Configuration

TODO: link to the steps in the requirements.

This page describes all the key/value pairs that can be specified in the TOML configuration file.

It is recommended to have some basic knowledge on the TOML syntax, for example by reading this page.

Table of Contents

Notes

  • Path strings: It is recommended to use slash / instead of backslash \ as directory separator. The path can be absolute or relative to the working directory (i.e., the directory from which metropy is run).
  • Geospatial file: Either a .parquet file with a geometry column or any file that can be read with geopandas.read_file (e.g., shapefile, geopackage, GeoJson).

Complete exemple

TODO

Main variables

main_directory

  • Description: Directory where the files generated by metropy will be stored.
  • Allowed values: String representing a valid path.
  • Requirements: Required for all steps.
  • Example: "paris/output/"
  • Note: If the directory does not exist, it will be created automatically by metropy.

crs

  • Description: Projected coordinate system to be used for spatial operations.
  • Allowed values: Any value accepted bypyproj.CRS.from_user_input()
  • Requirements: Required for all steps involving spatial operations.
  • Example: "EPSG:2154" (Lambert projection for France)
  • Note: You can use the epsg.io website to find a projected coordinate system that is adapted for your study area. It is strongly recommended that the unit of measure is meter. If you use a coordinate system for an area of use that is not adapted or with an incorrect unit of measure, then some operations might fail or the results might be erroneous (like road length being overestimated).

osm_file

  • Description: Path to the OpenStreetMap file (.osm or .osm.pbf) with data for the simulation area.
  • Allowed values: String representing a valid path to a .osm or .osm.pbf filename.
  • Requirements: Conditionally required for steps simulation-area, osm-road-import and osm-walk-import.
  • Example: "data/osm/france-250101.osm.pbf"
  • Note: You can download extract of OpenStreetMap data for any region in the world through the Geofabrik website. You can also download data directly from the OSM website, using the “Export” button, although it is limited to small areas.

[simulation_area] table

bbox

  • Description: Bounding box to be used as simulation area.
  • Allowed values: List of 4 floats.
  • Requirements: Conditionally required for step simulation-area.
  • Example: [1.4777, 48.3955, 3.6200, 49.2032]
  • Note: The values need to be specified as [minx, miny, maxx, maxy], in the simulation’s CRS. If bbox_wgs = true, the values need to be specified in WGS 84 (longitude, latitude).

bbox_wgs

  • Description: Whether the bbox values are specified in the simulation CRS (false) or in WGS84 (true).
  • Allowed values: Boolean.
  • Requirements: Optional for step simulation-area (default is false).
  • Example: true

polygon_file

  • Description: Path to the geospatial file containing polygon(s) of the simulation area.
  • Allowed values: String representing a valid path to a geospatial file.
  • Requirements: Conditionally required for step simulation-area.
  • Example: "data/my_area.geojson"

aav_name

  • Description: Name of the Aire d’attraction des villes to be selected.
  • Allowed values: String of a value that appears in the column libaav2024 of the aav_filename file.
  • Requirements: Conditionally required for step simulation-area.
  • Example: "Paris"

aav_filename

  • Description: Path to the shapefile of the French’s Aires d’attraction des villes.
  • Allowed values: String representing a valid path to the .zip file or .shp file from INSEE (with column libaav20xx).
  • Requirements: Optional for step simulation-area.
  • Example: "data/aav2020_2024.zip"
  • Notes: When aav_filename is not specified but aav_name is set, metropy will attempt to automatically download the shapefile.

osm_admin_level

  • Description: Administrative level to be considered when reading administrative boundaries.
  • Allowed values: Integer.
  • Requirements: Conditionally required for step simulation-area.
  • Example: 6
  • Notes: See this page for a table with the meaning of all possible value for each country.

osm_name

  • Description: List of subdivision names to be considered when reading administrative boundaries.
  • Allowed values: List of strings.
  • Requirements: Conditionally required for step simulation-area.
  • Example: ["Madrid"]
  • Notes: The values are compared with the name=* tag of the OpenStreetMap features. Be careful, the name can sometimes be in the local language.

buffer

  • Description: Distance by which the polygon of the simulation area must be extended or shrinked.
  • Allowed values: Number.
  • Requirements: Optional for step simulation-area (default is 0).
  • Example: 500
  • Notes: The value is expressed in the unit of measure of the CRS (usually meter). Positive values extend the area, while negative values shrink it.

[osm_road_import] table

highways

  • Description: List of highway=* OpenStreetMap tags to be considered as valid road ways.
  • Allowed values: List of strings.
  • Requirements: Required for step osm-road-import.
  • Example: ["motorway", "motorway_link", "trunk", "trunk_link", "primary", "primary_link"]
  • Notes: For a list of highway tags with description, see the OpenStreetMap wiki.

urban_landuse

  • Description: List of landuse=* OpenStreetMap tags that define an urban area.
  • Allowed values: List of strings.
  • Requirements: Optional for step osm-road-import (default is to consider all the area as being rural).
  • Example: ["residential", "industrial", "commercial", "retail"]
  • Notes: For a list of landuse tags with description, see the OpenStreetMap wiki. The urban areas are used to defined an urban vs rural flag on roads, which is in turn used to define default values (e.g., default speed limit of 50 km/h on urban roads vs 80 km/h on rural roads).

urban_buffer

  • Description: Distance by which the polygons of the urban areas will be buffered.
  • Allowed values: Number.
  • Requirements: Optional for step osm-road-import (default is 0).
  • Example: 50
  • Notes: The value is expressed in the unit of measure of the CRS (usually meter). Positive values extend the area, while negative values shrink it. A road edge must be entirely contained within urban areas to be classified as a urban edge so it is recommended to use a positive value to correctly identify urban edges.