A tool for generating zone-to-zone travel demand based on grid cells or TAZs using gravity model
GRID2DEMAND: A tool for generating zone-to-zone travel demand based on grid cells or TAZs and gravity model
pip install grid2demand
If you encounter installation issues, please refer to the user guide for solutions.
from __future__ import absolute_import
import grid2demand as gd
if __name__ == "__main__":
# Specify input directory
input_dir = "your-data-folder"
# Initialize a GRID2DEMAND object
net = gd.GRID2DEMAND(input_dir=input_dir, use_zone_id=True, mode_type="auto")
# Load network: node and poi
net.load_network()
# Generate zone.csv from node by specifying number of x blocks and y blocks
net.net2grid(num_x_blocks=10, num_y_blocks=10)
# net.net2grid(cell_width=10, cell_height=10, unit="km")
# Load zone from zone.csv
net.taz2zone()
# Map zones with nodes and poi, viseversa
net.map_mapping_between_zone_and_node_poi()
# Calculate zone-to-zone distance matrix
net.calc_zone_od_distance_matrix(pct=1)
# Calculate demand by running gravity model
net.run_gravity_model()
# Save demand, zone, updated node, updated poi, agent to csv
net.save_results_to_csv(node=False, zone=False, agent=False, overwrite_file=False)
The grid2demand project welcomes your expertise and enthusiasm!
Small improvements or fixes are always appreciated. If you are considering larger contributions to the source code, please contact us through email: Xiangyong Luo, Dr. Xuesong Simon Zhou
Writing code isn't the only way to contribute to grid2demand. You can also:
For more information about the ways you can contribute to grid2demand, visit our GitHub. If you' re unsure where to start or how your skills fit in, reach out! You can ask by opening a new issue or leaving a comment on a relevant issue that is already open on GitHub.
If you use grid2demand in your research please use the following BibTeX entry:
Xiangyong Luo, Xuesong Simon Zhou (2023). xyluo25/grid2demand: Zenodo. https://doi.org/10.5281/zenodo.11212556
If you have not used Grid2demand before, here are some advices to get started.
Read the user guide or watch the video at https://www.youtube.com/watch?v=EfjCERQQGTs.
Obtain a map.osm or map.osm.pbf file for your area of interest at https://extract.bbbike.org/ or openstreetmap.org
Look at the examples at Google colab environment https://github.com/xyluo25/grid2demand/blob/main/tutorial/Colab%20SF_Example.ipynb
Install Python, Grid2demand and QGIS on your computer or using Google Colab environment to modify one of the examples to implement your own model.
Post your questions on the users group:
GitHub: https://github.com/asu-trans-ai-lab/grid2demand/issues GitHub: https://github.com/xyluo25/grid2demand/issues
Open-source tool of grid2demand aims to provide an open-source quick demand generation python package, which can work anywhere in the world, thanks to open data from OpenStreetMap users.
To know more about this tool, please check out the 3rd mini teaching lesson in our podcast series https://www.youtube.com/watch?v=EfjCERQQGTs.
Gird2demand is an open-source trip generation and distribution tool for teaching transportation planning and applications. It generates zone-to-zone travel demand based on alpha-numeric grid zones. Users can obtain zone-to-zone and node-to-node travel demand with a few lines of python code based on OpenStreetMap and OSM2GMNS.
Mini teaching lesson: https://www.youtube.com/watch?v=EfjCERQQGTs
Trip generation and trip distribution are the first 2 steps in the larger context of the 4-step process in transportation planning. The standard four steps are briefly described below.
Trip generation is a procedure that uses socioeconomic data (e.g., household size, income, etc.) to estimate the number of person trips for a modeled time period (e.g., daily, peak hour) at a Traffic Analysis Zone (TAZ) level. A person trip involves a single person leaving from an origin and arriving at a single destination, and each trip has a classification/purpose based on typical classification such as home-based-work (HBW), home-based-other (HBO), and non-home-based (NHB).
In the four-step process, there are two typical methods used to predict trips based on attributes:
After estimating the total number of trips produced, the trips are often separated by different purposes (e.g., HBW, HBO, NHB).
An alternative approach to modeling trips is to model tours, which can be thought of as a series of linked trips. Tours are typically used in Activity-Based Models (ABM), where daily travel activities are generated based on activity patterns for households.
In trip-based transportation planning, for a home-based trip, a production is related to the home end/location, while an attraction is related to the non-home end/location. For a non-home-based trip, a production is related to the origin location, and an attraction is related to the destination location. Trips entering and leaving a zone should balance - if a person leaves a zone, they should also return; if a person enters a zone, they should also leave.
For example, if a person travels from home to work and then from work to home on a certain day, then 2 home-based work trip productions are generated at the home TAZ, and two attractions related at his or her work location TAZ.
Productions are typically modeled as a function of population and/or number of households, as well as income levels or auto ownership. Other explanatory variables might be used, such as the number of workers, but we need to make sure explanatory variables are often not interrelated and correlated with each other.
Attractions are often modeled as a function of the number of households and/or number of employees, where employment may be broken down by different types (e.g., retail, office, service, and other). Again, other explanatory variables can also be used, such as commercial floor space or CBD (Central Business District) variables, but the same checks for correlation between variables should be utilized. Attractions tend to be more difficult to measure/estimate, and we tend to have less trust in these estimates. For more information, users can read NCHRP Report 365: “Travel Estimation Techniques, CH 3 trip generation and NCHRP Report 716: Travel Demand Forecasting: Parameters and Techniques, CH 4.4 Trip Generation.
In transportation planning, accessibility is first defined as the potential of opportunities for traveler interaction. the potential opportunity for traveler interaction is positively associated with accessibility. Typically, accessibility captures the extent of the attractiveness of each potential destination and some researchers represent accessibility as the amount of activity locations potentially reachable within a given travel time or distance from an origin location.
One of the goals of transportation system construction and management is to improve individuals’ accessibility or the ease of reaching desired activities, destinations, and services. In general, quantitative accessibility measures describe how many and how easily destinations can be reached from a particular zone. For more information, users can check https://tfresource.org/topics/Accessibility.html.
There are a variety of trip distribution formulations. Among recent travel models, two formulations dominate: the gravity model and the destination choice model.
For each OD pair, a typical gravity model is applied to calculate zone-to-zone demand volume. In the gravity model, the trips produced at an origin and attracted to a destination are directly proportional to the total trip productions at the origin and the total attractions at the destination with "friction factor", which represents the reluctance or impedance of persons to make trips of various duration or distances. A gravity model may be “singly-constrained” or “doubly-constrained”. For more information, please visit https://tfresource.org/topics/Trip_distribution.html. and http://www.princeton.edu/~alaink/Orf467F12/The%20Gravity%20Model.pdf
For each OD pair, a gravity model to calculate zone-to-zone demand volume is formulated as follows.
Grid2demand is a quick demand generation tool based on the trip generation and trip distribution methods of the standard 4-step travel model for teaching transportation planning and applications. By taking advantage of the OSM2GMNS tool to obtain a routable transportation network from OpenStreetMap, Grid2demand aims to further utilize Point of Interest (POI) data to construct a trip demand matrix aligned with standard travel models.
The area of interest is partitioned into an alphanumeric grid (also known as atlas grid), in which each cell is identified by a combination of a letter and a number. The trip generation step is performed at the POI node level using ITE trip generation tables (https://www.ite.org/technical-resources/topics/trip-and-parking-generation/trip-generation-10th-edition-formats/) or other trip rate references.
When partitioning grid cells and calculating accessibility, World Geodetic System-1984 Coordinate System is applied to convert coordinates to length. The trip distribution is carried out using a typical gravity model. The data flow chart is illustrated in the following table and figure.
Description of Data Files
| Step | Process | Input File or Parameter | Output File | Method |
|---|---|---|---|---|
| 0 | Network files preparation | map file from OpenStreetMap | node.csv, link.csv, poi.csv | Osm2gmns tool |
| 1 | Input files reading | node.csv, poi.csv | ||
| 2 | Zone generation and grid partition | Number of blocks or grid scales in defined units of the area of interest (optional) | zone.csv, poi.csv (update with zone id) | Alphanumeric grid |
| 3 | Trip generation | poi_trip_rate.csv (optional), trip purpose | poi_trip_rate.csv (output/update with utilization notes), node.csv (update with zone id and demand values) | Trip rate method |
| 4 | OD distance matrix | zone.csv | OD matrix | Distance between zone centroids |
| 5 | Trip distribution | Trip purpose, friction factor coefficients | demand.csv, zone,csv (update with total production and attraction in each zone) | Gravity model |
| 6 | Agent generation | demand.csv | agent.csv | Random sampling of node-to-node agents according to zone-to-zone demand |
| 7 | Visualization | QGIS or NEXTA |
For the entire package, the input files include the network files in GMNS format (node.csv, link.csv) as well as poi.csv, generated by the OSM2GMNS tool.
Users can download a default poi_trip_rate.csv from https://github.com/asu-trans-ai-lab/grid2demand/blob/main/examples/data_folder/poi_trip_rate.csv and apply further adjustments based on local traffic conditions.
The final output files include zone.csv, accessibility.csv, demand.csv for zone-to-zone OD demand matrix, and input_agent.csv for node-to-node agent files which can be used by agent-based simulators such as AB Street and DTALite. Accordingly, node.csv and poi.csv are updated with assigned zone information.
To facilitate hierarchical and multi-resolution spatial computing, grid cells are used to aggregate trips to traffic analysis zones, while standard TAZs are typically defined based on census tracts. Users can specify the number of cells per row and per column or the width and height of each grid cell (in meters) for the area of interest. To maintain a consistent mapping, we use a fractional value in terms of the degree at different latitudes to represent different lengths on a flat surface. That is, a value of 0.01 longitudinal degrees at 60 degrees latitude is equivalent to 0.558 km on a flat surface. Thus, users can provide a latitude value of the area of interest, and the software will identify the closest latitude in the following table and use the equivalent distance to measure for that area.
Moreover, some nodes in the network are marked as boundary nodes in node.csv to describe the entrance or exit points with respect to the area of interest. Thus, we add virtual zones around the grid area’s boundary to aggregate demand from outside the area of interest, which are regarded as “gates” or external stations.
To enable detailed modeling of trip generation from parking lots and buildings, different types of POI nodes are specifically covered in file poi.csv, extracted from the original OSM file. The user can supply more information in poi.csv in case of missing values. The trip generation process used in grid2demand has the following 3 sub-steps.
A sample poi_trip_rate table is listed below.
For each boundary node (such as freeway or arterial’s endpoint at the boundary of the area) which stands for a gate to enter or leave the area, the default values of production and attraction are set to be 1000.
In the current version, accessibility is measured by zone-to-zone straight-line distance according to zone centroid coordinates. A more advanced version will be provided in the future to use the shortest path algorithm for computing end-to-end driving or multimodal travelling distance and costs.
As mentioned above, a typical gravity model is applied to calculate zone-to-zone demand volume. The trip purpose and friction factor coefficients can be defined by users or by default. The default values under three typical trip purposes are listed in the following table.
In the future, output demand.csv can act as one of multiple data sources for a hierarchical travel demand estimation and input_agent.csv can be directly used for assignment by DTALite and for other travel models. For more information, please visit https://www.researchgate.net/publication/325131295_Hierarchical_travel_demand_estimation_using_multiple_data_sources_A_forward_and_backward_propagation_algorithmic_framework_on_a_layered_computational_graph.
We will use the University of Maryland, College Park as an example to illustrate how to use grid2demand.
Step 1: Installation
You can install the latest release of grid2demand at PyPI (https://pypi.org/project/grid2demand/) via pip:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
pip install grid2demand
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
After running the command above, the grid2demand package along with two required dependency packages (numpy, pandas) will be installed on your computer (if they have not been installed yet).
Step 2: Determine the boundary of interest and download .osm file from OpenStreetMap (https://www.openstreetmap.org/)
Step 3: Execute OSM2GMNS to get network files in GMNS format
Open the Python IDE, such as Pycharm, for a typical configuration. Then, use OSM2GMNS to convert the map.osm file in OSM format into a network file in GMNS format.
Notes: User guide for osm2gmns can be found at https://osm2gmns.readthedocs.io/en/latest/.
import osm2gmns as og
# load network from osm file
net = og.getNetFromFile("map.osm", network_type=('railway', 'aeroway', 'auto', 'walk', 'bile'), POI=True, default_lanes=True, default_speed=True)
og.connectPOIWithNet(net)
og.outputNetToCSV(net, output_folder)
Your will see node.csv, poi.csv and link.csv in your output_folder <img src="docs/media/bc783b917bac32c27b66e4649a472088.png" style="zoom:80%;" />
Please note that poi.csv might have different degrees of missing information. Please supply additional accurate POI-type information if needed.
Step 4: Execute grid2demand Python code
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
import grid2demand as gd
input_dir = "Directory-to-your-node.csv-and-poi.csv"
net = gd.GRID2DEMAND(input_dir)
Users can customize the number of grid cells by setting “num_x_blocks” and“num_y_blocks”.
Users can customize the cell’s width and height in prefered units by setting “cell_width”,“cell_height” and "unit").
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
# load node and poi
net.load_network()
# create zone
net.net2grid(num_x_blocks=10,num_y_blocks=10)
# or generate zone based on grid size with 10 km width and 10 km height for each zone
# net.net2grid(cell_width=10, cell_height=10, unit='km')
# Synchronize geometry info between zone, node and poi
net.map_mapping_between_zone_and_node_poi()
Users can customize poi_trip_rate.csv by adding an external file folder location according to different trip purposes. By default, the trip purpose is set as purpose 1.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
# Generate poi trip rate for each poi
net.gen_poi_trip_rate(trip_rate_file="", trip_purpose=1)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
# Generate node production attraction for each node based on poi_trip_rate
net.gen_node_prod_attr()
# Calculate zone production and attraction based on node production and attraction
net.calc_zone_prod_attr()
Users need to input the latitude value of the area of interest. A latitude of 30 degrees is selected as the default. On the other hand, users can customize the accessibility matrix by setting the external folder of file accessibility.csv.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
# Calculate zone-to-zone od distance matrix
net.calc_zone_od_distance_matrix()
Users need to input the trip purpose and the friction factor coefficients. The default values of HBW, HBO and NHB are described above.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
# Run gravity model to generate agent-based demand
net.run_gravity_model()
Agent-based node-to-node demand will be generated randomly according to zone-to-zone demand obtained by the gravity model.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
# generate agent-based demand
net.gen_agent_based_demand()
One can configure the working dictionary in the Python IDE (e.g., Pycharm) before executing grid2demand. The files in the working folder will be used to obtain zone-to-zone demand with generated five output files highlighted in blue below. The output files will be saved in the current folder as the working dictionary.
# You can also view and edit the package setting by using gd.pkg_settings
print(net.pkg_settings)
# Output demand, agent, zone, zone_od_dist_table, zone_od_dist_matrix files
net.save_results_to_csv(agent=True)
Step 5: Visualization in QGIS
Open QGIS and add Delimited Text Layer to load the demand.csv and other files (with geometry info).
Then open the “Properties” window of the demand layer. Set the symbology as graduated symbols by size.
The zone-to-zone demand volume can be visualized with a base map.
FAQs
A tool for generating zone-to-zone travel demand based on grid cells or TAZs using gravity model
We found that grid2demand demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 6 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Bun 1.2.19 introduces isolated installs for smoother monorepo workflows, along with performance boosts, new tooling, and key compatibility fixes.
Security News
Popular npm packages like eslint-config-prettier were compromised after a phishing attack stole a maintainer’s token, spreading malicious updates.
Security News
/Research
A phishing attack targeted developers using a typosquatted npm domain (npnjs.com) to steal credentials via fake login pages - watch out for similar scams.