A package to create activity-based models (for transport demand modelling)
- acbm
- Motivation and Contribution
- Installation
- How to Run the Pipeline
- Future Work
- Related Work
- Contributing
- License
Agent-based models have emerged as an alternative to traditional 4-step transport demand models. They provide a more detailed framework by modeling travel as a sequence of activities, accounting for when, how, and with whom individuals participate. They can integrate household interactions, spatial-temporal constraints, are well suited to model on demand transport services (which are becoming increasingly common), and look at the equity implications across transport scenarios.
Despite being increasingly popular in research, adoption in industry has been slow. A couple of factors have influenced this. The first is inertia and well-established guidelines on 4-step models. However, this is changing; in 2024, the UK Department for Transport released its first Transport Analysis Guidance on activity and agent-based models (See TAG unit M5-4 agent-based methods and activity-based demand modelling). Other initiatives, such as the European Association of Activity-Based Modeling are also being established to try and increase adoption of activity-based modelling and push research into practice.
Another factor is tool availability. Agent-based modelling requires detailed individual travel data as input (what we are referring to as activity-based models, or activity-based travel demand). The creation of such datasets involves: synthetic population generation, activity sequence generation, and (primary and secondary) location assignment. Many tools exist for serving different steps, but only a couple of tools exist to run an entire, configurable pipeline, and they tend to be suited to the data of specific countries (see Related Work for a list of different open-source tools).
To our knowledge, no open-source activity-based travel demand generation pipeline exists for the UK. This repository allows researchers to run the entire pipeline for any region in the UK, with the output being a synthetic population with daily activity diaries and locations for each person. The pipeline is meant to be extendible, and we aim to plug in different approaches developed by others in the future. The output is a complete synthetic population with activity diaries and locations, which can be used directly as input into MATSim or other agent-based transport models.
This package is built using Poetry. To install the package, you will need to have Poetry installed. You can install it by following the instructions on the Poetry website.
Once you have Poetry installed, you can clone the repository and install the package by running the following commands in your terminal:
git clone https://github.com/alan-turing-institute/acbm
cd acbm
poetry installThe pipeline is a series of scripts that are run in sequence to generate the activity-based model. There are a few external datasets that are required. The data and config directories are structured as follows:
├── config
│ ├── <your_config_1>.toml
│ ├── <your_config_2>.toml
├── data
│ ├── external
│ │ ├── boundaries
│ │ │ ├── MSOA_DEC_2021_EW_NC_v3.geojson
│ │ │ ├── oa_england.geojson
│ │ │ ├── study_area_zones.geojson
│ │ ├── census_2011_rural_urban.csv
│ │ ├── centroids
│ │ │ ├── LSOA_Dec_2011_PWC_in_England_and_Wales_2022.csv
│ │ │ └── Output_Areas_Dec_2011_PWC_2022.csv
│ │ ├── MSOA_2011_MSOA_2021_Lookup_for_England_and_Wales.csv
│ │ ├── nts
│ │ │ └── UKDA-5340-tab
│ │ │ ├── 5340_file_information.rtf
│ │ │ ├── mrdoc
│ │ │ │ ├── excel
│ │ │ │ ├── pdf
│ │ │ │ ├── UKDA
│ │ │ │ └── ukda_data_dictionaries.zip
│ │ │ └── tab
│ │ │ ├── household_eul_2002-2022.tab
│ │ │ ├── individual_eul_2002-2022.tab
│ │ │ ├── psu_eul_2002-2022.tab
│ │ │ ├── trip_eul_2002-2022.tab
│ │ │ └── <other_nts_tables>.tab
│ │ ├── travel_times
│ │ │ ├── oa
│ │ │ | ├── travel_time_matrix.parquet
| | │ └── msoa
│ │ │ └── travel_time_matrix.parquet
│ │ ├── ODWP01EW_OA.zip
│ │ ├── ODWP15EW_MSOA_v1.zip
│ │ └── spc_output
│ │ └── raw
│ │ ├── <region>_households.parquet
│ │ ├── <region>_info_per_msoa.json
│ │ ├── <region>.pb
│ │ ├── <region>_people.parquet
│ │ ├── <region>_time_use_diaries.parquet
│ │ ├── <region>_venues.parquet
│ │ └── README.md
│ └── outputs
│ └- <config_id>
│ │
│ ├── interim
│ │ ├── <region>>_people_hh.parquet (Generated in Script 1)
│ │ ├── assigning (Generated in Script 3)
│ │ └── matching (Generated in Script 2)
│ ├── logs
│ ├── osmox
│ │ ├── <region>.osm.pbf
│ │ └── <region>_epsg_<3857>.parquet
│ │ └── <region>_epsg_<your_epsg>.parquet
│ ├── plots
│ │ ├── assigning
│ │ └── validation
│ ├── activities.csv
│ ├── households.csv
│ ├── legs.csv
│ ├── legs_with_locations.parquet
│ ├── people.csv
│ ├── plans.xml
│ ├── nts_households.parquet
│ ├── nts_individuals.parquet
│ └── nts_trips.parquetYou need to populate the data/external directory with the required datasets. A guide on where to find / generate each dataset can be found in the data/external/README.md
You need to create a config file in the config directory. The config file is a toml file that contains the parameters for the pipeline. A guide on how to set up the config file can be found in the config/README.md
The scripts are listed in order of execution in the scripts/run_pipeline.sh bash file
You can run the pipeline by executing the following command in the terminal from the base directory:
bash ./scripts/run_pipeline.sh config/<your_config_file>.tomlwhere your config file is the file you created in Step 2.
For details on what each script does, you can check the scrips/README.md and the WIKI
If you use acbm for research purposes, please consider citing it
Mahfouz, H., Greenbury, S. F., Zhang, B., Lynn, S., & Cheng, T. (2025). A reproducible pipeline for activity-based travel demand generation in England. Environment and Planning B: Urban Analytics and City Science, https://doi.org/10.1177/23998083251379620
We aim to include different options for each step of the pipeline. Some hopes for the future include:
- Bayesian Network approach to generate activities
- Implement a Deep Learning approach to generate activities (see package below)
- Workzone assignment: Plug in Neural Spatial Interaction Approach
There are a number of open-source tools for different parts of the activity-based modelling pipeline. Some of these include:
- Eqasim
- ActivitySim
- PAM: PAM has functionality for different parts of the pipeline, but itis not clear how to use it to create an activity-based model for an entire population.
See CONTRIBUTING.md for instructions on how to contribute.
Distributed under the terms of the Apache license.