A package to create activity-based models (for transport demand modelling)
- acbm
- Motivation and Contribution
- Installation
- How to Run the Pipeline
- Contributing
- License
Activity-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](https://www.gov.uk/government/publications/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. Activity-based modelling involves many steps, including 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](#related-work) for a list of different open-source tools).
To our knowledge, no open-source activity-based modelling 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
python -m pip install acbmFrom source:
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
│ │ │ ├── filtered
│ │ │ │ ├── nts_households.parquet
│ │ │ │ ├── nts_individuals.parquet
│ │ │ │ └── nts_trips.parquet
│ │ │ └── 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
│ │ │ ├── <region>>_people_hh.parquet (Generated in Script 1)
│ │ │ ├── <region>>_people_tu.parquet (Generated in Script 1)
│ │ │ ├── raw
│ │ │ │ ├── <region>_households.parquet
│ │ │ │ ├── <region>_info_per_msoa.json
│ │ │ │ ├── <region>.pb
│ │ │ │ ├── <region>_people.parquet
│ │ │ │ ├── <region>_time_use_diaries.parquet
│ │ │ │ ├── <region>_venues.parquet
│ │ │ │ ├── README.md
│ ├── interim
│ │ ├── assigning (Generated in Script 3)
│ │ └── matching (Generated in Script 2)
│ └── processed
│ ├── acbm_<config_name>_<date>
│ │ ├── activities.csv
│ │ ├── households.csv
│ │ ├── legs.csv
│ │ ├── legs_with_locations.parquet
│ │ ├── people.csv
│ │ └── plans.xml
│ ├── plots
│ │ ├── assigning
│ │ └── validationYou need to populate the data/external diectory 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
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. Specifically, it does not yet have functionality for activity generation (e.g. statistical matching or generative approaches), or constrained primary location assignment.
See CONTRIBUTING.md for instructions on how to contribute.
Distributed under the terms of the Apache license.