Dynamic attributes associated to KPI Templates

When using KPI APIs, you need to be managing well-formed JSON objects.

Some KPI Templates (see the complete list → Optima KPI methodology) require some mandatory dynamic attributes, as indicated in the table:

KPI Attribute

 Description

KPI Templates requiring

the Dynamic KPI Attribute

Delay

Integer type.

It contains the delay interval, expressed in seconds.

The possible values are:

  • 60 (1 minute).
  • 120 (2 minutes).
  • 180 (3 minutes).
  • 240 (4 minutes).
  • 300 (5 minutes).
  • 600 (10 minutes).
  • 900 (15 minutes).
  • 1800 (30 minutes).
  • 2700 (45 minutes).
  • 3600 (60 minutes).

Example:

"dynamicAttributes": [
    {
        "code": "delay",
        "value": "120"
    }]

The templates listed require the attribute delay:

  • 1 - Runs in delay

externality

String type.

It contains the externality accounted for.

The possible values are:

  • Carbon Dioxide
  • Carbon Monoxide
  • Nitrogen Oxide
  • Hydrocarbons
  • Particulate Matter
  • Fuel Consumption

Example:

"dynamicAttributes": [
    {
        "code": "externality",
        "value": "Carbon Dioxide"
    }]

For future use

forecast

Integer type.

It contains the forecast interval, expressed in seconds.

The possible values are:

  • 0 (equivalent to the current forecast)
  • 900 (15 minutes).
  • 1800 (30 minutes).
  • 2700 (45 minutes).
  • 3600 (60 minutes).

Example:

"dynamicAttributes": [
    {
        "code": "fore",
        "value": "1800"
    }]

The templates listed require the attribute fore:

  • 9 - Average User Speed
  • 10 - Average Network Speed
  • 11 - Number of Vehicles on the Network
  • 12 - Network Vehicle Output
  • 13 - Network Vehicle Input
  • 14 - Total Travel Time
  • 15 - Production
  • 21 - Model forecast quality
  • 24 - Average User Speed
  • 25 - Average Network Speed
  • 26 - Number of Vehicles on the Network
  • 27 - Network Vehicle Output
  • 28 - Network Vehicle Input
  • 29 - Total Travel Time
  • 30 - Production
  • 33 - Path Travel Time
  • 34 - Path Travel Time
  • 43 - Model Forecast Quality (Speed)

ML_forecast

Integer type.

It contains the time forecast interval, which is expressed in seconds.

The possible values are:

  • 900
  • 1800
  • 2700
  • 3600

The templates listed require the attribute ML Forecast horizon:

  • 35 - ML Forecast: Congestion Index
  • 36 - ML Forecast: Traffic Jam
  • 37 - ML Forecast: Network Congestion Share
  • 46 - ML Forecast: Percentage of Streets below Error Threshold (Speed)
  • 47 - ML Forecast: Percentage of Streets below Error Threshold (Flow)

interval

Integer type.

It contains the time interval, which is expressed in minutes and formatted as hh:mm:ss.

The harmonized values (speed or flow) are the values with the starting instant of validity falling into interval.

The possible values are:

  • 00:05:00
  • 00:10:00
  • 00:15:00
  • 00:30:00
  • 00:45:00
  • 01:00:00

Example:

"dynamicAttributes": [
    {
        "code": "interval",
        "value": "00:15:00"
    }]

The templates listed require the attribute interval:

  • 16 - Harmonizer: Average Speed Detection
  • 17 - Harmonizer: Average Flow Detection
  • 18 - Harmonizer: Count Speed Detections
  • 19 - Harmonizer: Count Flow Detections

only in queue

String type.

The possible values are:

  • nveh: this value is associated to All vehicles.
  • nveh*quen: this value is associated to Only vehicle in queue.

Example:

"dynamicAttributes": [
    {
        "code": "onlyQueue",
        "value": "All vehicles"
    }]

The templates listed require the attribute onlyQueue:

  • 11 - Number of Vehicles on the Network
  • 26 - Number of Vehicles on the Network

Point

Real type.

The position of the public transport vehicle.

 Not applicable.

shortTermForecastKpi

Boolean type.

It contains the indication about how the KPI is handled in the Short-Term Forecast (STF) template.

If:

  • true: the KPI is evaluated for all runs of STF, for all scenarios associated to the KPI. In this case, the KPI is constantly monitored.

    Important:   Each KPI evaluation adds a computational overhead after the STF simulation. This overhead is associated to any single evaluation, (usually, 5 minutes).

  • false: is only created as a KPI instance, but not constantly evaluated. The KPI is available:

    • In the list of KPIs to be associated to scenarios, for on-demand (spot) evaluations.

    • For the alternative scenario simulations (decision support), provided by STF in the context of real-time scenario evaluations.

Example:

"dynamicAttributes": [
    {
        "code": "shortTermForecastKpi",
        "value": "true"
    }]

The templates listed require the attribute shortTermForecastKpi:

  • 9 - Average User Speed
  • 10 - Average Network Speed
  • 11 - Number of Vehicles on the Network
  • 12 - Network Vehicle Output
  • 13 - Network Vehicle Input
  • 14 - Total Travel Time
  • 15 - Production
  • 20 - Model quality from base
  • 21 - Model forecast quality
  • 33 - Path Travel Time
  • 34 - Path Travel Time
  • 42 - Model Forecast Quality from Base (Speed)
  • 43 - Model Forecast Quality (Speed)

Micro forecast horizon

Integer type.

It contains the forecast interval, expressed in minutes.

The possible values are:

  • 0 minutes (now)
  • 5 minutes.
  • 10 minutes.
  • 15 minutes.
  • 20 minutes.
  • 25 minutes.
  • 30 minutes.
  • 35 minutes.
  • 40 minutes.
  • 45 minutes.
  • 50 minutes.
  • 55 minutes.

The templates listed require the attribute Micro forecast horizon:

  • 31 - PTV OPTIMA MICRO: Travel Times
  • 32 - PTV OPTIMA MICRO: Total Vehicle Times

Tsys

Integer type.

Transport system value.

 Not applicable.

SFQI_threshold

Real type.

It contains the threshold value for the forecast speed quality indicator.

The possible values are:

  • 0.10 (alias SFQI_speed_0.1)
  • 0.15 (alias SFQI_speed_0.15)
  • 0.20 (alias SFQI_speed_0.2)
  • 0.25 (alias SFQI_speed_0.25)
  • 0.30 (alias SFQI_speed_0.3)
  • 0.35 (alias SFQI_speed_0.35)
  • 0.40 (alias SFQI_speed_0.4)
  • 0.45 (alias SFQI_speed_0.45)
  • 0.50 (alias SFQI_speed_0.5)
  • 0.55 (alias SFQI_speed_0.55)
  • 0.60 (alias SFQI_speed_0.6)

For details on SFQI, → Forecast Quality Indicators (FQI).

The templates listed require the attribute MAPE_speed_threshold:

  • 45 - Percentage of Links below Error Threshold (Speed)
  • 46 - ML Forecast: Percentage of Streets below Error Threshold (Speed)

GEH_flow_threshold:

Real type.

It contains the threshold value for the forecast flow quality indicator.

The possible values are:

  • 5 (alias GEH_flow_5)
  • 6 (alias GEH_flow_6)
  • 7 (alias GEH_flow_7)
  • 9 (alias GEH_flow_9)
  • 10 (alias GEH_flow_10)
  • 11 (alias GEH_flow_11)
  • 12 (alias GEH_flow_12)
  • 13 (alias GEH_flow_13)
  • 14 (alias GEH_flow_14)
  • 15 (alias GEH_flow_15)
  • 47 ML Forecast: Percentage of Streets below Error Threshold (Flow)

For details on GEH, → Forecast Quality Indicators (FQI).

The templates listed require the attribute GEH_flow_threshold:

  • 41 - Percentage of Links below Error Threshold (Flow)

forecast_distance

Integer type.

It contains the forecast distance, which is expressed in seconds.

The possible values are:

  • 0 (alias forecast_distance_0) .
  • 900 (15 minutes, alias forecast_distance_15) .
  • 1800 (30 minutes, alias forecast_distance_30).
  • 2700 (45 minutes, alias forecast_distance_45).
  • 3600 (60 minutes, alias forecast_distance_60).

The templates listed require the attribute forecast_distance:

  • 41 - Percentage of Links below Error Threshold (Flow)
  • 45 - Percentage of Links below Error Threshold (Speed)

 

skip_if_road_closed

Boolean type.

  • true: in the KPI calculation, skip the contribution of a specific road if the road is closed.
  • false: calculate even on closed roads.

The templates listed require the attribute skip_if_road_closed:

  • 33 - Path Travel Time
  • 34 - Path Travel Time

Road Closures

String type.

Two possible values:

  • Skip calculation if roads are closed: For closed roads during the selected forecast interval, the KPI value is set to -1 to indicate that the travel time on the selected path is not relevant.
  • Calculate even on closed roads: It is calculated through the sum of travel times for all network elements included in the relevant set; the travel times for closed arcs may be arbitrarily high (this typically depends on the duration of a simulation).

Default value: Calculate even on closed roads

  

Total Emissions Externality

The pollutant type can be selected from the list:

  • Particulate matter (10μm)

  • Particulate matter (2.5μm)

  • Nitrogen dioxide (no2)

  • Ozone (o3)

  • Sulfur dioxide (so2)

  • Carbon monoxide (co)

  

Vissim Emissions Externality

The pollutant type can be selected from the list:

  • Carbone dioxide (co2)

  • Carbon monoxide (co)

  • Nitrogen monoxide (nox)

  • Particulates

  • Fuel consumption

  

Topics in this section