feat: Add empirical delay to Transmodel API

Author: t2gran

application/src/ext/resources/org/opentripplanner/ext/apis/transmodel/custom-documentation-entur.properties

@@ -23,3 +23,6 @@ TariffZone.description=A **zone** used to define a zonal fare structure in a zon
   TariffZones are deprecated, please use FareZones. \
   \
   **TariffZone data will not be maintained from 1. MAY 2025 (Entur).**
+
+EmpiricalDelay.description.append=NOTE! This feature is under development and the percentiles used \
+  may change without notice. The percentiles are currently set to min=10 and max=90.

application/src/main/java/org/opentripplanner/apis/transmodel/TransmodelGraph.java

@@ -103,7 +103,8 @@ private static TransmodelRequestContext createRequestContext(
     return new TransmodelRequestContext(
       serverContext,
       serverContext.routingService(),
-      serverContext.transitService()
+      serverContext.transitService(),
+      serverContext.empiricalDelayService()
     );
   }
 

application/src/main/java/org/opentripplanner/apis/transmodel/TransmodelGraphQLSchemaFactory.java

@@ -104,6 +104,7 @@
 import org.opentripplanner.apis.transmodel.model.timetable.BookingArrangementType;
 import org.opentripplanner.apis.transmodel.model.timetable.DatedServiceJourneyQuery;
 import org.opentripplanner.apis.transmodel.model.timetable.DatedServiceJourneyType;
+import org.opentripplanner.apis.transmodel.model.timetable.EmpiricalDelayType;
 import org.opentripplanner.apis.transmodel.model.timetable.InterchangeType;
 import org.opentripplanner.apis.transmodel.model.timetable.ServiceJourneyType;
 import org.opentripplanner.apis.transmodel.model.timetable.TimetabledPassingTimeType;
@@ -292,7 +293,8 @@ private GraphQLSchema createDefault() {
       DatedServiceJourneyType.REF
     );
 
-    // Timetable
+    /* Timetable */
+
     GraphQLNamedOutputType ptSituationElementType = PtSituationElementType.create(
       authorityType,
       quayType,
@@ -315,6 +317,7 @@ private GraphQLSchema createDefault() {
       stopToStopGeometryType,
       ptSituationElementType
     );
+    GraphQLOutputType empiricalDealy = EmpiricalDelayType.create();
     GraphQLOutputType estimatedCallType = EstimatedCallType.create(
       bookingArrangementType,
       noticeType,
@@ -323,6 +326,7 @@ private GraphQLSchema createDefault() {
       ptSituationElementType,
       ServiceJourneyType.REF,
       DatedServiceJourneyType.REF,
+      empiricalDealy,
       dateTimeScalar
     );
 

application/src/main/java/org/opentripplanner/apis/transmodel/TransmodelRequestContext.java

@@ -1,23 +1,29 @@
 package org.opentripplanner.apis.transmodel;
 
+import javax.annotation.Nullable;
+import org.opentripplanner.ext.empiricaldelay.EmpiricalDelayService;
 import org.opentripplanner.routing.api.RoutingService;
 import org.opentripplanner.standalone.api.OtpServerRequestContext;
 import org.opentripplanner.transit.service.TransitService;
+import org.opentripplanner.utils.lang.Sandbox;
 
 public class TransmodelRequestContext {
 
   private final OtpServerRequestContext serverContext;
   private final RoutingService routingService;
   private final TransitService transitService;
+  private final @Nullable EmpiricalDelayService empiricalDelayService;
 
   public TransmodelRequestContext(
     OtpServerRequestContext serverContext,
     RoutingService routingService,
-    TransitService transitService
+    TransitService transitService,
+    EmpiricalDelayService empiricalDelayService
   ) {
     this.serverContext = serverContext;
     this.routingService = routingService;
     this.transitService = transitService;
+    this.empiricalDelayService = empiricalDelayService;
   }
 
   public OtpServerRequestContext getServerContext() {
@@ -31,4 +37,10 @@ public RoutingService getRoutingService() {
   public TransitService getTransitService() {
     return transitService;
   }
+
+  @Nullable
+  @Sandbox
+  public EmpiricalDelayService getEmpiricalDelayService() {
+    return empiricalDelayService;
+  }
 }

application/src/main/java/org/opentripplanner/apis/transmodel/model/siri/et/EstimatedCallType.java

@@ -20,6 +20,7 @@
 import org.opentripplanner.apis.transmodel.model.EnumTypes;
 import org.opentripplanner.apis.transmodel.model.framework.TransmodelDirectives;
 import org.opentripplanner.apis.transmodel.model.framework.TransmodelScalars;
+import org.opentripplanner.apis.transmodel.model.timetable.EmpiricalDelayType;
 import org.opentripplanner.apis.transmodel.support.GqlUtil;
 import org.opentripplanner.model.TripTimeOnDate;
 import org.opentripplanner.routing.alertpatch.StopCondition;
@@ -44,6 +45,7 @@ public static GraphQLObjectType create(
     GraphQLOutputType ptSituationElementType,
     GraphQLOutputType serviceJourneyType,
     GraphQLOutputType datedServiceJourneyType,
+    GraphQLOutputType empiricalDelayType,
     GraphQLScalarType dateTimeScalar
   ) {
     return GraphQLObjectType.newObject()
@@ -151,6 +153,16 @@ public static GraphQLObjectType create(
           })
           .build()
       )
+      .field(
+        GraphQLFieldDefinition.newFieldDefinition()
+          .name("empiricalDelay")
+          .type(empiricalDelayType)
+          .description(
+            "The typical delay for this trip on this day for this stop based on historical data."
+          )
+          .dataFetcher(EmpiricalDelayType::dataFetcherForTripTimeOnDate)
+          .build()
+      )
       .field(
         GraphQLFieldDefinition.newFieldDefinition()
           .name("timingPoint")

application/src/main/java/org/opentripplanner/apis/transmodel/model/timetable/EmpiricalDelayType.java

@@ -0,0 +1,71 @@
+package org.opentripplanner.apis.transmodel.model.timetable;
+
+import graphql.Scalars;
+import graphql.schema.DataFetchingEnvironment;
+import graphql.schema.GraphQLFieldDefinition;
+import graphql.schema.GraphQLObjectType;
+import graphql.schema.GraphQLTypeReference;
+import org.jspecify.annotations.Nullable;
+import org.opentripplanner.apis.transmodel.TransmodelRequestContext;
+import org.opentripplanner.ext.empiricaldelay.model.EmpiricalDelay;
+import org.opentripplanner.model.TripTimeOnDate;
+
+public class EmpiricalDelayType {
+
+  static final String NAME = "EmpiricalDelay";
+  public static final GraphQLTypeReference REF = new GraphQLTypeReference(NAME);
+
+  private EmpiricalDelayType() {}
+
+  public static GraphQLObjectType create() {
+    return GraphQLObjectType.newObject()
+      .name(NAME)
+      .description(
+        """
+        The empirical delay indicate how late a service journey is based on historic data. What the
+        min and max percentiles represent is set per deployment. For example, if set to p10 and p90,
+        then 10% of the arrival will have a delay less then the `minPercentile`, and 10% will have
+        a delay larger than the `maxPercentile` value.
+        """
+      )
+      .field(
+        GraphQLFieldDefinition.newFieldDefinition()
+          .name("minPercentile")
+          .description("Minimum percentile")
+          .type(Scalars.GraphQLInt)
+          .dataFetcher(e -> (empiricalDelay(e).minPercentile()))
+          .build()
+      )
+      .field(
+        GraphQLFieldDefinition.newFieldDefinition()
+          .name("maxPercentile")
+          .description("Maximum percentile")
+          .type(Scalars.GraphQLInt)
+          .dataFetcher(e -> (empiricalDelay(e).maxPercentile()))
+          .build()
+      )
+      .build();
+  }
+
+  @Nullable
+  public static EmpiricalDelay dataFetcherForTripTimeOnDate(DataFetchingEnvironment environment) {
+    TripTimeOnDate parent = environment.getSource();
+    TransmodelRequestContext ctx = environment.getContext();
+    var service = ctx.getEmpiricalDelayService();
+
+    if (parent == null || service == null) {
+      return null;
+    }
+    return service
+      .findEmpiricalDelay(
+        parent.getTrip().getId(),
+        parent.getServiceDay(),
+        parent.getStopPosition()
+      )
+      .orElse(null);
+  }
+
+  private static EmpiricalDelay empiricalDelay(DataFetchingEnvironment environment) {
+    return environment.getSource();
+  }
+}

application/src/main/resources/org/opentripplanner/apis/transmodel/schema.graphql

@@ -216,6 +216,19 @@ type Emission {
   co2: Float
 }
 
+"""
+The empirical delay indicate how late a service journey is based on historic data. What the
+min and max percentiles represent is set per deployment. For example, if set to p10 and p90,
+then 10% of the arrival will have a delay less then the `minPercentile`, and 10% will have
+a delay larger than the `maxPercentile` value.
+"""
+type EmpiricalDelay {
+  "Maximum percentile"
+  maxPercentile: Int
+  "Minimum percentile"
+  minPercentile: Int
+}
+
 "List of visits to quays as part of vehicle journeys. Updated with real time information where available"
 type EstimatedCall {
   "Actual time of arrival at quay. Updated from real time information if available."
@@ -234,6 +247,8 @@ type EstimatedCall {
   date: Date!
   datedServiceJourney: DatedServiceJourney
   destinationDisplay: DestinationDisplay
+  "The typical delay for this trip on this day for this stop based on historical data."
+  empiricalDelay: EmpiricalDelay
   "Expected time of arrival at quay. Updated with real time information if available. Will be null if an actualArrivalTime exists"
   expectedArrivalTime: DateTime!
   "Expected time of departure from quay. Updated with real time information if available. Will be null if an actualDepartureTime exists"

application/src/test/java/org/opentripplanner/apis/transmodel/mapping/TripRequestMapperTest.java

@@ -143,7 +143,8 @@ void setup() {
     context = new TransmodelRequestContext(
       otpServerRequestContext,
       otpServerRequestContext.routingService(),
-      otpServerRequestContext.transitService()
+      otpServerRequestContext.transitService(),
+      otpServerRequestContext.empiricalDelayService()
     );
   }
 

application/src/test/java/org/opentripplanner/apis/transmodel/model/timetable/EmpiricalDelayTypeTest.java

@@ -0,0 +1,33 @@
+package org.opentripplanner.apis.transmodel.model.timetable;
+
+import static com.google.common.truth.Truth.assertThat;
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+
+import graphql.Scalars;
+import graphql.schema.GraphQLObjectType;
+import org.junit.jupiter.api.Test;
+
+class EmpiricalDelayTypeTest {
+
+  private static final GraphQLObjectType subject = EmpiricalDelayType.create();
+
+  @Test
+  void create() {
+    var subject = EmpiricalDelayType.create();
+
+    assertEquals(EmpiricalDelayType.NAME, subject.getName());
+    assertThat(subject.getDescription()).isNotEmpty();
+
+    var minPercentile = subject.getFieldDefinition("minPercentile");
+    assertNotNull(minPercentile);
+    assertEquals(Scalars.GraphQLInt, minPercentile.getType());
+
+    var maxPercentile = subject.getFieldDefinition("maxPercentile");
+    assertNotNull(maxPercentile);
+    assertEquals(Scalars.GraphQLInt, maxPercentile.getType());
+  }
+
+  @Test
+  void dataFetcherForTripTimeOnDate() {}
+}