Stop Times Mod for Spotfire®

The stop times mod is a graphical representation of stops for a vehicle journey with scheduled, estimated times and delays. It has application in public transportation and logistics use cases.

Data Requirements

Every mod handles missing, corrupted and/or inconsistent data in different ways. It is advised to always review how the data is visualized.

To make the stop times mod work properly, the underlying data must be formatted in a certain way. The data must exist in a single table with one row per stop that include the name, scheduled arrival DateTime and scheduled departure DateTime, estimated arrival DateTime and estimated departure DateTime and optionally actual arrival DateTime and actual departure DateTime.

Setting Up the Mod

In this example dataset, we have 9 columns: stop, status, planArrival, planDepart, estArrival, estDepart, arrival, depart, name

Specify the data table with marking and filters as usual. The chart supports marking data; you can set the Marking property as desired.

Then the Stop Times visualizations will be configured with the following settings:

Name

The display name for the stop on the diagram. In our use case, the 'name' column. 

Sequence by

Determines what order the stops will be rendered. In our use case, the 'stop' column.

Graphic type

Can be left blank for most uses. This will render each row as a leading line with a circle at the end of it. If your data has separate rows for lines and circles, you can set this value to 'line' or 'circle' to render as that graphic. 

Note: The visualization expects that there will be alternating circle and line rows, and the set should always start and end with a circle.

Sched Arr & Sched Dep

Optional. Represent the scheduled arrival and departure times for a stop. These must be DateTime columns. The first stop in a trip should have a null value for the Sched Arr and the last stop should have a null value for the Sched Dep. In our use case, the 'planArrival' and 'planDepart' columns.

Est Arr & Est Dep

Optional. Represent the estimated arrival and departure times for a stop. These must be DateTime columns. The first stop in a trip should have a null value for the Est Arr and the last stop should have a null value for the Est Dep. In our use case, the 'estArrival' and 'estDepart' columns.

Act Arr & Act Dep

Optional. Represent the estimated arrival and departure times for a stop. These must be DateTime columns. The first stop in a trip should have a null value for the Est Arr and the last stop should have a null value for the Est Dep. In our use case, the 'arrival' and 'depart' columns.

Status

Optional. Should be a categorical expression so you may need to surround with < and >. This configuration will determine the color of the stops on the diagram. See the Configuration section below for details. This configuration must evaluate to one of the following values:

• pending: the default state
• done: the stop has been passed (departed)
• next: the stop will be the next marked as active (on approach)
• active: the stop is currently active (arrived)

This will likely take the form of an expression in order to convert a combination of the stop status and the actual times into the appropriate status value. For example:

 <If([status]="Departed","done",If([status]="In Transit","next",If([status]="Arrived" and [plannedDepartureDateTime] is not null,"active",If([status]="Arrived" and [plannedDepartureDateTime] is null,"done","pending"))))>

At this point the diagram should render.

Configuring the Mod

Some additional configuration for the mod can be completed using an included text editor. To access the editor, double-click on the center of the plot area. This will present a box titled Mod Configuration and an editor that will contain the configuration in JSON format. This will be pre-populated with the required structure.

{
  "delays": {
    "calcEstArrDelay":true,
    "calcEstDepDelay":true,
    "calcActArrDelay":true,
    "calcActDepDelay":true
  },
  "colors": {
    "pending": "grey",
    "next": "darkorange",
    "active": "darkorange",
    "done": "dodgerblue"
  }
}

The delays section includes flags to indicate whether or not the delay time in minutes will be calculated for each of estimated and actual arrivals and departures. If you have no scheduled times then these values will be omitted by default anyway.

The colors section indicates the color for each line or circle that will be set based on the Status property. These can be any valid HTML color name, or a valid color in hex, for example #FFFFFF for white.

Using the Mod

Once the mod is configured it will render a diagram of stops in sequence. The lines and circles will be colored based on the configured Status and the colors defined in the additional configuration.

For the default Graphic type which is a leading line with a circle, the following status colors will apply:

• pending: both the line and circle will be colored the same as pending
• done: both the line and circle will be colored the same as done
• next: the line will be colored as next and the circle will remain pending
• active: the line will be colored as done and the circle will be colored as active

For the Graphic type of line or circle each row will render as either a line or a circle. In this case the color will apply to the graphic based on the specified Status. 

If the Status is not set, or set to something other than the 4 required values, then the lines and circles will be colored black.

Each stop will have a block of times associated with it.

• The left column is arrival times. This will be empty for the first stop
• The right column is departure times. This will be empty for the last stop.

Within each column there can be scheduled, estimated, and/or actual times, depending on configuration. All times are optional.

• The first time is the scheduled arrival or departure time
• The second time is the estimated arrival or departure time. This will be rendered in italic.
• The third time is the actual arrival or departure time. This will be rendered in bold.

For estimated and actual times, a delay delta is displayed by default and is calculated based on scheduled times. If there are no scheduled times then the delay delta will not be present. The delay delta can be hidden using the additional configuration panel.

Marking

If marking is enabled, the stop name will be highlighted with the color of the marking if selected. You can mark and unmark stops in the diagram by clicking on the stop text block. You can select or toggle multiple markings by holding down the CTRL key, just like in a regular Spotfire table. The mod does not support using drag marking.

In a terminal window:

• npm install
• npm start

In a new terminal window:

• npm run server

• Spotfire Community Exchange: A safe and trusted place to discover ready-to-use Mods
• Developer Documentation: Introduction and tutorials for Mods developers
• Mods code examples on GitHub: A public repository for example projects