Merge pull request #23 from xyluo25/main

update docs

.gitignore

@@ -15,7 +15,6 @@ x64/
 **log.txt
 *__pycache__*
 **.egg-info/*
-*setup.py
 *PKG-INFO*
 *Tutorial_PyPI.md
 *dist/*

README_pkg.md

@@ -1,10 +1,10 @@
 ## Project description
 
-GRID2DEMAND: A tool for generating zone-to-zone travel demand based on grid cells
+GRID2DEMAND: A tool for generating zone-to-zone travel demand based on grid cells or TAZs and gravity model
 
 ## Introduction
 
-Grid2demand is an open-source 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 OSM2GMNS tool to obtain routable transportation network from OpenStreetMap, Grid2demand aims to further utilize Point of Interest (POI) data to construct trip demand matrix aligned with standard travel models.
+Grid2demand is an open-source 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 OSM2GMNS tool to obtain route-able transportation network from OpenStreetMap, Grid2demand aims to further utilize Point of Interest (POI) data to construct trip demand matrix aligned with standard travel models.
 
 You can get access to the introduction video with the link: [https://www.youtube.com/watch?v=EfjCERQQGTs&t=1021s](https://www.youtube.com/watch?v=EfjCERQQGTs&t=1021s)
 
@@ -22,87 +22,129 @@ If you meet installation issues, please refer to the [user guide](https://github
 
 ## Simple Example
 
+### Generate Demand with node.csv and poi.csv
+
+1. Create zone from node.csv (the boundary of nodes), this will generate grid cells (num_x_blocks, num_y_blocks, or x length and y length in km for each grid cell)
+2. Generate demands for between zones (utilize nodes and pois)
+
 ```python
 from __future__ import absolute_import
-from grid2demand import GRID2DEMAND
+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)
+
+    # load network: node and poi
+    net.load_network()
+
+    # Generate zone dictionary from node dictionary by specifying number of x blocks and y blocks
+    net.net2zone(num_x_blocks=10, num_y_blocks=10)
+    # net.net2zone(cell_width=10, cell_height=10, unit="km")
 
+    # Calculate demand by running gravity model
+    net.run_gravity_model()
+
+    # Save demand, zone, updated node, updated poi to csv
+    net.save_results_to_csv()
+```
+
+# Generate Demand with node.csv, poi.csv and zone.csv (geometry filed in zone.csv)
+
+```python
+from __future__ import absolute_import
+import grid2demand as gd
 
 if __name__ == "__main__":
 
-    # Step 0: Specify input directory, if not, use current working directory as default input directory
-    input_dir = "./datasets/ASU"
+    # Specify input directory
+    path_node = "your-path-to-node.csv"
+    path_poi = "your-path-to-poi.csv"
+    path_zone = "your-path-to-zone.csv"  # zone_id, geometry are required columns
 
     # Initialize a GRID2DEMAND object
-    gd = GRID2DEMAND(input_dir)
+    net = gd.GRID2DEMAND(zone_file = path_zone, node_file = path_node, poi_file = path_poi)
 
-    # Step 1: Load node and poi data from input directory
-    node_dict, poi_dict = gd.load_network.values()
+    # load network: node and poi
+    net.load_network()
 
-    # Step 2: Generate zone dictionary from node dictionary by specifying number of x blocks and y blocks
-    zone_dict = gd.net2zone(node_dict, num_x_blocks=10, num_y_blocks=10)
+    # Generate zone
+    net.taz2zone()
 
-    # Step 2: Generate zone based on grid size with 10 km width and 10km height for each zone
-    # zone_dict = gd.net2zone(node_dict, cell_width=10, cell_height=10)
+    # Calculate demand by running gravity model
+    net.run_gravity_model()
 
-    # Step 2: Generate zone dictionary from zone.cvs(TAZs) prepared from users.
-    # zone_dict = gd.taz2zone()
-
-    # Step 3: synchronize geometry info between zone, node and poi
-    #       add zone_id to node and poi dictionaries
-    #       also add node_list and poi_list to zone dictionary
-    updated_dict = gd.sync_geometry_between_zone_and_node_poi(zone_dict, node_dict, poi_dict)
-    zone_dict_update, node_dict_update, poi_dict_update = updated_dict.values()
+    # Save demand, zone, updated node, updated poi to csv
+    net.save_results_to_csv(overwrite_file=True)
+```
 
-    # Step 4: Calculate zone-to-zone od distance matrix
-    zone_od_distance_matrix = gd.calc_zone_od_distance_matrix(zone_dict_update)
+# Generate Demand with node.csv, poi.csv and zone.csv (x_coord, y_coord fields represent zone centroids)
 
-    # Step 5: Generate poi trip rate for each poi
-    poi_trip_rate = gd.gen_poi_trip_rate(poi_dict_update)
+```python
+from __future__ import absolute_import
+import grid2demand as gd
+
+if __name__ == "__main__":
 
-    # Step 6: Generate node production attraction for each node based on poi_trip_rate
-    node_prod_attr = gd.gen_node_prod_attr(node_dict_update, poi_trip_rate)
+    # Specify input directory
+    path_node = "your-path-to-node.csv"
+    path_poi = "your-path-to-poi.csv"
+    path_zone = "your-path-to-zone.csv"  # zone_id, x_coord, y_coord are required columns
 
-    # Step 6.1: Calculate zone production and attraction based on node production and attraction
-    zone_prod_attr = gd.calc_zone_prod_attr(node_prod_attr, zone_dict_update)
+    # Initialize a GRID2DEMAND object
+    net = gd.GRID2DEMAND(zone_file = path_zone, node_file = path_node, poi_file = path_poi)
 
-    # Step 7: Run gravity model to generate agent-based demand
-    df_demand = gd.run_gravity_model(zone_prod_attr, zone_od_distance_matrix)
+    # load network: node and poi
+    net.load_network()
 
-    # Step 8: generate agent-based demand
-    df_agent = gd.gen_agent_based_demand(node_prod_attr, zone_prod_attr, df_demand=df_demand)
+    # Generate zone
+    net.taz2zone()
 
-    # You can also view and edit the package setting by using gd.pkg_settings
-    print(gd.pkg_settings)
+    # Calculate demand by running gravity model
+    net.run_gravity_model()
 
-    # Step 9: Output demand, agent, zone, zone_od_dist_table, zone_od_dist_matrix files
-    gd.save_demand
-    gd.save_agent
-    gd.save_zone
-    gd.save_zone_od_dist_table
-    gd.save_zone_od_dist_matrix
+    # Save demand, zone, updated node, updated poi to csv
+    net.save_results_to_csv(overwrite_file=True)
 ```
 
-## Visualization
+# Generate Demand with node.csv (if zone_id field exist, generated zone boundary cover zone_id that are not empty) and poi.csv
+
+```python
+from __future__ import absolute_import
+import grid2demand as gd
+
+if __name__ == "__main__":
+
+    # Specify input directory
+    path_node = "your-path-to-node.csv"  # make sure you have zone_id field in node.csv
+    path_poi = "your-path-to-poi.csv"
 
-Option 1: Open [QGIS](https://www.qgis.org/) and add Delimited Text Layer of the files.
+    # Initialize a GRID2DEMAND object
+    net = gd.GRID2DEMAND(node_file = path_node, poi_file = path_poi, use_zone_id=True)
 
-Option 2: Upload files to the website of [ASU Trans+AI Lab](https://asu-trans-ai-lab.github.io/index.html#/) and view input and output files.
+    # load network: node and poi
+    net.load_network()
 
-Option 3: Import input_agent.csv to [A/B Street](https://a-b-street.github.io/docs/howto/asu.html) and view dynamic simulation of the demand.
+    # Generate zone dictionary from node dictionary by specifying number of x blocks and y blocks
+    net.net2zone(num_x_blocks=10, num_y_blocks=10)
+    # net.net2zone(cell_width=10, cell_height=10, unit="km")
 
-## User guide
+    # Calculate demand by running gravity model
+    net.run_gravity_model(zone_prod_attr, zone_od_distance_matrix)
 
-Users can check the [user guide](https://github.com/asu-trans-ai-lab/grid2demand/blob/main/README.md) for a detailed introduction of grid2demand.
+    # Save demand, zone, updated node, updated poi to csv
+    net.save_results_to_csv(overwrite_file=True)
+```
 
 ## Call for Contributions
 
 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 :  luoxiangyong01@gmail.com
-
-    Dr. Xuesong Simon Zhou :  xzhou74@asu.edu
+Small improvements or fixes are always appreciated. If you are considering larger contributions to the source code, please contact us through email: [Xiangyong Luo](mailto:luoxiangyong01@gmail.com), [Dr. Xuesong Simon Zhou](mailto:xzhou74@asu.edu)
 
 Writing code isn't the only way to contribute to grid2demand. You can also:
 
@@ -120,6 +162,5 @@ For more information about the ways you can contribute to grid2demand, visit [ou
 
 If you use grid2demand in your research please use the following BibTeX entry:
 
-```
-Xiangyong Luo, Dustin Carlino, and Xuesong Simon Zhou. (2023). xyluo25/grid2demand: new lease to v0.3.5-rc.2 (0.3.5-rc.2). Zenodo. https://doi.org/10.5281/zenodo.8397105
-```
+
+Xiangyong Luo, Dustin Carlino, and Xuesong Simon Zhou. (2023). [xyluo25/grid2demand](https://github.com/xyluo25/grid2demand/): Zenodo. https://doi.org/10.5281/zenodo.11212556

README_pypi.md

@@ -0,0 +1,84 @@
+<!--
+ *  Created Date: Sunday, May 26th 2024
+ *  Contact Info: luoxiangyong01@gmail.com
+ *  Author/Copyright: Mr. Xiangyong Luo
+-->
+
+## Project description
+
+GRID2DEMAND: A tool for generating zone-to-zone travel demand based on grid cells or TAZs and gravity model
+
+## Introduction
+
+Grid2demand is an open-source 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 OSM2GMNS tool to obtain route-able transportation network from OpenStreetMap, Grid2demand aims to further utilize Point of Interest (POI) data to construct trip demand matrix aligned with standard travel models.
+
+You can get access to the introduction video with the link: [https://www.youtube.com/watch?v=EfjCERQQGTs&amp;t=1021s](https://www.youtube.com/watch?v=EfjCERQQGTs&t=1021s)
+
+## Quick Start
+
+Users can refer to the [code template and test data set](https://github.com/asu-trans-ai-lab/grid2demand) to have a quick start.
+
+## Installation
+
+```python
+pip install grid2demand
+```
+
+If you meet installation issues, please refer to the [user guide](https://github.com/asu-trans-ai-lab/grid2demand) for solutions.
+
+## Simple Example
+
+### Generate Demand with node.csv and poi.csv
+
+1. Create zone from node.csv (the boundary of nodes), this will generate grid cells (num_x_blocks, num_y_blocks, or x length and y length in km for each grid cell)
+2. Generate demands for between zones (utilize nodes and pois)
+
+```python
+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)
+
+    # load network: node and poi
+    net.load_network()
+
+    # Generate zone dictionary from node dictionary by specifying number of x blocks and y blocks
+    net.net2zone(num_x_blocks=10, num_y_blocks=10)
+    # net.net2zone(cell_width=10, cell_height=10, unit="km")
+
+    # Calculate demand by running gravity model
+    net.run_gravity_model()
+
+    # Save demand, zone, updated node, updated poi to csv
+    net.save_results_to_csv()
+```
+
+## Call for Contributions
+
+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](mailto:luoxiangyong01@gmail.com), [Dr. Xuesong Simon Zhou](mailto:xzhou74@asu.edu)
+
+Writing code isn't the only way to contribute to grid2demand. You can also:
+
+* review pull requests
+* help us stay on top of new and old issues
+* develop tutorials, presentations, and other educational materials
+* develop graphic design for our brand assets and promotional materials
+* translate website content
+* help with outreach and onboard new contributors
+* write grant proposals and help with other fundraising efforts
+
+For more information about the ways you can contribute to grid2demand, visit [our GitHub](https://github.com/asu-trans-ai-lab/grid2demand). 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.
+
+## Citing grid2demand
+
+If you use grid2demand in your research please use the following BibTeX entry:
+
+Xiangyong Luo, Dustin Carlino, and Xuesong Simon Zhou. (2023). [xyluo25/grid2demand](https://github.com/xyluo25/grid2demand/): Zenodo. https://doi.org/10.5281/zenodo.11212556