Calculate CO₂ emissions of itineraries

doc-templates/Emissions.md

@@ -0,0 +1,54 @@
+# CO₂ Emissions calculation
+
+## Contact Info
+
+- Digitransit Team
+
+## Documentation
+
+Graph build import of CO₂ 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 columns:
+
+`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
+3456,12.3,20.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 `emissions` object in the
+`build-config.json` file. The `emissions` object should contain parameters called
+`carAvgCo2PerKm` and `carAvgOccupancy`. The `carAvgCo2PerKm` provides the average emissions value for a car in g/km and
+the `carAvgOccupancy` provides the average number of passengers in a car.
+
+<!-- INSERT: config -->
+
+## Changelog
+
+### OTP 2.5
+
+- Initial implementation of the emissions calculation.

docs/BuildConfiguration.md

@@ -55,6 +55,9 @@ Sections follow that describe particular settings in more depth.
 | 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  |
 | [elevationBucket](#elevationBucket)                                      |   `object`  | Used to download NED elevation tiles from the given AWS S3 bucket.                                                                                             | *Optional* |                                   |   na  |
+| [emissions](#emissions)                                                  |   `object`  | Emissions configuration.                                                                                                                                       | *Optional* |                                   |   na  |
+|    carAvgCo2PerKm                                                        |  `integer`  | The average CO₂ emissions of a car in grams per kilometer.                                                                                                     | *Optional* | `170`                             |   na  |
+|    carAvgOccupancy                                                       |   `double`  | The average number of passengers in a car.                                                                                                                     | *Optional* | `1.3`                             |   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  |
 |    blockBasedInterlining                                                 |  `boolean`  | Whether to create stay-seated transfers in between two trips with the same block id.                                                                           | *Optional* | `true`                            |  2.3  |
@@ -723,6 +726,18 @@ for the next graph build operation. You should add the `--cache <directory>` com
 to specify your NED tile cache location.
 
 
+<h3 id="emissions">emissions</h3>
+
+**Since version:** `na` ∙ **Type:** `object` ∙ **Cardinality:** `Optional`   
+**Path:** / 
+
+Emissions configuration.
+
+By specifying the average CO₂ emissions of a car in grams per kilometer as well as
+the average number of passengers in a car the program is able to to perform emission
+calculations for car travel.
+
+
 <h3 id="gd_discardMinTransferTimes">discardMinTransferTimes</h3>
 
 **Since version:** `2.3` ∙ **Type:** `boolean` ∙ **Cardinality:** `Optional` ∙ **Default value:** `false`   
@@ -1163,7 +1178,11 @@ case where this is not the case.
         "enabled" : true
       }
     }
-  ]
+  ],
+  "emissions" : {
+    "carAvgCo2PerKm" : 170,
+    "carAvgOccupancy" : 1.3
+  }
 }
 ```
 

docs/Configuration.md

@@ -236,6 +236,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 the emissions sandbox module.                                                                                                                                                                      |                    |    ✓️   |
 | `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/Emissions.md

@@ -0,0 +1,79 @@
+# CO₂ Emissions calculation
+
+## Contact Info
+
+- Digitransit Team
+
+## Documentation
+
+Graph build import of CO₂ 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 columns:
+
+`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
+3456,12.3,20.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 `emissions` object in the
+`build-config.json` file. The `emissions` object should contain parameters called
+`carAvgCo2PerKm` and `carAvgOccupancy`. The `carAvgCo2PerKm` provides the average emissions value for a car in g/km and
+the `carAvgOccupancy` provides the average number of passengers in a car.
+
+<!-- config BEGIN -->
+<!-- NOTE! This section is auto-generated. Do not change, change doc in code instead. -->
+
+### Example configuration
+
+```JSON
+// build-config.json
+{
+  "emissions" : {
+    "carAvgCo2PerKm" : 170,
+    "carAvgOccupancy" : 1.3
+  }
+}
+```
+### Overview
+
+| Config Parameter |    Type   | Summary                                                    |  Req./Opt. | Default Value | Since |
+|------------------|:---------:|------------------------------------------------------------|:----------:|---------------|:-----:|
+| carAvgCo2PerKm   | `integer` | The average CO₂ emissions of a car in grams per kilometer. | *Optional* | `170`         |   na  |
+| carAvgOccupancy  |  `double` | The average number of passengers in a car.                 | *Optional* | `1.3`         |   na  |
+
+
+### Details
+
+
+<!-- config END -->
+
+## Changelog
+
+### OTP 2.5
+
+- Initial implementation of the emissions calculation.

src/ext-test/java/org/opentripplanner/ext/emissions/Co2EmissionsDataReaderTest.java

@@ -0,0 +1,38 @@
+package org.opentripplanner.ext.emissions;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+
+import java.io.File;
+import org.junit.jupiter.api.Test;
+import org.opentripplanner.graph_builder.issue.service.DefaultDataImportIssueStore;
+import org.opentripplanner.test.support.ResourceLoader;
+
+public class Co2EmissionsDataReaderTest {
+
+  private static final ResourceLoader RES = ResourceLoader.of(Co2EmissionsDataReaderTest.class);
+  private static final File CO2_GTFS_ZIP = RES.file("emissions-test-gtfs.zip");
+  private static final File CO2_GTFS = RES.file("emissions-test-gtfs/");
+  private static final File INVALID_CO2_GTFS = RES.file("emissions-invalid-test-gtfs/");
+
+  private Co2EmissionsDataReader co2EmissionsDataReader = new Co2EmissionsDataReader(
+    new DefaultDataImportIssueStore()
+  );
+
+  @Test
+  void testCo2EmissionsZipDataReading() {
+    var emissions = co2EmissionsDataReader.readGtfsZip(CO2_GTFS_ZIP);
+    assertEquals(6, emissions.size());
+  }
+
+  @Test
+  void testCo2EmissionsDataReading() {
+    var emissions = co2EmissionsDataReader.readGtfs(CO2_GTFS);
+    assertEquals(6, emissions.size());
+  }
+
+  @Test
+  void testInvalidCo2EmissionsDataReading() {
+    var emissions = co2EmissionsDataReader.readGtfs(INVALID_CO2_GTFS);
+    assertEquals(0, emissions.size());
+  }
+}

src/ext-test/java/org/opentripplanner/ext/emissions/EmissionsTest.java

@@ -0,0 +1,173 @@
+package org.opentripplanner.ext.emissions;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+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.framework.model.Grams;
+import org.opentripplanner.model.StopTime;
+import org.opentripplanner.model.plan.Itinerary;
+import org.opentripplanner.model.plan.ScheduledTransitLeg;
+import org.opentripplanner.model.plan.ScheduledTransitLegBuilder;
+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 EmissionsTest {
+
+  private DefaultEmissionsService eService;
+  private EmissionsFilter emissionsFilter;
+
+  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, Double> emissions = new HashMap<>();
+    emissions.put(new FeedScopedId("F", "1"), (0.12 / 12));
+    emissions.put(new FeedScopedId("F", "2"), 0.0);
+    EmissionsDataModel emissionsDataModel = new EmissionsDataModel(emissions, 0.131);
+    this.eService = new DefaultEmissionsService(emissionsDataModel);
+    this.emissionsFilter = new EmissionsFilter(eService);
+  }
+
+  @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();
+    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 ScheduledTransitLegBuilder<>()
+      .withTripTimes(new TripTimes(trip, stoptimes, new Deduplicator()))
+      .withTripPattern(pattern)
+      .withBoardStopIndexInPattern(0)
+      .withAlightStopIndexInPattern(2)
+      .withStartTime(TIME)
+      .withEndTime(TIME.plusMinutes(10))
+      .withServiceDate(TIME.toLocalDate())
+      .withZoneId(ZoneIds.BERLIN)
+      .build();
+    Itinerary i = new Itinerary(List.of(leg));
+    assertEquals(
+      new Grams(2223.902),
+      emissionsFilter.filter(List.of(i)).get(0).getEmissionsPerPerson().getCo2()
+    );
+  }
+
+  @Test
+  void testGetEmissionsForCarRoute() {
+    var leg = StreetLeg
+      .create()
+      .withMode(TraverseMode.CAR)
+      .withDistanceMeters(214.4)
+      .withStartTime(TIME)
+      .withEndTime(TIME.plus(1, ChronoUnit.HOURS))
+      .build();
+    Itinerary i = new Itinerary(List.of(leg));
+    assertEquals(
+      new Grams(28.0864),
+      emissionsFilter.filter(List.of(i)).get(0).getEmissionsPerPerson().getCo2()
+    );
+  }
+
+  @Test
+  void testNoEmissionsForFeedWithoutEmissionsConfigured() {
+    Map<FeedScopedId, Double> emissions = new HashMap<>();
+    emissions.put(new FeedScopedId("G", "1"), (0.12 / 12));
+    EmissionsDataModel emissionsDataModel = new EmissionsDataModel(emissions, 0.131);
+
+    this.eService = new DefaultEmissionsService(emissionsDataModel);
+    this.emissionsFilter = new EmissionsFilter(this.eService);
+
+    var route = TransitModelForTest.route(id("1")).withAgency(subject).build();
+    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 ScheduledTransitLegBuilder<>()
+      .withTripTimes(new TripTimes(trip, stoptimes, new Deduplicator()))
+      .withTripPattern(pattern)
+      .withBoardStopIndexInPattern(0)
+      .withAlightStopIndexInPattern(2)
+      .withStartTime(TIME)
+      .withEndTime(TIME.plusMinutes(10))
+      .withServiceDate(TIME.toLocalDate())
+      .withZoneId(ZoneIds.BERLIN)
+      .build();
+    Itinerary i = new Itinerary(List.of(leg));
+    assertEquals(null, emissionsFilter.filter(List.of(i)).get(0).getEmissionsPerPerson());
+  }
+
+  @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();
+    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 ScheduledTransitLegBuilder<>()
+      .withTripTimes(new TripTimes(trip, stoptimes, new Deduplicator()))
+      .withTripPattern(pattern)
+      .withBoardStopIndexInPattern(0)
+      .withAlightStopIndexInPattern(2)
+      .withStartTime(TIME)
+      .withEndTime(TIME.plusMinutes(10))
+      .withServiceDate(TIME.toLocalDate())
+      .withZoneId(ZoneIds.BERLIN)
+      .build();
+    Itinerary i = new Itinerary(List.of(leg));
+    assertEquals(
+      new Grams(0.0),
+      emissionsFilter.filter(List.of(i)).get(0).getEmissionsPerPerson().getCo2()
+    );
+  }
+}