/transport-performance-docker

A docker container for running `transport-performance`.

Primary LanguagePythonMIT LicenseMIT

transport-performance-docker

About

A dockerised solution for analysing urban centres using transport-network-performance.

Installation and Building

This section covers general installation and building only. Developers, see CONTRIBUTING.md for more details.

  1. Install dependencies: Docker

  2. Clone this repo and move into the directory:

git clone https://github.com/datasciencecampus/transport-performance-docker.git
cd transport-performance-docker
  1. Build the docker image:
docker build -t transport-performance .

The transport-performance docker image should then be visable using docker images in a CLI

Note: steps 2 and 3 are temporary while this image is not hosted (somewhere like DockerHub, for example).

Usage

This section covers general usage instructions only. Developers, see CONTRIBUTING.md for more details.

  1. Add required input data (see the Input Data section for more details).

  2. (Optional) Create a configuration toml to define the 'core' set-up parameters, those that will be consitently used across all urban centre runs (see the Config TOML section for more details).

  3. Set the following environment variables to run specific urban centre parameters:

Environment Variable Required Default Value Description
COUNTRY_NAME Yes - Name of the urban centre country
AREA_NAME Yes - Name of the urban centre (analysis area)
BBOX Yes - Bounding box coordinates surrounding the entirity of the urban centre. It is a string comma separated list format in left, bottom, right, top order. Note: the limits of this bounding box do not need to be precise, but they should make certain they are large enough to include the entirity of the urban centre
CENTRE Yes - The coordinate within the urban centre of interest. It is a string comma separated list in Y coord, X coord order. Note: this point does not need to be precise, but must be somewhere within the expected urban centre boundary
BBOX_CRS No EPSG:4326 Authority code of the coordinate reference system used to define BBOX
CENTRE_CRS No EPSG:4326 Authority code of the coordinate reference system used to define CENTRE
BUFFER_ESTIMATION_CRS No EPGS:27700 Authority code of the coordinate referece system used when calculating the urban centre buffer
GTFS_OSM_SUBDIR No COUNTRY_NAME Subdirectory name in which gtfs and osm folders are located
EMPTY_FEED No 0 Whether to remove empty GTFS feeds post filtering. Should be either 0 or 1. Setting 0 means empty feeds will not be deleted and an error wil be raised. Setting 1 means empty feeds will be deleted and a warning will be raised.
FAST_TRAVEL No 1 During GTFS cleaning, a flag to identify whether unrealsitic trips (where vehicle would have to travel unrealistically fast) should be removed. These trips will be removed when set to 1. Setting 0 means this cleaning stage will not occur.
CALCULATE_SUMMARIES No 1 Whether GTFS trip and route summaries should be generated (counts by modality by date). These will be calcualted when set to 1. Setting to 0 will skip this step (with a log warning being raised).
BATCH_ORIG No 0 Whether origins should be batched to improve memory utilisation. Setting to 0 results in no origin/destination batching and if memory availablility allows will be the most performant approach. Setting to 1 will batch origins and can be helpful when memory limitiations impact larger urban centres.
CONFIG_FILE No default_config.toml The file name of the 'base' configuration toml file to use.
  1. Run the docker container (for each specific urban centre, as required):
docker compose up

The container will then start and provide progress updates throughout via CLI logs.

All outputs will then be available in data/<AREA_NAME>_<DATETIMESTAMP>/ where <AREA_NAME> is the name set inside the environment variable and <DATETIMESTEMP> is set at runtime. Logs are also available in data/<AREA_NAME>_<DATETIMESTAMP>/outputs/log/ in .txt format.

Notes:

  • A new outputs directory is build for each run.
  • The docker container automatically shutsdown once the run is complete.
  • The Makefile can be used to spin up instances of the container for a subset of urban centres. See Using the Makefile for more information.

Input Data

All input data should be placed within subdirectories of the data/inputs/ folder. This folder is linked to the docker container and will be used to read inputs locally.

  • GTFS data can be added within data/inputs/<GTFS_OSM_SUBDIR>/gtfs/
  • OSM data can be added within data/inputs/<GTFS_OSM_SUBDIR>/osm/
  • population data can be added within data/inputs/population/
  • urban centre data can be added within data/inputs/urban_centre/

Notes:

  • Changing this structure will lead to issues when running the container.
  • <GTFS_OSM_SUBDIR> corresponds to the value assigned to the GTFS_OSM_SUBDIR environment variable. Unless specified directly, this will default to the value of COUNTRY_NAME.

Config TOML

An updated .toml can be placed within data/inputs/ directory. This captures 'core' configuration parameters that will be used consistently across all urban centre analyses run. More details to follow when a specification has been finalised, but data/inputs/config/default_config.toml can be used as a template in the meantime.

Using the Makefile

Current known limitations

Below is a summary of the main currently known limitations. See the GitHub repo issues tab for more details.

  1. Does not have pyosmium/osmium-tool dependencies (validate_osm not useable) [#3] (#3)

Data Science Campus

At the Data Science Campus we apply data science, and build skills, for public good across the UK and internationally. Get in touch with the Campus at datasciencecampus@ons.gov.uk.

License

The code, unless otherwise stated, is released under the MIT Licence.

The documentation for this work is subject to © Crown copyright and is available under the terms of the Open Government 3.0 licence.