polish source code and docs for release

- rename arg work_dir to input_dir in read_demand();
- call read_demand() in test_find_shortest_path_for_agents() which
  is essential to set up agents;
- terminate test_find_shortest_path_for_agents() if there are no
  agents;
- fix bug in test_odme() on calling read_measurements();
- disable test_multimodal_dtalite() which will crash the testing process
  as run_DTALite() requires a different settings.yml;
- update docstrings for run_DTALite();
- conduct minor changes to docstrings for perform_column_generation()
  and perform_network_assignment();
- replace deprecated perform_column_generation() with find_ue() in
  usecases.md;
- update Public API for colgen and io;
- change version number from v0.9.8 to v0.9.9.

Author: jdlph

README.md

@@ -1,6 +1,6 @@
 # Path4GMNS
 [![platform](https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-red)](https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-red)
-[![Downloads](https://static.pepy.tech/badge/path4gmns)](https://pepy.tech/project/path4gmns) [![GitHub release](https://img.shields.io/badge/release-v0.9.8-brightgreen)](https://img.shields.io/badge/release-v0.8.2-brightgreen) ![Read the Docs](https://img.shields.io/readthedocs/path4gmns)
+[![Downloads](https://static.pepy.tech/badge/path4gmns)](https://pepy.tech/project/path4gmns) [![GitHub release](https://img.shields.io/badge/release-v0.9.9-brightgreen)](https://img.shields.io/badge/release-v0.8.2-brightgreen) ![Read the Docs](https://img.shields.io/readthedocs/path4gmns)
 [![](https://dcbadge.vercel.app/api/server/JGFMta7kxZ?style=flast)](https://discord.gg/JGFMta7kxZ)
 
 Path4GMNS is an open-source, cross-platform, lightweight, and fast Python path engine for networks encoded in [GMNS](https://github.com/zephyr-data-specs/GMNS). Besides finding static shortest paths for simple analyses, its main functionality is to provide an efficient and flexible framework for column-based (path-based) modeling and applications in transportation (e.g., activity-based demand modeling). Path4GMNS supports, in short,

docs/source/api.rst

@@ -28,21 +28,23 @@ path4gmns.conduct_odme
 
 path4gmns.colgen
 ================
+.. autofunction:: path4gmns.colgen.find_ue
 .. autofunction:: path4gmns.colgen.perform_column_generation
 .. autofunction:: path4gmns.colgen.perform_network_assignment
 
 
 path4gmns.io
 ============
-.. autofunction:: path4gmns.utils.read_network
-.. autofunction:: path4gmns.utils.read_zones
-.. autofunction:: path4gmns.utils.load_demand
-.. autofunction:: path4gmns.utils.load_columns
-.. autofunction:: path4gmns.utils.output_link_performance
-.. autofunction:: path4gmns.utils.output_agent_paths
-.. autofunction:: path4gmns.utils.output_zones
-.. autofunction:: path4gmns.utils.output_synthetic_zones
-.. autofunction:: path4gmns.utils.output_synthetic_demand
+.. autofunction:: path4gmns.io.read_demand
+.. autofunction:: path4gmns.io.read_measurements
+.. autofunction:: path4gmns.io.read_network
+.. autofunction:: path4gmns.io.load_demand
+.. autofunction:: path4gmns.io.load_columns
+.. autofunction:: path4gmns.io.output_link_performance
+.. autofunction:: path4gmns.io.output_agent_paths
+.. autofunction:: path4gmns.io.output_agent_trajectory
+.. autofunction:: path4gmns.io.output_synthetic_zones
+.. autofunction:: path4gmns.io.output_synthetic_demand
 
 
 path4gmns.simulation

docs/source/usecases.md

@@ -363,10 +363,10 @@ network.get_accessible_links(1, 15, 'w', time_dependent=True, demand_period_id=1
 
 Transportation equity is accessibility with respect to different demographics. Path4GMNS provides the following simple info and statistics on equity given a time budget and a segmentation of zones (e.g., zones can be grouped into a set of bins according to income level and each zone will have a unique bin index). The current implementation takes bin index of each zone from node.csv under column "bin_index" (via node-to-zone mapping), which is error prone. As a zone might have more than one node, it may encounter inconsistent bin indices over a set of nodes corresponding to the same zone. In case of that, the first bin index encountered for each zone in loading node.csv is always used for evaluation. 0 is taken as default if column "bin_index" or the value of an entry is missing.
 
-1. accessible zones.
-2. min accessibility. Each zone has a list of accessible zones given a time budget and a transportation mode. This metric refers to the zone with the minimum number of accessible zones. This number and the zone ID will both be output. Note that there could be multiple zones with the same minimum number of accessible zones and only the first zone will be in the output.
-3. max accessibility.
-4. mean accessibility. The average number of accessible zones over a bin of zones (corresponding to a specific demographic) given a time budget and a transportation mode.
+1. **accessible zones**.
+2. **min accessibility**. Each zone has a list of accessible zones given a time budget and a transportation mode. This metric refers to the zone with the minimum number of accessible zones. This number and the zone ID will both be output. Note that there could be multiple zones with the same minimum number of accessible zones and only the first zone will be in the output.
+3. **max accessibility**.
+4. **mean accessibility**. The average number of accessible zones over a bin of zones (corresponding to a specific demographic) given a time budget and a transportation mode.
 
 They can be obtained via Path4GMNS of v0.8.3 or higher in a way very similar to the process of evaluating accessibility.
 
@@ -426,7 +426,7 @@ simulation:
   resolution: 6
 ```
 
-perform_column_generation() shall be called in the first place to set up path for each agent before simulation.
+find_ue() shall be called in the first place to set up path for each agent before simulation.
 
 ```Python
 import path4gmns as pg
@@ -445,7 +445,7 @@ print('writing agent trajectories')
 pg.output_agent_trajectory(network)
 ```
 
-If you have route_assignment.csv (i.e.columns) from a previous run or DTALite, you can bypass perform_column_generation() and directly load it to conduct simulation.
+If you have route_assignment.csv (i.e.columns) from a previous run or DTALite, you can bypass find_ue() and directly load it to conduct simulation.
 
 ```python
 import path4gmns as pg

path4gmns/colgen.py

@@ -300,8 +300,7 @@ def perform_column_generation(column_gen_num, column_update_num, ui):
     ----
     You will need to call output_columns() and output_link_performance() to
     get the assignment results, i.e., paths/columns (in route_assignment.csv) and
-    assigned volumes and other link attributes on each link (in l
-    ink_performance.csv)
+    assigned volumes and other link attributes on each link (in link_performance.csv)
     """
     # make sure iteration numbers are both non-negative
     assert(column_gen_num>=0)
@@ -355,7 +354,7 @@ def update_links_using_columns(network):
 
 
 def perform_network_assignment(assignment_mode, column_gen_num, column_update_num, ui):
-    """DEPRECATED Column Generation API
+    """DEPRECATED Column Generation API. Use find_ue() instead!
 
     Keep it here as legacy support for existing users who already get used to it
     """

path4gmns/dtaapi.py

@@ -144,7 +144,7 @@ def run_DTALite():
     This version of DTALite includes all-new Logbook, enhanced scenario handling,
     improved I/O functionality, and so on.
 
-    Its source code can be found at https://github.com/asu-trans-ai-lab/DTALite.
+    Its source code can be found at https://github.com/asu-trans-ai-lab/DTALite/tree/feature/multimodal.
 
     Parameters
     ----------
@@ -156,11 +156,10 @@ def run_DTALite():
 
     Note
     ----
-    It is compatible with the classic DTALite and the corresponding data sets
-    from https://github.com/jdlph/Path4GMNS/tree/dev/data.
+    It is NOT compatible with the classic DTALite (i.e., perform_network_assignment_DTALite()).
 
-    Additional data set can be found at
-    https://github.com/asu-trans-ai-lab/DTALite/tree/main/data.
+    Only use the following data set from
+    https://github.com/asu-trans-ai-lab/DTALite/tree/feature/multimodal/data.
 
     Please run the script calling this API using system terminal rather than
     Python console for proper logging.

path4gmns/io.py

@@ -22,9 +22,9 @@
     'output_columns',
     'output_link_performance',
     'output_agent_paths',
+    'output_agent_trajectory,'
     'output_synthetic_zones',
-    'output_synthetic_demand',
-    'output_agent_trajectory'
+    'output_synthetic_demand'
 ]
 
 
@@ -1395,7 +1395,7 @@ def read_measurements(ui, input_dir='.'):
         print(f'the number of valid measurements is {record_no}\n')
 
 
-def read_demand(ui, use_synthetic_data = False, save_synthetic_data=True, work_dir='.'):
+def read_demand(ui, use_synthetic_data = False, save_synthetic_data=True, input_dir='.'):
     """ a dedicated API to read demand and zone information """
     A = ui._base_assignment
 
@@ -1417,7 +1417,7 @@ def read_demand(ui, use_synthetic_data = False, save_synthetic_data=True, work_d
             try:
                 at = A.get_agent_type_id(d.get_agent_type_str())
                 dp = A.get_demand_period_id(d.get_period())
-                _read_demand(work_dir,
+                _read_demand(input_dir,
                              d.get_file_name(),
                              at,
                              dp,
@@ -1447,7 +1447,7 @@ def read_demand(ui, use_synthetic_data = False, save_synthetic_data=True, work_d
             dp = A.get_demand_period_id(d.get_period())
             _read_zones(ui)
             _read_demand(
-                work_dir, filename, at, dp, A.network.zones, A.column_pool
+                input_dir, filename, at, dp, A.network.zones, A.column_pool
             )
             # early termination to load only one synthetic demand file
             return
@@ -1465,5 +1465,5 @@ def read_demand(ui, use_synthetic_data = False, save_synthetic_data=True, work_d
     print('data synthesis is complete!')
 
     if save_synthetic_data:
-        output_synthetic_zones(ui, work_dir)
-        output_synthetic_demand(ui, work_dir)
+        output_synthetic_zones(ui, input_dir)
+        output_synthetic_demand(ui, input_dir)

tests/test_dtalite.py

@@ -16,9 +16,11 @@ def test_classic_dtalite(sample_data_dir, mode = 1):
     chdir(ORIG_DIR)
 
 
-def test_multimodal_dtalite(sample_data_dir):
-    chdir(sample_data_dir)
+# disable it from now on (10/16/24) as run_DTALite() requires a different
+# settings.yml
+# def test_multimodal_dtalite(sample_data_dir):
+#     chdir(sample_data_dir)
 
-    run_DTALite()
+#     run_DTALite()
 
-    chdir(ORIG_DIR)
+#     chdir(ORIG_DIR)

tests/test_odme.py

@@ -19,7 +19,7 @@ def test_odme(sample_data_dir, tmp_output_dir):
         column_update_num = 20
         find_ue(network, column_gen_num, column_update_num)
 
-    read_measurements(input_dir=sample_data_dir)
+    read_measurements(network, input_dir=sample_data_dir)
     # ODME
     odme_update_num = 20
     conduct_odme(network, odme_update_num)

tests/test_sp.py

@@ -1,7 +1,7 @@
 from os.path import isfile
 from random import randint
 
-from path4gmns.io import output_agent_paths, read_network
+from path4gmns.io import output_agent_paths, read_demand, read_network
 
 
 def test_routing_engine(sample_data_dir):
@@ -29,12 +29,16 @@ def test_find_shortest_path(sample_data_dir):
 def test_find_shortest_path_for_agents(sample_data_dir, tmp_output_dir):
     """ find_path_for_agents has been DEPRECATED """
     network = read_network(input_dir=sample_data_dir)
+    read_demand(network, input_dir=sample_data_dir)
 
     # find agent paths under a specific mode defined in settings.yaml,
     # say, a (i.e., auto)
     # network.find_path_for_agents('a') or network.find_path_for_agents('auto')
     network.find_path_for_agents()
 
+    if network.get_agent_num() == 0:
+        return
+
     agent_id = randint(0, network.get_agent_num() - 1)
     # origin node id of agent
     network.get_agent_orig_node_id(agent_id)