Gelato

Gelato is a [MATSim](https://github.com/matsim-org/matsim-libs/tree/master#readme)-flavoured reference implementation of a sustainable mobility Key Performance Indicators (KPI) framework (see [here](https://medium.com/arupcitymodelling/gelato-tasty-sustainability-kpis-for-transport-models-80ad80f3e5db) for a detailed description). Gelato turns MATSim outputs into transport sustainability KPI metrics and exists to provide a runnable application to better understand and explore the framework. As such, it should be regarded as a by-product of the framework rather than a work in its own right. The KPI metrics generated by Gelato provide a snapshot summary of a given MATSim model, and help compare different MATSim models and scenarios against each other. # Installation If you have Docker installed and would prefer to use Gelato via Docker rather than locally installing the prerequisite dependencies and building and running the Java application from the command line, skip to the "[Using Gelato via Docker](#using-gelato-via-docker)" section. Alternatively, you can grab the latest pre-built, runnable Gelato jar file from the [releases page](https://github.com/arup-group/gelato/releases), make sure you have the necessary [prerequisites](#prerequisites) installed and then skip straight to the "[Usage](#usage)" section. To find out how to build Gelato from source and then run it without using Docker, read on... ## Prerequisites In order to build and run Gelato locally, your environment must already have available: #### JDK >= 17 - Start [here](https://www.oracle.com/java/technologies/downloads/) or [here](https://jdk.java.net/) - If you want to run Gelato from a pre-built jar file rather than build it yourself, you can install a JRE rather than a full JDK #### Maven - Start [here](https://maven.apache.org/) - Only required if you're building Gelato from source ## Building To compile everything, run all unit tests and linting checks, and build a runnable jar file that includes all the necessary dependencies, clone this repo, and then from the directory you cloned it into: ```shell mvn clean package ``` This will generate a new jar file in the `target` directory that is named according to the Gelato version number and the latest git commit level - `gelato-0.0.1-alpha-with-dependencies-230f897.jar` is the runnable jar in the example below: ```shell ls -talh target ``` ``` total 48 -rw-r--r--@ 1 mickyfitz staff 83M 13 Dec 15:17 gelato-0.0.1-alpha-with-dependencies-230f897.jar drwxr-xr-x@ 12 mickyfitz staff 384B 13 Dec 15:17 . -rw-r--r--@ 1 mickyfitz staff 28K 13 Dec 15:17 gelato-0.0.1-alpha.jar drwxr-xr-x@ 3 mickyfitz staff 96B 13 Dec 15:17 maven-archiver -rw-r--r--@ 1 mickyfitz staff 14K 13 Dec 15:17 jacoco.exec drwxr-xr-x@ 4 mickyfitz staff 128B 13 Dec 15:17 surefire-reports drwxr-xr-x@ 3 mickyfitz staff 96B 13 Dec 15:17 test-classes drwxr-xr-x@ 3 mickyfitz staff 96B 13 Dec 15:17 generated-test-sources drwxr-xr-x@ 3 mickyfitz staff 96B 13 Dec 15:17 classes drwxr-xr-x@ 3 mickyfitz staff 96B 13 Dec 15:17 maven-status drwxr-xr-x@ 3 mickyfitz staff 96B 13 Dec 15:17 generated-sources drwxr-xr-x@ 15 mickyfitz staff 480B 13 Dec 15:17 .. ``` # Usage You can run Gelato from the command line, directly from the jar file. The CLI is quite discoverable: ```shell java -jar target/gelato-0.0.1-alpha-with-dependencies-230f897.jar --help ``` ``` Usage: MatsimKpiGenerator [-hV] -mc= -mo= -o= -h, --help Show this help message and exit. -mc= Full path to your model's MATSim config file -mo= Full path to your model's MATSim output directory -o= Full path to the directory you want KPIs to be written to -V, --version Print version information and exit. ``` To generate KPI metrics in a local directory on your machine, assuming: - MATSim output directory is at `/path/to/my-model/outputs` - MATSim config file at `/path/to/my-model/outputs/output_config.xml` - Target output directory at `/path/to/gelato-outputs/my-model/kpi` ```shell java -jar target/gelato-0.0.1-alpha-with-dependencies-230f897.jar \ -mc /path/to/my-model/outputs/output_config.xml \ -mo /path/to/my-model/outputs \ -o /path/to/gelato-outputs/my-model/kpi ``` We recommend using MATSim's output config file for the `-mc` parameter wherever possible. Gelato will read in MATSim's output files and generate a number of compressed output files in the directory you specified via `-o`, giving you something like this: ```shell -rw-r--r--@ 1 mickyfitz staff 1.2M 5 Mar 16:10 intermediate-access-to-mobility-services.csv.gz -rw-r--r--@ 1 mickyfitz staff 110B 5 Mar 16:04 intermediate-affordability.csv.gz -rw-r--r--@ 1 mickyfitz staff 4.4M 5 Mar 16:11 intermediate-congestion.csv.gz -rw-r--r--@ 1 mickyfitz staff 67B 5 Mar 16:09 intermediate-ghg-emissions.csv.gz -rw-r--r--@ 1 mickyfitz staff 392K 5 Mar 16:13 intermediate-mobility-space-usage.csv.gz -rw-r--r--@ 1 mickyfitz staff 586K 5 Mar 16:06 intermediate-occupancy-rate.csv.gz -rw-r--r--@ 1 mickyfitz staff 3.0M 5 Mar 16:07 intermediate-passenger-km.csv.gz -rw-r--r--@ 1 mickyfitz staff 172K 5 Mar 16:04 intermediate-pt-wait-time.csv.gz -rw-r--r--@ 1 mickyfitz staff 190B 5 Mar 16:11 intermediate-travel-time.csv.gz -rw-r--r--@ 1 mickyfitz staff 2.5M 5 Mar 16:07 intermediate-vehicle-km.csv.gz -rw-r--r--@ 1 mickyfitz staff 25B 5 Mar 16:10 kpi-access-to-mobility-services-access-to-bus.csv.gz -rw-r--r--@ 1 mickyfitz staff 25B 5 Mar 16:10 kpi-access-to-mobility-services-access-to-pt-and-pt-used.csv.gz -rw-r--r--@ 1 mickyfitz staff 25B 5 Mar 16:10 kpi-access-to-mobility-services-access-to-rail.csv.gz -rw-r--r--@ 1 mickyfitz staff 81B 5 Mar 16:11 kpi-congestion.csv.gz -rw-r--r--@ 1 mickyfitz staff 24B 5 Mar 16:09 kpi-ghg-emissions.csv.gz -rw-r--r--@ 1 mickyfitz staff 392K 5 Mar 16:13 kpi-mobility-space-usage-per-activity-type.csv.gz -rw-r--r--@ 1 mickyfitz staff 23B 5 Mar 16:13 kpi-mobility-space-usage.csv.gz -rw-r--r--@ 1 mickyfitz staff 107B 5 Mar 16:04 kpi-modal-split.csv.gz -rw-r--r--@ 1 mickyfitz staff 24B 5 Mar 16:06 kpi-occupancy-rate.csv.gz -rw-r--r--@ 1 mickyfitz staff 30B 5 Mar 16:07 kpi-passenger-km.csv.gz -rw-r--r--@ 1 mickyfitz staff 27B 5 Mar 16:04 kpi-pt-wait-time.csv.gz -rw-r--r--@ 1 mickyfitz staff 909K 5 Mar 16:08 kpi-speed.csv.gz -rw-r--r--@ 1 mickyfitz staff 35B 5 Mar 16:11 kpi-travel-time.csv.gz -rw-r--r--@ 1 mickyfitz staff 33B 5 Mar 16:07 kpi-vehicle-km.csv.gz -rw-r--r--@ 1 mickyfitz staff 26M 5 Mar 16:02 supporting-data-activities.csv.gz -rw-r--r--@ 1 mickyfitz staff 1.7M 5 Mar 16:02 supporting-data-activity-facilities.csv.gz -rw-r--r--@ 1 mickyfitz staff 72M 5 Mar 16:02 supporting-data-legs.csv.gz -rw-r--r--@ 1 mickyfitz staff 284M 5 Mar 16:03 supporting-data-linkLog.csv.gz -rw-r--r--@ 1 mickyfitz staff 200K 5 Mar 16:04 supporting-data-networkLinkModes.csv.gz -rw-r--r--@ 1 mickyfitz staff 483K 5 Mar 16:04 supporting-data-networkLinks.csv.gz -rw-r--r--@ 1 mickyfitz staff 34M 5 Mar 16:03 supporting-data-person-mode-score-parameters.csv.gz -rw-r--r--@ 1 mickyfitz staff 27K 5 Mar 16:04 supporting-data-scheduleRoutes.csv.gz -rw-r--r--@ 1 mickyfitz staff 49K 5 Mar 16:04 supporting-data-scheduleStops.csv.gz -rw-r--r--@ 1 mickyfitz staff 48M 5 Mar 16:02 supporting-data-trips.csv.gz -rw-r--r--@ 1 mickyfitz staff 188M 5 Mar 16:04 supporting-data-vehicleOccupancy.csv.gz -rw-r--r--@ 1 mickyfitz staff 12M 5 Mar 16:04 supporting-data-vehicles.csv.gz ``` For a short explanation of the content and meaning of these files, see [the KPI section](#the-kpis). ## A word about memory Gelato is a memory-hungry application. The bigger the model outputs you feed it in terms of the size of the events file, the network file, etc., the more memory it will need. For this reason, for some MATSim models you will need to: - Run Gelato in an environment with a lot of RAM available (memory usage of over 100GB is not unheard of) - Tweak [the JVM heap settings](https://bell-sw.com/blog/guide-to-jvm-memory-configuration-options/) to make sure that Gelato is able to use as much of the available RAM as possible Gelato logs its memory usage every minute, like so: ```shell 2024-02-12T13:34:03,345 INFO MemoryObserver:42 used RAM: 25 MB free: 518 MB total: 544 MB 2024-02-12T13:35:03,350 INFO MemoryObserver:42 used RAM: 6167 MB free: 9304 MB total: 15472 MB 2024-02-12T13:36:03,351 INFO MemoryObserver:42 used RAM: 9854 MB free: 9585 MB total: 19440 MB 2024-02-12T13:37:03,358 INFO MemoryObserver:42 used RAM: 15375 MB free: 5568 MB total: 20944 MB 2024-02-12T13:38:03,365 INFO MemoryObserver:42 used RAM: 21976 MB free: 3623 MB total: 25600 MB 2024-02-12T13:39:03,372 INFO MemoryObserver:42 used RAM: 25378 MB free: 221 MB total: 25600 MB 2024-02-12T13:40:03,374 INFO MemoryObserver:42 used RAM: 22115 MB free: 3484 MB total: 25600 MB 2024-02-12T13:41:03,379 INFO MemoryObserver:42 used RAM: 23096 MB free: 2503 MB total: 25600 MB 2024-02-12T13:42:03,385 INFO MemoryObserver:42 used RAM: 22929 MB free: 2670 MB total: 25600 MB 2024-02-12T13:43:03,392 INFO MemoryObserver:42 used RAM: 24238 MB free: 1361 MB total: 25600 MB 2024-02-12T13:44:03,402 INFO MemoryObserver:42 used RAM: 23718 MB free: 1881 MB total: 25600 MB 2024-02-12T13:45:03,409 INFO MemoryObserver:42 used RAM: 23552 MB free: 2047 MB total: 25600 MB ``` If you're running on a machine with 120GB of RAM, you may be surprised to see Gelato fail with an out of memory error having used around only 30GB of RAM. This is because the JVM's [`MaxRAMPercentage`](https://www.baeldung.com/java-jvm-parameters-rampercentage#-xxmaxrampercentage) setting defaults to 25%, so 75% of the available RAM will go ignored and unused. You can override this default behaviour in a number of different ways using JVM parameters, for example: - Use `Xmx` to set the max heap size to an absolute value, for example 100GB: ```shell java -Xmx100g \ -jar gelato-0.0.2-alpha.jar \ -mc /path/to/my-model/outputs/output_config.xml \ -mo /path/to/my-model/outputs \ -o /path/to/gelato-outputs/my-model/kpi ``` - Use `MaxRAMPercentage` to set the max heap size as a percentage of the available RAM (values *must* include 1 decimal place, so `80.0` rather than `80`): ```shell java -XX:MaxRAMPercentage=80.0 \ -jar gelato-0.0.2-alpha.jar \ -mc /path/to/my-model/outputs/output_config.xml \ -mo /path/to/my-model/outputs \ -o /p ``` ## A word about running times We have not yet spent any time trying to optimise runtime. Running times depend on a combination of factors, but are mostly influenced by: - The size and shape of the MATSim outputs you feed to Gelato - The specifications of the machine you are running Gelato on For this reason, Your Mileage May (Will..) Vary, but as an example, on an M2 Macbook Pro, a full set of KPIs takes between 22 and 36 minutes to generate for a model with a compressed events file of around 620MB, containing 61.4 million events, and a full set of input files like this: ```shell -rw-r--r--@ 1 mickyfitz staff 29M 26 Jan 15:41 output_vehicles.xml.gz -rw-r--r--@ 1 mickyfitz staff 45M 26 Jan 15:41 output_trips.csv.gz -rw-r--r--@ 1 mickyfitz staff 38K 26 Jan 15:39 output_transitVehicles.xml.gz -rw-r--r--@ 1 mickyfitz staff 1.1M 26 Jan 15:39 output_transitSchedule.xml.gz -rw-r--r--@ 1 mickyfitz staff 469M 26 Jan 15:39 output_plans.xml.gz -rw-r--r--@ 1 mickyfitz staff 17M 26 Jan 15:28 output_persons.csv.gz -rw-r--r--@ 1 mickyfitz staff 906K 26 Jan 15:27 output_network.xml.gz -rw-r--r--@ 1 mickyfitz staff 1.1M 26 Jan 15:27 output_links.csv.gz -rw-r--r--@ 1 mickyfitz staff 66M 26 Jan 15:27 output_legs.csv.gz -rw-r--r--@ 1 mickyfitz staff 6.7M 26 Jan 15:26 output_households.xml.gz -rw-r--r--@ 1 mickyfitz staff 2.1M 26 Jan 15:26 output_facilities.xml.gz -rw-r--r--@ 1 mickyfitz staff 205M 26 Jan 15:26 output_experienced_plans.xml.gz -rw-r--r--@ 1 mickyfitz staff 618M 26 Jan 15:20 output_events.xml.gz -rw-r--r--@ 1 mickyfitz staff 194B 26 Jan 15:05 output_counts.xml.gz -rw-r--r--@ 1 mickyfitz staff 18K 26 Jan 15:05 output_config_reduced.xml -rw-r--r--@ 1 mickyfitz staff 53K 26 Jan 15:05 output_config.xml -rw-r--r--@ 1 mickyfitz staff 2.1M 26 Jan 15:05 output_allVehicles.xml.gz -rw-r--r--@ 1 mickyfitz staff 32M 26 Jan 15:05 output_activities.csv.gz ``` Peak memory usage was around 20GB - see the [memory settings](#a-word-about-memory) section for a deeper discussion of memory usage and JVM settings. # Using Gelato via Docker ## Building the Image You can build a Gelato Docker image by cloning this repo, and then running the following command from the directory you cloned it into: ```shell docker build -t gelato . ``` We have tried to keep the Docker image size reasonably small (around 350MB). ## Running Gelato via the Image Assuming: - A MATSim output directory on your local machine at `/path/to/my-model/outputs` - A MATSim config file on your local machine at `/path/to/my-model/outputs/output_config.xml` - A target KPI output directory on your local machine at `/path/to/gelato-outputs/my-model` - A desired path to the MATSim files directory inside the Docker container of `/my-model-outputs` - A desired path to the Gelato KPI output directory inside the Docker container of `/gelato-out` You can run Gelato from the Docker image you just built by mounting the input and output data directories as [volumes](https://docs.docker.com/storage/volumes/) in the Docker container via a command like this: ```shell docker run \ -v /path/to/my-model/outputs/:/my-model-outputs \ -v /path/to/gelato-outputs/my-model:/gelato-out \ gelato \ -mc /my-model-outputs/output_config.xml \ -mo /my-model-outputs \ -o /gelato-out ``` You can use Gelato's CLI in essentially the same way you would when running directly from the jar file, for example: ```shell docker run gelato --version ``` ``` 0.0.1-alpha ``` ```shell docker run gelato --help ``` ``` Usage: MatsimKpiGenerator [-hV] -mc= -mo= -o= -h, --help Show this help message and exit. -mc= Full path to your model's MATSim config file -mo= Full path to your model's MATSim output directory -o= Full path to the directory you want KPIs to be written to -V, --version Print version information and exit. ``` ## Configuring JVM memory settings in the Docker container JVMs have been "container-aware" for a few years now, meaning they can detect when they are running inside a container and read Cgroup settings. This means that JVM memory settings are based on the memory available **to the container**, rather than the memory available in the host environment. This is welcome behaviour when running Gelato via Docker, but you will usually still need to tweak the JVM settings to make full use of containers with large amounts of RAM. You can do this using the same JVM parameters described in the [JVM memory](#a-word-about-memory) section above, but passing these parameters into the Docker container requires you to set a `JVM_OPTS` environmental variable to hold all the param name/value pairs. Your Docker `run` command would therefore look something like this: ```shell docker run \ -v /path/to/my-model/outputs/:/my-model-outputs \ -v /path/to/gelato-outputs/my-model:/gelato-out \ -e JVM_OPTS="-Xmx100G -XX:+PrintFlagsFinal" \ gelato \ -mc /my-model-outputs/output_config.xml \ -mo /my-model-outputs \ -o /gelato-out ``` You will sometimes want to set more than one JVM parameter. You do this by making a space-separated list inside the `JVM_OPTS` value string, for example: ```shell -e JVM_OPTS="-Xmx100G -XX:+UseParallelGC -XX:+HeapDumpOnOutOfMemoryError -XX:+PrintFlagsFinal" ``` (The `-XX:+PrintFlagsFinal` param does not modify memory configuration, but instructs the JVM to dump all of its settings to the console on startup. That can be handy when you want to confirm at runtime that the memory settings are as you expect.) # The KPIs ## Methodology Much of the work that led to the creation of Gelato involved defining a framework of useful KPIs that can be calculated using data available from a MATSim simulation. The KPIs are grouped together under "themes", strongly influenced by the [World Business Council for Sustainable Development](https://www.wbcsd.org/) dimensions of [sustainable mobility](https://docs.wbcsd.org/2015/03/Mobility_indicators.pdf) and the three pillars of sustainable development. The themes that we use to describe our KPIs are outlined in column "KPI Theme", below. | WBCSD Dimension of Sustainable Mobility | Sustainable Development Pillar | KPI Theme | |-----------------------------------------|--------------------------------|-------------------------------| | "Global Environment" | "Environmental" | "Environment" | | "Quality of Life" | "Social" | "Social" | | "Economic Success" | "Economic" | "Economic" | | "Mobility System Performance" | -- | "Mobility System Performance" | Spanning across all themes, a fourth dimension, "Mobility System Performance" is effectively a separate, unifying layer, whereby improvements in mobility system performance can lead to better outcomes across any or all of the other themes. Some KPIs do not fall directly under a specific theme, but are parameters for generating other KPIs. They are marked as `Parameter` in the table below. Parameters are included to provide context on the simulation and allow for sense-checking, whereas KPIs are intended to allow for measurement of sustainable mobility and be compared across scenarios. ## The KPI Metrics We will add more KPIs as we go, but for now, these are the KPIs generated by Gelato: | Themes | KPI Name | File | Definition | Methodology | Intermediate Data | |--------------------------------------------------------------------------|-----------------------------|------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------| | Quality of Life | Access to Mobility Services | `kpi-access-to-mobility-services-access-to-{bus,rail,pt-and-pt-used}.csv.gz` | Percentage of agents whose homes are within 400m of bus stops, 800m of rail stops, and whether they used PT for travel | From trip logs, we obtain agents' 'home' activity locations. We find whether there is a stop that serves transit services of modes 'bus' and 'rail', within distances of 400 and 800 metres of person's home location, respectively. | `intermediate-access-to-mobility-services.csv.gz` | |

• Quality of Life
• Mobility System Performance

| Affordability | `kpi-affordability.csv.gz` | Ratio of average spend on transport of low income agents : overall average spend on transport of all agents | Using leg logs and monetary scoring values per mode and person's subpopulation (per distance unit and constant), and/or Person Money Events, compute monetary cost for each leg. We compute total and average daily spend on transport by income brackets (numeric values for income are required) or subpopulation, if not available, (if `low income` subpopulation is available, otherwise only intermediate output is generated). Read more: [KPI Data Requirements and Expectations: Affordability](KPI_Data_Requirements_and_Expectations.md#affordability). | `intermediate-affordability.csv.gz` | |

• Global Environment
• Mobility System Performance

| Congestion | `kpi-congestion.csv.gz` | Delays in road traffic and in public transport during peak hours compared to free flow travel | Capture free-flow time at the link level, subtract congested time from this value. Congested time is the difference between link entry and exit time. | `intermediate-congestion.csv.gz` | | Global Environment | GHG Emissions | `kpi-ghg-emissions.csv.gz` | Total Emissions emitted by vehicles | Total kilometres travelled by vehicles multiplied by default emission factors of 0.222 kg C02/km (car) and 1.372 kg CO2/km (bus), respectively; or as set by you - read more in [KPI Data Requirements and Expectations: GHG Emissions](KPI_Data_Requirements_and_Expectations.md#ghg-emissions). | `intermediate-ghg-emissions.csv.gz` | |

• Global Environment
• Mobility System Performance

| Mobility Space Usage | `kpi-mobility-space-usage{-per-activity-type}.csv.gz` | Estimated parking space demand per capita | Number of persons at facilities, per activity type, who arrived there by car. We use a parking space factor of 11.5 ([link](https://www.interparking-france.com/en/what-are-the-dimensions-of-a-parking-space/)) to calculate total parking demand and weigh it by number of trips. | `intermediate-mobility-space-usage.csv.gz` | |

• Social
• Mobility System Performance

| PT Wait Time | `kpi-pt-wait-time.csv.gz` | Average time waiting for a PT boarding | Average trip wait times by transport mode. | `intermediate-pt-wait-time.csv.gz` | |

• Quality of Life
• Economic Success

| Travel Time | `kpi-travel-time.csv.gz` | Average travel time across all trips, in minutes | Using trip logs, convert travel time to minutes, average across the trips. | `intermediate-travel-time.csv.gz` | | Parameter | Modal Split | `kpi-modal-split.csv.gz` | Modal split of dominant (by distance) trip modes | Using trip logs, calculate the number of trips for each mode, as well as the percentage. This metric will not be scaled, but viewed in tandem with the other KPIs. | None | | Parameter | Occupancy Rate | `kpi-occupancy-rate.csv.gz` | Average load factor of vehicles of all modes | Track boarding/alighting events at vehicle level and combine with the vehicle log to calculate distances, then aggregate to average occupancy by mode. | `intermediate-occupancy-rate.csv.gz` | | Parameter | Passenger KM | `kpi-passenger-km.csv.gz` | Total distance travelled by all persons | Sum the total distance travelled as recorded in the trip logs. | `intermediate-passenger-km.csv.gz` | | Parameter | Speed | `kpi-speed.csv.gz` | Network link length divided by travel time | Calculate average speed for each network link in hourly bins. | None | | Parameter | Vehicle KM | `kpi-vehicle-km.csv.gz` | Total distance travelled by all moving vehicles | Sum the total distance travelled as recorded in the link log. | `intermediate-vehicle-km.csv.gz` | ## Intermediate Data Gelato generates a number of "intermediate" files that represent the intermediate, disaggregate output of various KPI calculations: | File | Description | Corresponding KPI File | |---------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------| | `intermediate-access-to-mobility-services.csv.gz` | Home locations for each person, true/false columns to identify access to bus and rail stops, and whether the agent used transit. | `kpi-access-to-mobility-services-access-to-{bus,rail,pt-and-pt-used}.csv.gz` | | `intermediate-affordability.csv.gz` | Total and average daily monetary cost of travel across agent income bracket (or subpopulation if income is not available). Overall values are also reported. | `kpi-affordability.csv.gz` | | `intermediate-congestion.csv.gz` | Average delay ratio for travel time on each link, for each mode, across all hours of the modelled day, given the link was used within that hour by vehicle(s) of that mode. | `kpi-congestion.csv.gz` | | `intermediate-ghg-emissions.csv.gz` | Total emissions and emissions per capita (total emissions divided by total persons in sim) | `kpi-ghg-emissions.csv.gz` | | `intermediate-mobility-space-usage.csv.gz` | Parking space demand per facility and activity type. Max occupancy and total trips are also given. | `kpi-mobility-space-usage{-per-activity-type}.csv.gz` | | `intermediate-occupancy-rate.csv.gz` | Average occupancy of each vehicle, across the modelled day, given that vehicle has travelled. Capacity of the vehicle is reported for convenience. | `kpi-occupancy-rate.csv.gz` | | `intermediate-pt-wait-time.csv.gz` | Average waiting time, in seconds, for each transit stop and transit mode, across hours of the modelled day (given the transit stop was used for travel). | `kpi-pt-wait-time.csv.gz` | | `intermediate-passenger-km.csv.gz` | Total kilometres travelled by each person during the modelled day. | `kpi-passenger-km.csv.gz` | | `intermediate-travel-time.csv.gz` | Average travel time, in minutes, by trip purpose. | `kpi-travel-time.csv.gz` | | `intermediate-vehicle-km.csv.gz` | Total kilometres travelled by each vehicle during the modelled day. The mode of the vehicle is reported for convenience. | `kpi-vehicle-km.csv.gz` | ## Supporting Data In addition to KPI and intermediate files, Gelato also generates a number of "supporting data" files containing the data aggregations used as inputs to the KPI calculations. These files allow the user to perform their own ad-hoc analyses without having to parse and collate raw MATSim output data. Supporting data files use the naming scheme `supporting-data-`. | File | Description | |--------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `supporting-data-activities.csv.gz` | The complement of trips table. Activities performed by persons, includes access and egress mode used for the activity as well as activity start and end time, which takes account of trip travel time. | | `supporting-data-activity-facilities.csv.gz` | Facility locations and link IDs used for access to different types of activities. | | `supporting-data-legs.csv.gz` | Information (temporal and spatial) about the legs (subcomponents) of each trip of each person who travelled in the model (see: MATSim's `output_legs.csv` file). | | `supporting-data-linkLog.csv.gz` | A data table recording every vehicle's entry into and exit from each network link it travelled through, alongside the number of occupants in the vehicle at each of these points. Built by parsing raw link entry/exit events from MATSim's `output_events.xml.gz` and used to calculate KPIs such as `Congestion` and `Occupancy Rate`. | | `supporting-data-networkLinkModes.csv.gz` | Modes of transport allowed for each network link. | | `supporting-data-networkLinks.csv.gz` | Links of the transport network, their speed, capacity, length (in metres) and number of lanes. | | `supporting-data-person-mode-score-parameters.csv.gz` | Person table with columns for income (if available), subpopulation, and monetary distance and constant costs for each transport mode configured. | | `supporting-data-scheduleRoutes.csv.gz` | Public transit routes and line IDs and their transit mode. | | `supporting-data-scheduleStops.csv.gz` | Public transit stops, their name, spatial coordinates, and the link of the network they are accessed by. | | `supporting-data-trips.csv.gz` | Information (temporal and spatial) about the trips of each person who travelled in the model (see: MATSim's `output_trips.csv` file). | | `supporting-data-vehicleOccupancy.csv.gz` | Supporting table for the `supporting-data-linkLog.csv.gz`. Person IDs occupying the vehicle at the Link Log entry at the given index. | | `supporting-data-vehicles.csv.gz` | All vehicles, private and transit, known to the model, regardless of whether they have been used. For transit vehicles, transit Line and Route IDs are also reported. |