Calculate CO₂ emissions of itineraries

docs/BuildConfiguration.md

@@ -54,6 +54,9 @@ Sections follow that describe particular settings in more depth.
 |       source                                                             |    `uri`    | The unique URI pointing to the data file.                                                                                                                      | *Required* |                                   |  2.2  |
 | demDefaults                                                              |   `object`  | Default properties for DEM extracts.                                                                                                                           | *Optional* |                                   |  2.3  |
 |    [elevationUnitMultiplier](#demDefaults_elevationUnitMultiplier)       |   `double`  | Specify a multiplier to convert elevation units from source to meters.                                                                                         | *Optional* | `1.0`                             |  2.3  |
+| [digitransitEmissions](#digitransitEmissions)                            |   `object`  | Configure properties for emissions file.                                                                                                                       | *Optional* |                                   |   na  |
+|    carAvgCo2                                                             |  `integer`  | The average CO2 emissions of a car.                                                                                                                            | *Optional* | `170`                             |   na  |
+|    carAvgOccupancy                                                       |   `double`  | The average number of passengers in a car.                                                                                                                     | *Optional* | `1.3`                             |   na  |
 | [elevationBucket](#elevationBucket)                                      |   `object`  | Used to download NED elevation tiles from the given AWS S3 bucket.                                                                                             | *Optional* |                                   |   na  |
 | [fares](sandbox/Fares.md)                                                |   `object`  | Fare configuration.                                                                                                                                            | *Optional* |                                   |  2.0  |
 | gtfsDefaults                                                             |   `object`  | The gtfsDefaults section allows you to specify default properties for GTFS files.                                                                              | *Optional* |                                   |  2.3  |
@@ -697,6 +700,18 @@ values are defined in meters in the source data. If, for example, decimetres are
 in the source data, this should be set to 0.1.
 
 
+<h3 id="digitransitEmissions">digitransitEmissions</h3>
+
+**Since version:** `na` ∙ **Type:** `object` ∙ **Cardinality:** `Optional`   
+**Path:** / 
+
+Configure properties for emissions file.
+
+By specifying a URL to fetch emissions data, the program gains access to carbon dioxide (CO2)
+emissions associated with transportation modes. This data is then used
+to perform emission calculations for public transport modes and car travel.
+
+
 <h3 id="elevationBucket">elevationBucket</h3>
 
 **Since version:** `na` ∙ **Type:** `object` ∙ **Cardinality:** `Optional`   
@@ -1163,7 +1178,11 @@ case where this is not the case.
         "enabled" : true
       }
     }
-  ]
+  ],
+  "digitransitEmissions" : {
+    "carAvgCo2PerKm" : 170,
+    "carAvgOccupancy" : 1.3
+  }
 }
 ```
 

docs/Configuration.md

@@ -235,6 +235,7 @@ Here is a list of all features which can be toggled on/off and their default val
 | `TransferConstraints`                | Enforce transfers to happen according to the _transfers.txt_(GTFS) and Interchanges(NeTEx). Turing this _off_ will increase the routing performance a little.                                             |         ✓️         |         |
 | `ActuatorAPI`                        | Endpoint for actuators (service health status).                                                                                                                                                           |                    |    ✓️   |
 | `AsyncGraphQLFetchers`               | Whether the @async annotation in the GraphQL schema should lead to the fetch being executed asynchronously. This allows batch or alias queries to run in parallel at the cost of consuming extra threads. |                    |         |
+| `Co2Emissions`                       | Enable emissions calculation and data handling.                                                                                                                                                           |                    |    ✓️   |
 | `DataOverlay`                        | Enable usage of data overlay when calculating costs for the street network.                                                                                                                               |                    |    ✓️   |
 | `FaresV2`                            | Enable import of GTFS-Fares v2 data.                                                                                                                                                                      |                    |    ✓️   |
 | `FlexRouting`                        | Enable FLEX routing.                                                                                                                                                                                      |                    |    ✓️   |

docs/sandbox/DigitransitEmissions.md

@@ -0,0 +1,61 @@
+# Digitransit CO2 Emissions calculation
+
+## Contact Info
+
+- Digitransit Team
+
+## Documentation
+
+Graph build import of CO2 Emissions from GTFS data sets (through custom emissions.txt extension)
+and the ability to attach them to itineraries by Digitransit team.
+The emissions are represented in grams per kilometer (g/Km) unit.
+
+Emissions data is located in an emissions.txt file within a gtfs package and has the following properties:
+
+`route_id`: route id
+
+`avg_co2_per_vehicle_per_km`: Average carbon dioxide equivalent value for the vehicles used on the route at grams/Km units.
+
+`avg_passenger_count`: Average passenger count for the vehicles on the route.
+
+For example:
+```csv
+route_id,avg_co2_per_vehicle_per_km,avg_passenger_count
+1234,123,20
+2345,0,0
+```
+
+Emissions data is loaded from the gtfs package and embedded into the graph during the build process.
+
+
+### Configuration
+To enable this functionality, you need to enable the "Co2Emissions"  feature in the
+`otp-config.json` file. 
+
+```json
+//otp-config.json
+{
+  "Co2Emissions": true
+}
+```
+Include the `digitransitEmissions` object in the
+`build-config.json` file. The `digitransitEmissions` object should contain parameters called
+`carAvgCo2PerKm` and `carAvgOccupancy`. The `carAvgCo2PerKm` provides the average emissions value for a car and
+the `carAvgOccupancy` provides the average number of passengers in a car.
+
+```json
+//build-config.json
+{
+  "digitransitEmissions": {
+    "carAvgCo2PerKm": 170,
+    "carAvgOccupancy": 1.3
+  }
+}
+```
+## Changelog
+
+### OTP 2.5
+
+- Initial implementation of the emissions calculation.
+
+

src/ext-test/java/org/opentripplanner/ext/emissions/digitransit/EmissionsServiceTest.java

@@ -0,0 +1,189 @@
+package org.opentripplanner.ext.emissions.digitransit;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNull;
+import static org.opentripplanner.transit.model._data.TransitModelForTest.id;
+
+import java.time.OffsetDateTime;
+import java.time.ZonedDateTime;
+import java.time.temporal.ChronoUnit;
+import java.util.ArrayList;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.opentripplanner._support.time.ZoneIds;
+import org.opentripplanner.ext.digitransitemissions.DigitransitEmissions;
+import org.opentripplanner.ext.digitransitemissions.DigitransitEmissionsService;
+import org.opentripplanner.model.StopTime;
+import org.opentripplanner.model.plan.Itinerary;
+import org.opentripplanner.model.plan.Leg;
+import org.opentripplanner.model.plan.ScheduledTransitLeg;
+import org.opentripplanner.model.plan.StreetLeg;
+import org.opentripplanner.street.search.TraverseMode;
+import org.opentripplanner.transit.model._data.TransitModelForTest;
+import org.opentripplanner.transit.model.basic.TransitMode;
+import org.opentripplanner.transit.model.framework.Deduplicator;
+import org.opentripplanner.transit.model.framework.FeedScopedId;
+import org.opentripplanner.transit.model.organization.Agency;
+import org.opentripplanner.transit.model.timetable.Trip;
+import org.opentripplanner.transit.model.timetable.TripTimes;
+
+class EmissionsServiceTest {
+
+  private DigitransitEmissionsService eService;
+
+  static final ZonedDateTime TIME = OffsetDateTime
+    .parse("2023-07-20T17:49:06+03:00")
+    .toZonedDateTime();
+
+  private static final Agency subject = Agency
+    .of(TransitModelForTest.id("F:1"))
+    .withName("Foo_CO")
+    .withTimezone("Europe/Helsinki")
+    .build();
+
+  @BeforeEach
+  void SetUp() {
+    Map<FeedScopedId, DigitransitEmissions> digitransitEmissions = new HashMap<>();
+    digitransitEmissions.put(
+      new FeedScopedId("F", "1"),
+      DigitransitEmissions.newDigitransitEmissions(0.12, 12)
+    );
+    digitransitEmissions.put(
+      new FeedScopedId("F", "2"),
+      DigitransitEmissions.newDigitransitEmissions(0, 0)
+    );
+    this.eService = new DigitransitEmissionsService(digitransitEmissions, 0.131);
+  }
+
+  @Test
+  void testGetEmissionsForItinerary() {
+    var stopOne = TransitModelForTest.stopForTest("1:stop1", 60, 25);
+    var stopTwo = TransitModelForTest.stopForTest("1:stop1", 61, 25);
+    var stopThree = TransitModelForTest.stopForTest("1:stop1", 62, 25);
+    var stopPattern = TransitModelForTest.stopPattern(stopOne, stopTwo, stopThree);
+    var route = TransitModelForTest.route(id("1")).build();
+    List<Leg> legs = new ArrayList<>();
+    var pattern = TransitModelForTest.tripPattern("1", route).withStopPattern(stopPattern).build();
+    var stoptime = new StopTime();
+    var stoptimes = new ArrayList<StopTime>();
+    stoptimes.add(stoptime);
+    var trip = Trip
+      .of(FeedScopedId.parse("FOO:BAR"))
+      .withMode(TransitMode.BUS)
+      .withRoute(route)
+      .build();
+    var leg = new ScheduledTransitLeg(
+      new TripTimes(trip, stoptimes, new Deduplicator()),
+      pattern,
+      0,
+      2,
+      TIME,
+      TIME.plusMinutes(10),
+      TIME.toLocalDate(),
+      ZoneIds.BERLIN,
+      null,
+      null,
+      100,
+      null
+    );
+    legs.add(leg);
+    Itinerary i = new Itinerary(legs);
+    assertEquals(2223.902, eService.getEmissionsForItinerary(i));
+  }
+
+  @Test
+  void testGetEmissionsForCarRoute() {
+    List<Leg> legs = new ArrayList<>();
+    var leg = StreetLeg
+      .create()
+      .withMode(TraverseMode.CAR)
+      .withDistanceMeters(214.4)
+      .withStartTime(TIME)
+      .withEndTime(TIME.plus(1, ChronoUnit.HOURS))
+      .build();
+    legs.add(leg);
+    Itinerary i = new Itinerary(legs);
+    assertEquals(28.0864, eService.getEmissionsForItinerary(i));
+  }
+
+  @Test
+  void testNoEmissionsForFeedWithoutEmissionsConfigured() {
+    Map<FeedScopedId, DigitransitEmissions> digitransitEmissions = new HashMap<>();
+    digitransitEmissions.put(
+      new FeedScopedId("G", "1"),
+      DigitransitEmissions.newDigitransitEmissions(0.12, 12)
+    );
+    this.eService = new DigitransitEmissionsService(digitransitEmissions, 0.131);
+
+    var route = TransitModelForTest.route(id("1")).withAgency(subject).build();
+    List<Leg> legs = new ArrayList<>();
+    var pattern = TransitModelForTest
+      .tripPattern("1", route)
+      .withStopPattern(TransitModelForTest.stopPattern(3))
+      .build();
+    var stoptime = new StopTime();
+    var stoptimes = new ArrayList<StopTime>();
+    stoptimes.add(stoptime);
+    var trip = Trip
+      .of(FeedScopedId.parse("FOO:BAR"))
+      .withMode(TransitMode.BUS)
+      .withRoute(route)
+      .build();
+    var leg = new ScheduledTransitLeg(
+      new TripTimes(trip, stoptimes, new Deduplicator()),
+      pattern,
+      0,
+      2,
+      TIME,
+      TIME.plusMinutes(10),
+      TIME.toLocalDate(),
+      ZoneIds.BERLIN,
+      null,
+      null,
+      100,
+      null
+    );
+    legs.add(leg);
+    Itinerary i = new Itinerary(legs);
+    assertNull(eService.getEmissionsForItinerary(i));
+  }
+
+  @Test
+  void testZeroEmissionsForItineraryWithZeroEmissions() {
+    var stopOne = TransitModelForTest.stopForTest("1:stop1", 60, 25);
+    var stopTwo = TransitModelForTest.stopForTest("1:stop1", 61, 25);
+    var stopThree = TransitModelForTest.stopForTest("1:stop1", 62, 25);
+    var stopPattern = TransitModelForTest.stopPattern(stopOne, stopTwo, stopThree);
+    var route = TransitModelForTest.route(id("2")).build();
+    List<Leg> legs = new ArrayList<>();
+    var pattern = TransitModelForTest.tripPattern("1", route).withStopPattern(stopPattern).build();
+    var stoptime = new StopTime();
+    var stoptimes = new ArrayList<StopTime>();
+    stoptimes.add(stoptime);
+    var trip = Trip
+      .of(FeedScopedId.parse("FOO:BAR"))
+      .withMode(TransitMode.BUS)
+      .withRoute(route)
+      .build();
+    var leg = new ScheduledTransitLeg(
+      new TripTimes(trip, stoptimes, new Deduplicator()),
+      pattern,
+      0,
+      2,
+      TIME,
+      TIME.plusMinutes(10),
+      TIME.toLocalDate(),
+      ZoneIds.BERLIN,
+      null,
+      null,
+      100,
+      null
+    );
+    legs.add(leg);
+    Itinerary i = new Itinerary(legs);
+    assertEquals(0, eService.getEmissionsForItinerary(i));
+  }
+}

src/ext-test/java/org/opentripplanner/ext/transmodelapi/mapping/TripRequestMapperTest.java

@@ -24,6 +24,8 @@
 import org.junit.jupiter.params.ParameterizedTest;
 import org.junit.jupiter.params.provider.Arguments;
 import org.opentripplanner._support.time.ZoneIds;
+import org.opentripplanner.ext.digitransitemissions.DefaultEmissionsService;
+import org.opentripplanner.ext.digitransitemissions.DefaultEmissionsServiceRepository;
 import org.opentripplanner.ext.transmodelapi.TransmodelRequestContext;
 import org.opentripplanner.graph_builder.issue.api.DataImportIssueStore;
 import org.opentripplanner.model.calendar.CalendarServiceData;
@@ -125,6 +127,7 @@ public class TripRequestMapperTest implements PlanTestConstants {
           new DefaultWorldEnvelopeService(new DefaultWorldEnvelopeRepository()),
           new DefaultVehiclePositionService(),
           new DefaultVehicleRentalService(),
+          new DefaultEmissionsService(new DefaultEmissionsServiceRepository()),
           RouterConfig.DEFAULT.flexConfig(),
           List.of(),
           null

src/ext/java/org/opentripplanner/ext/digitransitemissions/DefaultEmissionsService.java

@@ -0,0 +1,25 @@
+package org.opentripplanner.ext.digitransitemissions;
+
+import jakarta.inject.Inject;
+import java.io.Serializable;
+import java.util.Optional;
+import org.opentripplanner.model.plan.Itinerary;
+
+public class DefaultEmissionsService implements Serializable, EmissionsService {
+
+  private EmissionsServiceRepository repository = null;
+
+  @Inject
+  public DefaultEmissionsService(EmissionsServiceRepository repository) {
+    this.repository = repository;
+  }
+
+  @Override
+  public Double getEmissionsForItinerary(Itinerary itinerary) {
+    Optional<DigitransitEmissionsService> service = repository.retrieveEmissionsService();
+    if (service.isPresent()) {
+      return service.get().getEmissionsForItinerary(itinerary);
+    }
+    return null;
+  }
+}

src/ext/java/org/opentripplanner/ext/digitransitemissions/DefaultEmissionsServiceRepository.java

@@ -0,0 +1,26 @@
+package org.opentripplanner.ext.digitransitemissions;
+
+import jakarta.inject.Inject;
+import jakarta.inject.Singleton;
+import java.io.Serializable;
+import java.util.Optional;
+import javax.annotation.Nonnull;
+
+@Singleton
+public class DefaultEmissionsServiceRepository implements EmissionsServiceRepository, Serializable {
+
+  private volatile DigitransitEmissionsService emissionsService = null;
+
+  @Inject
+  public DefaultEmissionsServiceRepository() {}
+
+  @Override
+  public Optional<DigitransitEmissionsService> retrieveEmissionsService() {
+    return Optional.ofNullable(emissionsService);
+  }
+
+  @Override
+  public void saveEmissionsService(@Nonnull DigitransitEmissionsService emissionsService) {
+    this.emissionsService = emissionsService;
+  }
+}