Configuring stored scenarios

Configuring stored scenarios#

Polaris-Studio enables users to manage multiple model scenarios within the same version control repository.

The manner in which alternative scenarios are housed consists on defining each one of these scenarios as having a base scenario (from which part of its files will be inherited), and a pre-defined folder structure that contains the files that should override the base scenario files.

As each scenario is defined as a modification of a base scenario, it is possible to create a hierarchy of scenarios, where each scenario can be based on another scenario, and so on. This allows for a smaller data redundancy in cases where there is a combination of factors (e.g. two future year scenarios where the only difference between the two is the population forecast).

The base scenario is always the ultimate base for all scenarios

As the stored scenario management tool works by overwriting files from the base folder structure, the base scenario will always be the ultimate base for all scenarios. This means that if a file is not defined in a scenario or on its declared base, it will be inherited from the base scenario.

Note: The management of multiple scenarios tooling is designed to build and verify multiple scenarios stored in a repository only. Editing scenarios and selectively commiting components back to GIT (if desired) is left to the modeller.

Configuring stored scenarios#

The scenarios configuration for POLARIS model repository stored in a repository is consolidated in the model_scenarios.json file found in the scenario_files folder inside the model root folder.

{
    "high_growth":{
		"description": "example scenario",
		"based_on": "base",
		"run_on_build": ["active", "location_links", "intersections", "geoconsistency", "location_parking"],
		"custom_scripts": ["scenario_scripts/update_freight_high_growth.py"]
	},
   "low_growth": {
      ...
   }
}

As can be seen in the example above, each scenario appears as a key in the JSON file, and 4 keys can be defined for each scenario:

  1. description: A short description of the scenario, which is useful for documentation purposes ONLY.

  2. based_on: The name of the base scenario from which this scenario will inherit its files.

  3. custom_scripts: A list of custom Python or sql script files that will be run BEFORE the scenario is built and the run_on_build procedures are finalized. These scripts must be stored anywhere in the scenario folder and correctly referred to in the scenario configuration json. We recommend adding these scripts to a scenario_scripts folder and configuring the json as suggested above.

  4. run_on_build: A list of Polaris-Studio procedures that must be run after the scenario is built and the custom scripts have been executed. The set of procedure names that can be provided here are as follows:

    • active: Re-generates the Transit_Walk and Transit_Bike tables.

    • location_links: Rebuilds the location_links table.

    • location_parking: Rebuilds the location_parking table.

    • intersections: Rebuilds all intersections from scratch. Draws traffic signal locations from OSM.

    • geoconsistency: Runs a full geo-consistency check for the entire model.

Custom scripts must have a specific signature

All custom scripts must have a specific signature in order to be run by Polaris-Studio, as shown below.

from pathlib import Path

def scenario_process(model_dir: Path):
    pass

Child scenarios do not inherit custom scripts or “run_on_build” procedures

Scripts that are required on “child” scenarios (i.e. scenarios that are based on another scenario) must be stored in the scenario folder of the child scenario too.

Custom Scripts are your friends#

Custom scripts are a powerful and flexible way to modify model inputs without having to store full copies tables, where much of the data would be redundant with their base scenario.

Below there are a few examples of types of scenarios that can leverage this workflow:

  • Alternative population forecasts: In the supply database, only a few columns in the zone layer would have to
    be modified. In this case, the scenario can contain a CSV file with the modified values, and a custom script to update the zone table with the new values at build time.

  • Improved transit service: In a scenario where certain transit routes would have higher frequencies in the peak periods, the scenario could contain a CSV file with the new frequencies, and a custom script to update the transit_routes table with the new values at build time.

  • New infrastructure: In a scenario where a new road is added to the network, the scenario could contain the data for the new road (including geometry), and a custom script to update the link table with those values. The Supply automatic editing triggers would generate the necessary new nodes, and Polaris-Studio code could be called to create the new intersections, location-links, Active transport network, etc.

In all of these cases, the custom script could contain validation logic to ensure that the changes made to the database are consistent with expectations.

Multi-supply#

The main use-case for maintaining multiple scenarios within a POLARIS model repository is to keep supply models (i.e. networks) for different forecasting horizons and/or infrastructure alternatives.

It is particularly complex to ensure consistency across all supply files when blending tables from different scenario sources, therefore some rules are imposed to the provenance of tables in order to ensure consistency:

Note: The file type for a table (*.csv or *.parquet) must be the same FOR ALL SCENARIOS in a repository.

Sets of tables that must ALWAYS come from the same source:#

  • Transit: transit_links, transit_routes, transit_pattern_links, transit_patterns, transit_agencies, transit_stops & transit_raw_shapes,

  • Traffic - link, node, signal, phasing, timing, phasing_nested_records, timing_nested_records, sign & signal_nested_records

Programmatic network changes are preferred#

In many cases, the network differences between two scenarios are rather minor, such as the increase/reduction of number of lanes for a set of links, change in socio-economic data for a set of zones, etc.

In these cases, the most space-efficient way to specify an alternative network is through the use of custom scripts that implement those specific changes, instead of storing a full copy of the network tables in the repository.

User duty to model consistency#

Although it would be possible to create and enforce a set of rules that would nearly guarantee consistency within the supply model, it would require a significant number of custom treatments for special cases and limit the flexibility of this solution.

For example: Let’s suppose that the user wants to create a scenario with a new network for a future year, but they want to create the connections and intersection control tables (signal, phasing, timing, phasing_nested_records, sign, timing_nested_records & signal_nested_records) on the fly, instead of having to store them in the repository. In this case, enforcing that all tables come from the same source would not be possible, or it would require additional configurations or special treatment.

For this reason, the user is responsible for ensuring that the configuration entered to create the scenario results in a consistent model.

Polaris-Studio provides testing tools to build all scenarios for a repository and check consistency for each one of them.