{"id":24990193,"url":"https://github.com/arup-group/gelato","last_synced_at":"2025-04-12T01:52:05.854Z","repository":{"id":244259138,"uuid":"730664480","full_name":"arup-group/gelato","owner":"arup-group","description":"Gelato turns MATSim outputs into transport sustainability KPI metrics","archived":false,"fork":false,"pushed_at":"2024-10-18T14:05:57.000Z","size":1646,"stargazers_count":10,"open_issues_count":31,"forks_count":2,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-04-12T01:51:57.711Z","etag":null,"topics":["city-modelling","city-modelling-lab","cml"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/arup-group.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-12-12T12:13:29.000Z","updated_at":"2024-10-28T14:55:08.000Z","dependencies_parsed_at":"2024-06-13T18:21:22.656Z","dependency_job_id":null,"html_url":"https://github.com/arup-group/gelato","commit_stats":null,"previous_names":["arup-group/gelato"],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arup-group%2Fgelato","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arup-group%2Fgelato/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arup-group%2Fgelato/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arup-group%2Fgelato/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/arup-group","download_url":"https://codeload.github.com/arup-group/gelato/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248505873,"owners_count":21115354,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["city-modelling","city-modelling-lab","cml"],"created_at":"2025-02-04T13:34:48.097Z","updated_at":"2025-04-12T01:52:05.829Z","avatar_url":"https://github.com/arup-group.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Gelato\n\n![DailyCIbadge](https://github.com/arup-group/gelato/actions/workflows/ci.yml/badge.svg)\n\n\u003cfigure\u003e\n \u003cimg alt=\"Gelato Clip Art\" height=\"300\" src=\"images/gelato.png\" title=\"Gelato\" width=\"150\"/\u003e\n \u003cfigcaption\u003e\u003csub\u003eImage Designed by Wannapik\u003c/sub\u003e\u003c/figcaption\u003e\n\u003c/figure\u003e\n\n\u003cp\u003e\n\nGelato is a [MATSim](https://github.com/matsim-org/matsim-libs/tree/master#readme)-flavoured reference implementation\nof a sustainable mobility Key Performance Indicators (KPI) framework (see\n[here](https://medium.com/arupcitymodelling/gelato-tasty-sustainability-kpis-for-transport-models-80ad80f3e5db) for a\ndetailed description). Gelato turns MATSim outputs into transport sustainability KPI metrics and exists to provide a\nrunnable application to better understand and explore the framework. As such, it should be regarded as a by-product of\nthe framework rather than a work in its own right.\n\nThe KPI metrics generated by Gelato provide a snapshot summary of a\ngiven MATSim model, and help compare different MATSim models and scenarios against each other.\n\n\n# Installation\n\nIf you have Docker installed and would prefer to use Gelato via Docker rather than\nlocally installing the prerequisite dependencies and building and running the Java\napplication from the command line, skip to the\n\"[Using Gelato via Docker](#using-gelato-via-docker)\" section.\n\nAlternatively, you can grab the latest pre-built, runnable Gelato jar file from the\n[releases page](https://github.com/arup-group/gelato/releases), make sure you have the necessary\n[prerequisites](#prerequisites) installed and then skip straight to the \"[Usage](#usage)\" section.\n\nTo find out how to build Gelato from source and then run it without using Docker, read on...\n\n## Prerequisites\nIn order to build and run Gelato locally, your environment must already have available:\n\n#### JDK \u003e= 17\n- Start [here](https://www.oracle.com/java/technologies/downloads/) or [here](https://jdk.java.net/)\n- If you want to run Gelato from a pre-built jar file rather than build it yourself, you can install a JRE\nrather than a full JDK\n\n#### Maven\n- Start [here](https://maven.apache.org/)\n- Only required if you're building Gelato from source\n\n## Building\nTo compile everything, run all unit tests and linting checks, and build a runnable jar file that includes all\nthe necessary dependencies, clone this repo, and then from the directory you cloned it into:\n\n```shell\nmvn clean package\n```\n\nThis will generate a new jar file in the `target` directory that is named according to the Gelato\nversion number and the latest git commit level - `gelato-0.0.1-alpha-with-dependencies-230f897.jar`\nis the runnable jar in the example below:\n\n```shell\nls -talh target\n```\n\n```\ntotal 48\n-rw-r--r--@ 1 mickyfitz staff 83M 13 Dec 15:17 gelato-0.0.1-alpha-with-dependencies-230f897.jar\ndrwxr-xr-x@ 12 mickyfitz staff 384B 13 Dec 15:17 .\n-rw-r--r--@ 1 mickyfitz staff 28K 13 Dec 15:17 gelato-0.0.1-alpha.jar\ndrwxr-xr-x@ 3 mickyfitz staff 96B 13 Dec 15:17 maven-archiver\n-rw-r--r--@ 1 mickyfitz staff 14K 13 Dec 15:17 jacoco.exec\ndrwxr-xr-x@ 4 mickyfitz staff 128B 13 Dec 15:17 surefire-reports\ndrwxr-xr-x@ 3 mickyfitz staff 96B 13 Dec 15:17 test-classes\ndrwxr-xr-x@ 3 mickyfitz staff 96B 13 Dec 15:17 generated-test-sources\ndrwxr-xr-x@ 3 mickyfitz staff 96B 13 Dec 15:17 classes\ndrwxr-xr-x@ 3 mickyfitz staff 96B 13 Dec 15:17 maven-status\ndrwxr-xr-x@ 3 mickyfitz staff 96B 13 Dec 15:17 generated-sources\ndrwxr-xr-x@ 15 mickyfitz staff 480B 13 Dec 15:17 ..\n```\n\n\n# Usage\n\nYou can run Gelato from the command line, directly from the jar file. The CLI is quite discoverable:\n\n```shell\njava -jar target/gelato-0.0.1-alpha-with-dependencies-230f897.jar --help\n```\n\n```\nUsage: MatsimKpiGenerator [-hV] -mc=\u003cmatsimConfigFile\u003e\n -mo=\u003cmatsimOutputDirectory\u003e -o=\u003coutputDir\u003e\n\n -h, --help Show this help message and exit.\n -mc=\u003cmatsimConfigFile\u003e\n Full path to your model's MATSim config file\n -mo=\u003cmatsimOutputDirectory\u003e\n Full path to your model's MATSim output directory\n -o=\u003coutputDir\u003e Full path to the directory you want KPIs to be written to\n -V, --version Print version information and exit.\n```\n\nTo generate KPI metrics in a local directory on your machine, assuming:\n\n- MATSim output directory is at `/path/to/my-model/outputs`\n- MATSim config file at `/path/to/my-model/outputs/output_config.xml`\n- Target output directory at `/path/to/gelato-outputs/my-model/kpi`\n\n```shell\njava -jar target/gelato-0.0.1-alpha-with-dependencies-230f897.jar \\\n-mc /path/to/my-model/outputs/output_config.xml \\\n-mo /path/to/my-model/outputs \\\n-o /path/to/gelato-outputs/my-model/kpi\n```\n\nWe recommend using MATSim's output config file for the `-mc` parameter wherever\npossible.\n\nGelato will read in MATSim's output files and generate a number of compressed output\nfiles in the directory you specified via `-o`, giving you something like this:\n\n```shell\n-rw-r--r--@ 1 mickyfitz staff 1.2M 5 Mar 16:10 intermediate-access-to-mobility-services.csv.gz\n-rw-r--r--@ 1 mickyfitz staff 110B 5 Mar 16:04 intermediate-affordability.csv.gz\n-rw-r--r--@ 1 mickyfitz staff 4.4M 5 Mar 16:11 intermediate-congestion.csv.gz\n-rw-r--r--@ 1 mickyfitz staff 67B 5 Mar 16:09 intermediate-ghg-emissions.csv.gz\n-rw-r--r--@ 1 mickyfitz staff 392K 5 Mar 16:13 intermediate-mobility-space-usage.csv.gz\n-rw-r--r--@ 1 mickyfitz staff 586K 5 Mar 16:06 intermediate-occupancy-rate.csv.gz\n-rw-r--r--@ 1 mickyfitz staff 3.0M 5 Mar 16:07 intermediate-passenger-km.csv.gz\n-rw-r--r--@ 1 mickyfitz staff 172K 5 Mar 16:04 intermediate-pt-wait-time.csv.gz\n-rw-r--r--@ 1 mickyfitz staff 190B 5 Mar 16:11 intermediate-travel-time.csv.gz\n-rw-r--r--@ 1 mickyfitz staff 2.5M 5 Mar 16:07 intermediate-vehicle-km.csv.gz\n-rw-r--r--@ 1 mickyfitz staff 25B 5 Mar 16:10 kpi-access-to-mobility-services-access-to-bus.csv.gz\n-rw-r--r--@ 1 mickyfitz staff 25B 5 Mar 16:10 kpi-access-to-mobility-services-access-to-pt-and-pt-used.csv.gz\n-rw-r--r--@ 1 mickyfitz staff 25B 5 Mar 16:10 kpi-access-to-mobility-services-access-to-rail.csv.gz\n-rw-r--r--@ 1 mickyfitz staff 81B 5 Mar 16:11 kpi-congestion.csv.gz\n-rw-r--r--@ 1 mickyfitz staff 24B 5 Mar 16:09 kpi-ghg-emissions.csv.gz\n-rw-r--r--@ 1 mickyfitz staff 392K 5 Mar 16:13 kpi-mobility-space-usage-per-activity-type.csv.gz\n-rw-r--r--@ 1 mickyfitz staff 23B 5 Mar 16:13 kpi-mobility-space-usage.csv.gz\n-rw-r--r--@ 1 mickyfitz staff 107B 5 Mar 16:04 kpi-modal-split.csv.gz\n-rw-r--r--@ 1 mickyfitz staff 24B 5 Mar 16:06 kpi-occupancy-rate.csv.gz\n-rw-r--r--@ 1 mickyfitz staff 30B 5 Mar 16:07 kpi-passenger-km.csv.gz\n-rw-r--r--@ 1 mickyfitz staff 27B 5 Mar 16:04 kpi-pt-wait-time.csv.gz\n-rw-r--r--@ 1 mickyfitz staff 909K 5 Mar 16:08 kpi-speed.csv.gz\n-rw-r--r--@ 1 mickyfitz staff 35B 5 Mar 16:11 kpi-travel-time.csv.gz\n-rw-r--r--@ 1 mickyfitz staff 33B 5 Mar 16:07 kpi-vehicle-km.csv.gz\n-rw-r--r--@ 1 mickyfitz staff 26M 5 Mar 16:02 supporting-data-activities.csv.gz\n-rw-r--r--@ 1 mickyfitz staff 1.7M 5 Mar 16:02 supporting-data-activity-facilities.csv.gz\n-rw-r--r--@ 1 mickyfitz staff 72M 5 Mar 16:02 supporting-data-legs.csv.gz\n-rw-r--r--@ 1 mickyfitz staff 284M 5 Mar 16:03 supporting-data-linkLog.csv.gz\n-rw-r--r--@ 1 mickyfitz staff 200K 5 Mar 16:04 supporting-data-networkLinkModes.csv.gz\n-rw-r--r--@ 1 mickyfitz staff 483K 5 Mar 16:04 supporting-data-networkLinks.csv.gz\n-rw-r--r--@ 1 mickyfitz staff 34M 5 Mar 16:03 supporting-data-person-mode-score-parameters.csv.gz\n-rw-r--r--@ 1 mickyfitz staff 27K 5 Mar 16:04 supporting-data-scheduleRoutes.csv.gz\n-rw-r--r--@ 1 mickyfitz staff 49K 5 Mar 16:04 supporting-data-scheduleStops.csv.gz\n-rw-r--r--@ 1 mickyfitz staff 48M 5 Mar 16:02 supporting-data-trips.csv.gz\n-rw-r--r--@ 1 mickyfitz staff 188M 5 Mar 16:04 supporting-data-vehicleOccupancy.csv.gz\n-rw-r--r--@ 1 mickyfitz staff 12M 5 Mar 16:04 supporting-data-vehicles.csv.gz\n```\n\nFor a short explanation of the content and meaning of these files, see [the KPI section](#the-kpis).\n\n## A word about memory\nGelato is a memory-hungry application. The bigger the model outputs you feed it in\nterms of the size of the events file, the network file, etc., the more memory it will need.\nFor this reason, for some MATSim models you will need to:\n\n- Run Gelato in an environment with a lot of RAM available (memory usage of over 100GB is not unheard of)\n- Tweak [the JVM heap settings](https://bell-sw.com/blog/guide-to-jvm-memory-configuration-options/) to make\nsure that Gelato is able to use as much of the available RAM as possible\n\nGelato logs its memory usage every minute, like so:\n```shell\n2024-02-12T13:34:03,345 INFO MemoryObserver:42 used RAM: 25 MB free: 518 MB total: 544 MB\n2024-02-12T13:35:03,350 INFO MemoryObserver:42 used RAM: 6167 MB free: 9304 MB total: 15472 MB\n2024-02-12T13:36:03,351 INFO MemoryObserver:42 used RAM: 9854 MB free: 9585 MB total: 19440 MB\n2024-02-12T13:37:03,358 INFO MemoryObserver:42 used RAM: 15375 MB free: 5568 MB total: 20944 MB\n2024-02-12T13:38:03,365 INFO MemoryObserver:42 used RAM: 21976 MB free: 3623 MB total: 25600 MB\n2024-02-12T13:39:03,372 INFO MemoryObserver:42 used RAM: 25378 MB free: 221 MB total: 25600 MB\n2024-02-12T13:40:03,374 INFO MemoryObserver:42 used RAM: 22115 MB free: 3484 MB total: 25600 MB\n2024-02-12T13:41:03,379 INFO MemoryObserver:42 used RAM: 23096 MB free: 2503 MB total: 25600 MB\n2024-02-12T13:42:03,385 INFO MemoryObserver:42 used RAM: 22929 MB free: 2670 MB total: 25600 MB\n2024-02-12T13:43:03,392 INFO MemoryObserver:42 used RAM: 24238 MB free: 1361 MB total: 25600 MB\n2024-02-12T13:44:03,402 INFO MemoryObserver:42 used RAM: 23718 MB free: 1881 MB total: 25600 MB\n2024-02-12T13:45:03,409 INFO MemoryObserver:42 used RAM: 23552 MB free: 2047 MB total: 25600 MB\n```\n\nIf you're running on a machine with 120GB of RAM, you may be surprised to see Gelato\nfail with an out of memory error having used around only 30GB of RAM. This is because the JVM's\n[`MaxRAMPercentage`](https://www.baeldung.com/java-jvm-parameters-rampercentage#-xxmaxrampercentage)\nsetting defaults to 25%, so 75% of the available RAM will go ignored and unused. You can override this\ndefault behaviour in a number of different ways using JVM parameters, for example:\n\n- Use `Xmx` to set the max heap size to an absolute value, for example 100GB:\n```shell\njava -Xmx100g \\\n-jar gelato-0.0.2-alpha.jar \\\n-mc /path/to/my-model/outputs/output_config.xml \\\n-mo /path/to/my-model/outputs \\\n-o /path/to/gelato-outputs/my-model/kpi\n```\n- Use `MaxRAMPercentage` to set the max heap size as a percentage of the available RAM (values *must*\ninclude 1 decimal place, so `80.0` rather than `80`):\n```shell\njava -XX:MaxRAMPercentage=80.0 \\\n-jar gelato-0.0.2-alpha.jar \\\n-mc /path/to/my-model/outputs/output_config.xml \\\n-mo /path/to/my-model/outputs \\\n-o /p\n```\n\n## A word about running times\nWe have not yet spent any time trying to optimise runtime. Running times depend on a combination of factors,\nbut are mostly influenced by:\n\n- The size and shape of the MATSim outputs you feed to Gelato\n- The specifications of the machine you are running Gelato on\n\nFor this reason, Your Mileage May (Will..) Vary, but as an example, on an M2 Macbook Pro, a full set of\nKPIs takes between 22 and 36 minutes to generate for a model with a compressed events file\nof around 620MB, containing 61.4 million events, and a full set of input files like this:\n\n```shell\n-rw-r--r--@ 1 mickyfitz staff 29M 26 Jan 15:41 output_vehicles.xml.gz\n-rw-r--r--@ 1 mickyfitz staff 45M 26 Jan 15:41 output_trips.csv.gz\n-rw-r--r--@ 1 mickyfitz staff 38K 26 Jan 15:39 output_transitVehicles.xml.gz\n-rw-r--r--@ 1 mickyfitz staff 1.1M 26 Jan 15:39 output_transitSchedule.xml.gz\n-rw-r--r--@ 1 mickyfitz staff 469M 26 Jan 15:39 output_plans.xml.gz\n-rw-r--r--@ 1 mickyfitz staff 17M 26 Jan 15:28 output_persons.csv.gz\n-rw-r--r--@ 1 mickyfitz staff 906K 26 Jan 15:27 output_network.xml.gz\n-rw-r--r--@ 1 mickyfitz staff 1.1M 26 Jan 15:27 output_links.csv.gz\n-rw-r--r--@ 1 mickyfitz staff 66M 26 Jan 15:27 output_legs.csv.gz\n-rw-r--r--@ 1 mickyfitz staff 6.7M 26 Jan 15:26 output_households.xml.gz\n-rw-r--r--@ 1 mickyfitz staff 2.1M 26 Jan 15:26 output_facilities.xml.gz\n-rw-r--r--@ 1 mickyfitz staff 205M 26 Jan 15:26 output_experienced_plans.xml.gz\n-rw-r--r--@ 1 mickyfitz staff 618M 26 Jan 15:20 output_events.xml.gz\n-rw-r--r--@ 1 mickyfitz staff 194B 26 Jan 15:05 output_counts.xml.gz\n-rw-r--r--@ 1 mickyfitz staff 18K 26 Jan 15:05 output_config_reduced.xml\n-rw-r--r--@ 1 mickyfitz staff 53K 26 Jan 15:05 output_config.xml\n-rw-r--r--@ 1 mickyfitz staff 2.1M 26 Jan 15:05 output_allVehicles.xml.gz\n-rw-r--r--@ 1 mickyfitz staff 32M 26 Jan 15:05 output_activities.csv.gz\n```\n\nPeak memory usage was around 20GB - see the [memory settings](#a-word-about-memory) section for a deeper\ndiscussion of memory usage and JVM settings.\n\n\n# Using Gelato via Docker\n\n## Building the Image\nYou can build a Gelato Docker image by cloning this repo, and then running the\nfollowing command from the directory you cloned it into:\n\n```shell\ndocker build -t gelato .\n```\n\nWe have tried to keep the Docker image size reasonably small (around 350MB).\n\n## Running Gelato via the Image\nAssuming:\n\n- A MATSim output directory on your local machine at `/path/to/my-model/outputs`\n- A MATSim config file on your local machine at `/path/to/my-model/outputs/output_config.xml`\n- A target KPI output directory on your local machine at `/path/to/gelato-outputs/my-model`\n- A desired path to the MATSim files directory inside the Docker container of `/my-model-outputs`\n- A desired path to the Gelato KPI output directory inside the Docker container of `/gelato-out`\n\nYou can run Gelato from the Docker image you just built by mounting\nthe input and output data directories as [volumes](https://docs.docker.com/storage/volumes/) in the Docker container\nvia a command like this:\n\n```shell\ndocker run \\\n-v /path/to/my-model/outputs/:/my-model-outputs \\\n-v /path/to/gelato-outputs/my-model:/gelato-out \\\ngelato \\\n-mc /my-model-outputs/output_config.xml \\\n-mo /my-model-outputs \\\n-o /gelato-out\n```\n\nYou can use Gelato's CLI in essentially the same way you would when running directly from the jar file, for example:\n\n```shell\ndocker run gelato --version\n```\n```\n0.0.1-alpha\n```\n\n```shell\ndocker run gelato --help\n```\n\n```\nUsage: MatsimKpiGenerator [-hV] -mc=\u003cmatsimConfigFile\u003e\n -mo=\u003cmatsimOutputDirectory\u003e -o=\u003coutputDir\u003e\n -h, --help Show this help message and exit.\n -mc=\u003cmatsimConfigFile\u003e\n Full path to your model's MATSim config file\n -mo=\u003cmatsimOutputDirectory\u003e\n Full path to your model's MATSim output directory\n -o=\u003coutputDir\u003e Full path to the directory you want KPIs to be written to\n -V, --version Print version information and exit.\n```\n\n## Configuring JVM memory settings in the Docker container\nJVMs have been \"container-aware\" for a few years now, meaning they can detect when they are running\ninside a container and read Cgroup settings. This means that JVM memory settings are based on the memory\navailable **to the container**, rather than the memory available in the host environment. This is welcome\nbehaviour when running Gelato via Docker, but you will usually still need to tweak the JVM settings to\nmake full use of containers with large amounts of RAM.\n\nYou can do this using the same JVM parameters described in the [JVM memory](#a-word-about-memory)\nsection above, but passing these parameters into the Docker container requires you to set a `JVM_OPTS`\nenvironmental variable to hold all the param name/value pairs. Your Docker `run` command would therefore\nlook something like this:\n\n```shell\ndocker run \\\n-v /path/to/my-model/outputs/:/my-model-outputs \\\n-v /path/to/gelato-outputs/my-model:/gelato-out \\\n-e JVM_OPTS=\"-Xmx100G -XX:+PrintFlagsFinal\" \\\ngelato \\\n-mc /my-model-outputs/output_config.xml \\\n-mo /my-model-outputs \\\n-o /gelato-out\n```\n\nYou will sometimes want to set more than one JVM parameter. You do this by making a space-separated list\ninside the `JVM_OPTS` value string, for example:\n\n```shell\n-e JVM_OPTS=\"-Xmx100G -XX:+UseParallelGC -XX:+HeapDumpOnOutOfMemoryError -XX:+PrintFlagsFinal\"\n```\n\n(The `-XX:+PrintFlagsFinal` param does not modify memory configuration, but instructs the JVM to dump all of\nits settings to the console on startup. That can be handy when you want to confirm at runtime that the memory settings\nare as you expect.)\n\n\n# The KPIs\n\n## Methodology\nMuch of the work that led to the creation of Gelato involved defining\na framework of useful KPIs that can be calculated using data available from a MATSim\nsimulation. The KPIs are grouped together under \"themes\", strongly influenced by the\n[World Business Council for Sustainable Development](https://www.wbcsd.org/) dimensions of\n[sustainable mobility](https://docs.wbcsd.org/2015/03/Mobility_indicators.pdf) and the three pillars of\nsustainable development. The themes that we use to describe our KPIs are outlined in column \"KPI Theme\", below.\n\n| WBCSD Dimension of Sustainable Mobility | Sustainable Development Pillar | KPI Theme |\n|-----------------------------------------|--------------------------------|-------------------------------|\n| \"Global Environment\" | \"Environmental\" | \"Environment\" |\n| \"Quality of Life\" | \"Social\" | \"Social\" |\n| \"Economic Success\" | \"Economic\" | \"Economic\" |\n| \"Mobility System Performance\" | -- | \"Mobility System Performance\" |\n\nSpanning across all themes, a fourth dimension, \"Mobility System Performance\" is effectively a separate, unifying layer,\nwhereby improvements in mobility system performance can lead to better outcomes across any or all of the other themes.\n\nSome KPIs do not fall directly under a specific theme, but are parameters\nfor generating other KPIs. They are marked as `Parameter` in the table\nbelow. Parameters are included to provide context on the simulation and allow\nfor sense-checking, whereas KPIs are intended to allow for measurement of sustainable mobility and be compared across scenarios.\n\n## The KPI Metrics\nWe will add more KPIs as we go, but for now, these are the KPIs generated by Gelato:\n\n| Themes | KPI Name | File | Definition | Methodology | Intermediate Data |\n|--------------------------------------------------------------------------|-----------------------------|------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------|\n| 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` |\n| \u003cul\u003e\u003cli\u003eQuality of Life\u003c/li\u003e\u003cli\u003eMobility System Performance\u003c/li\u003e\u003c/ul\u003e | 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` |\n| \u003cul\u003e\u003cli\u003eGlobal Environment\u003c/li\u003e\u003cli\u003eMobility System Performance\u003c/li\u003e\u003c/ul\u003e | 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` |\n| 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` |\n| \u003cul\u003e\u003cli\u003eGlobal Environment\u003c/li\u003e\u003cli\u003eMobility System Performance\u003c/li\u003e\u003c/ul\u003e | 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` |\n| \u003cul\u003e\u003cli\u003eSocial\u003c/li\u003e\u003cli\u003eMobility System Performance\u003c/li\u003e\u003c/ul\u003e | 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` |\n| \u003cul\u003e\u003cli\u003eQuality of Life\u003c/li\u003e\u003cli\u003eEconomic Success\u003c/li\u003e\u003c/ul\u003e | 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` |\n| 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 |\n| 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` |\n| 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` |\n| Parameter | Speed | `kpi-speed.csv.gz` | Network link length divided by travel time | Calculate average speed for each network link in hourly bins. | None |\n| 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` |\n\n## Intermediate Data\nGelato generates a number of \"intermediate\" files that represent the intermediate, disaggregate output of\nvarious KPI calculations:\n\n| File | Description | Corresponding KPI File |\n|---------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------|\n| `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` |\n| `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` |\n| `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` |\n| `intermediate-ghg-emissions.csv.gz` | Total emissions and emissions per capita (total emissions divided by total persons in sim) | `kpi-ghg-emissions.csv.gz` |\n| `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` |\n| `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` |\n| `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` |\n| `intermediate-passenger-km.csv.gz` | Total kilometres travelled by each person during the modelled day. | `kpi-passenger-km.csv.gz` |\n| `intermediate-travel-time.csv.gz` | Average travel time, in minutes, by trip purpose. | `kpi-travel-time.csv.gz` |\n| `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` |\n\n## Supporting Data\n\nIn addition to KPI and intermediate files, Gelato also generates a number of \"supporting data\" files containing the\ndata aggregations used as inputs to the KPI calculations. These files allow the user to perform their own ad-hoc\nanalyses without having to parse and collate raw MATSim output data. Supporting data files use the naming scheme\n`supporting-data-\u003cname of aggregation\u003e`.\n\n| File | Description |\n|--------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `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. |\n| `supporting-data-activity-facilities.csv.gz` | Facility locations and link IDs used for access to different types of activities. |\n| `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). |\n| `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`. |\n| `supporting-data-networkLinkModes.csv.gz` | Modes of transport allowed for each network link. |\n| `supporting-data-networkLinks.csv.gz` | Links of the transport network, their speed, capacity, length (in metres) and number of lanes. |\n| `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. |\n| `supporting-data-scheduleRoutes.csv.gz` | Public transit routes and line IDs and their transit mode. |\n| `supporting-data-scheduleStops.csv.gz` | Public transit stops, their name, spatial coordinates, and the link of the network they are accessed by. |\n| `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). |\n| `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. |\n| `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. |\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farup-group%2Fgelato","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Farup-group%2Fgelato","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farup-group%2Fgelato/lists"}