enhance tutorial over the legacy way

- output origin node and destination node of each agent in agent_paths.csv,
  and change header 'volume' to 'OD volume' to avoid confusion;
- enhance exception message when an invalid agent_no as a result of an
  invalid agent_id is encountered in _get_agent();
- udpate README on Major Updates introduced in v0.8.7a1.

Author: jdlph

README.md

@@ -33,7 +33,7 @@ The Python modules are written in **Python 3.x**, which is the minimum requireme
 
 ## Quick Start
 
-v0.8.7a1 includes several important changes in user interface. We highly recommend that you go through the [tutorial](https://github.com/jdlph/Path4GMNS/tree/dev/tests/tutorial.ipynb) written in Jupyter notebook with step-by-step demonstration using the latest release, no matter you are one of the existing users or new to Path4GMNS.
+v0.8.7a1 as a hot fix over v0.8.6 includes several important changes in user interface. We highly recommend that you go through the [tutorial](https://github.com/jdlph/Path4GMNS/tree/dev/tests/tutorial.ipynb) written in Jupyter notebook with step-by-step demonstration using the latest release, no matter you are one of the existing users or new to Path4GMNS.
 
 ## User Manual
 
@@ -559,6 +559,10 @@ DTALite uses arrays rather than STL containers to store columns. These arrays ar
 22. More robust parsing functions (v0.8.6)
 23. Fix crucial bug in column generation module which will lead to wrong results if a zone has multiple nodes (v0.8.6)
 24. Fix crucial bug in setting up the capacity of each VDFPeriod instance if the input is missing from link.csv (v0.8.6)
+25. Add backwards compatibility on deprecated default agent type of p or passenger (v0.8.7a1)
+26. Fix potential issue that bin_index might not start from zero when all zones have the same number of nodes in _synthesize_bin_index() (v0.8.7a1)
+27. Fix potential zero division issue in _synthesize_bin_index() when min_ and max_ are the same (v0.8.7a1)
+28. Elaborate the legacy way of loading demand and zone information in tutorial (v0.8.7a1)
 
 Detailed update information can be found in [Releases](https://github.com/jdlph/Path4GMNS/releases).
 
@@ -572,7 +576,7 @@ You are encouraged to join our [Gmail group](https://groups.google.com/g/path4gm
 
 ## How to Cite
 
-Li, P. and Zhou, X. (2022, September 27). *Path4GMNS*. Retrieved from https://github.com/jdlph/Path4GMNS
+Li, P. and Zhou, X. (2022, October 2). *Path4GMNS*. Retrieved from https://github.com/jdlph/Path4GMNS
 
 ## References
 Lu, C. C., Mahmassani, H. S., Zhou, X. (2009). Equivalent gap function-based reformulation and solution algorithm for the dynamic user equilibrium problem. Transportation Research Part B: Methodological, 43, 345-364.

path4gmns/classes.py

@@ -531,8 +531,8 @@ def _get_agent(self, agent_no):
         try:
             return self.agents[agent_no]
         except IndexError:
-            print('Please provide a valid agent id, which shall be a\
-                  positive integer!')
+            agent_id = agent_no + 1
+            print('Please provide a valid agent id. agent_id: {agent_id} does NOT EXIST!')
 
     def get_agent_node_path(self, agent_id, path_only):
         """ return the sequence of node IDs along the agent path

path4gmns/utils.py

@@ -1178,10 +1178,12 @@ def output_agent_paths(ui, output_geometry=True, output_dir='.'):
         line = ['agent_id',
                 'o_zone_id',
                 'd_zone_id',
+                'origin node',
+                'destination node',
                 'path_id',
                 'agent_type',
                 'demand_period',
-                'volume',
+                'OD volume',
                 'distance',
                 'node_sequence',
                 'link_sequence',
@@ -1232,6 +1234,8 @@ def output_agent_paths(ui, output_geometry=True, output_dir='.'):
             line = [agent_id,
                     oz,
                     dz,
+                    a.get_orig_node_id(),
+                    a.get_dest_node_id(),
                     0,
                     at_str,
                     dp_str,

tests/tutorial.ipynb

@@ -79,7 +79,7 @@
    "id": "annoying-berry",
    "metadata": {},
    "source": [
-    "Navigate to the target data set directory. In this tutorial, we will use the data set where this Jupyter notebook is located for simplicity. You can check your present working directory (PWD) by the following commnad."
+    "Navigate to the target data set directory. In this tutorial, we will use the [data set](https://github.com/jdlph/Path4GMNS/tree/dev/tests) where this Jupyter notebook is located for simplicity. You can check your present working directory (PWD) by the following commnad."
    ]
   },
   {
@@ -293,7 +293,9 @@
     "\n",
     "Accessiblity defines where you can go given a time budget and a transportation mode (e.g., auto). You can find the number of accessible zones from each zone (zone_accessibility.csv) along with the free flow travel time for each OD pair (od_accessibility.csv).\n",
     "\n",
-    "The default mode is 'auto' and the default time budget is 240 minutes. We will come back to multimodal evaluation in a later section."
+    "The default mode is 'auto' and the default time budget is 240 minutes. We will come back to multimodal evaluation in a later section.\n",
+    "\n",
+    "Zone information is necessary for accessibility evaluation."
    ]
   },
   {
@@ -305,6 +307,7 @@
    "source": [
     "# no need to load demand file for accessibility evaluation\n",
     "network = pg.read_network()\n",
+    "pg.read_zones(network)\n",
     "\n",
     "pg.evaluate_accessibility(network, single_mode=True)"
    ]
@@ -323,7 +326,7 @@
     "3. max accessibility. This metric refers to the zone with the maximum number of accessible zones. \n",
     "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.\n",
     "\n",
-    "Similar to accessiblity evaluation, the default mode is 'auto' but the default time budget is 60 minutes."
+    "Similar to accessiblity evaluation, the default mode is 'auto' but the default time budget is 60 minutes. Zone information is still required here."
    ]
   },
   {
@@ -334,6 +337,7 @@
    "outputs": [],
    "source": [
     "network = pg.read_network()\n",
+    "pg.read_zones(network)\n",
     "\n",
     "pg.evaluate_equity(network, single_mode=True)"
    ]
@@ -345,7 +349,7 @@
    "source": [
     "## 4. Move Foward to Multimodal Evaluation\n",
     "\n",
-    "In order to perform multimodal evaluation, the corresponding modes (i.e., agent types) must be presented in settings.yml. It will be parsed by pyyaml (5.1 or higher) to the Python engine at run-time. A sample file looks like blow. You can start from here and modify it towards your own needs.\n",
+    "In order to perform multimodal evaluation, the corresponding modes (i.e., agent types) must be presented in settings.yml. It will be parsed by pyyaml (5.1 or higher) to the Python engine at run-time. A sample file looks like blow. You can start from here and modify it towards your own needs. **Note that** the default agent type which is **'a' as type and 'auto' as name must be present in this file**. Otherwise, you will encounter an exception with message \"No AGENT type: a\". We will relax this requirement in a later release.\n",
     "\n",
     "```yaml\n",
     "agents:\n",
@@ -464,8 +468,8 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "# no need to load demand file for accessibility evaluation\n",
     "network = pg.read_network()\n",
+    "pg.read_zones(network)\n",
     "\n",
     "pg.evaluate_accessibility(network)"
    ]
@@ -488,6 +492,7 @@
    "outputs": [],
    "source": [
     "network = pg.read_network()\n",
+    "pg.read_zones(network)\n",
     "\n",
     "pg.evaluate_equity(network)"
    ]
@@ -590,13 +595,51 @@
    "source": [
     "## 7. Legacy Way to Load Demand and Zone Info\n",
     "\n",
-    "The legacy way to load demand is via read_network() by speicifying \"load_demand=True\". We have **deprecated** it and switch to the new way demonstrated in **Section 3.2**. If you came to Path4GMNS before v0.8.6, you probably notice that \"load_demand=True\" was not required as demand will be loaded by default. This is one of the changes introduced in v0.8.6. The legacy way are still used in [demo.py](https://github.com/jdlph/Path4GMNS/blob/dev/tests/demo.py) and the code examples in [User Manual](https://github.com/jdlph/Path4GMNS/tree/dev#user-manual), which will be updated gradually over time.\n",
+    "### A Little Bit of History\n",
+    "\n",
+    "During the early development of Path4GMNS, demand.csv is presumed to be given and zone information is provided along node.csv. The latter is the current design of GMNS and is endorsed in [OSM2GMNS](https://github.com/jiawlu/OSM2GMNS). This assumption leads to the following legacy way (as the original design of Path4GMNS) to load demand and zone information while the new way demonstrated was in **Section 3.2**. \n",
+    "\n",
+    "```python\n",
+    "network = pg.read_network(load_demand=True)\n",
+    "```\n",
+    "\n",
+    "The demand file is specified in settings.yml as demand.csv. You can change it to any demand file in your PWD. This design actually allows us to load multiple demand files simultaneously corresponding to different period and agent_type. We will elaborate it in a future release.\n",
+    "\n",
+    "```yaml\n",
+    "---\n",
+    "# settings for Path4GMNS\n",
+    "agents:\n",
+    "  - type: a\n",
+    "    name: auto\n",
+    "    vot: 10\n",
+    "    flow_type: 0\n",
+    "    pce: 1\n",
+    "    free_speed: 60\n",
+    "    use_link_ffs: true\n",
+    "  - type: w\n",
+    "    name: walk\n",
+    "    vot: 10\n",
+    "    flow_type: 0\n",
+    "    pce: 1\n",
+    "    free_speed: 10\n",
+    "    use_link_ffs: false\n",
+    "\n",
+    "demand_periods:\n",
+    "  - period: AM\n",
+    "    time_period: 0700_0800\n",
+    "\n",
+    "demand_files:\n",
+    "  - file_name: demand.csv\n",
+    "    format_type: column\n",
+    "    period: AM\n",
+    "    agent_type: a\n",
     "\n",
-    "read_network(load_demand=True) will automatically check OD connectivity which **requires zone info to be specified in node.csv**. Otherwise, you will get an exception stating \"NO VALID OD VOLUME!! DOUBLE CHECK YOUR demand.csv\". \n",
+    "```\n",
+    "If you came to Path4GMNS before v0.8.6, you probably notice that \"load_demand=True\" was not required as demand will be loaded by default. This is one of the changes introduced in v0.8.6 to better promote the new way of loading demand. The legacy way are still used in [demo.py](https://github.com/jdlph/Path4GMNS/blob/dev/tests/demo.py) and the code examples in [User Manual](https://github.com/jdlph/Path4GMNS/tree/dev#user-manual), which will be updated gradually over time. You can still use this legacy way with the [existing sample data sets](https://github.com/jdlph/Path4GMNS/tree/dev/data), which do not have zone.csv but have zone information in node.csv. \n",
     "\n",
-    "Here, we still present how to use this legacy way to find paths for agents and conduct traffic assigment. You can use it with the existing [sample data sets](https://github.com/jdlph/Path4GMNS/tree/dev/data), which do not have zone.csv. \n",
+    "**Note that** read_network(load_demand=True) will **automatically check OD connectivity** which **requires zone info to be specified in node.csv**. Otherwise, you will get an exception stating \"NO VALID OD VOLUME!! DOUBLE CHECK YOUR demand.csv\". \n",
     "\n",
-    "### Find Shortest Paths for All Individual Agents"
+    "### 7.1 Find Shortest Paths for All Individual Agents"
    ]
   },
   {
@@ -606,10 +649,12 @@
    "metadata": {},
    "outputs": [],
    "source": [
+    "# zone info must be present in node.csv\n",
+    "# demand.csv must be given\n",
     "network = pg.read_network(load_demand=True)\n",
     "network.find_path_for_agents()\n",
     "\n",
-    "agent_id = 300\n",
+    "agent_id = 1\n",
     "print('\\norigin node id of agent is '\n",
     "      f'{network.get_agent_orig_node_id(agent_id)}')\n",
     "print('destination node id of agent is '\n",
@@ -619,7 +664,7 @@
     "print('shortest path (link id) of agent, '\n",
     "      f'{network.get_agent_link_path(agent_id)}')\n",
     "\n",
-    "agent_id = 1000\n",
+    "agent_id = 100\n",
     "print('\\norigin node id of agent is '\n",
     "      f'{network.get_agent_orig_node_id(agent_id)}')\n",
     "print('destination node id of agent is '\n",
@@ -640,7 +685,7 @@
    "id": "insured-electronics",
    "metadata": {},
    "source": [
-    "### Perform Path-Based UE Traffic Assignment"
+    "### 7.2 Perform Path-Based UE Traffic Assignment"
    ]
   },
   {
@@ -650,9 +695,11 @@
    "metadata": {},
    "outputs": [],
    "source": [
+    "# zone info must be present in node.csv\n",
+    "# demand.csv must be given\n",
     "network = pg.read_network(load_demand=True)\n",
     "\n",
-    "column_gen_num = 20\n",
+    "column_gen_num = 10\n",
     "column_update_num = 10\n",
     "\n",
     "# path-based UE only\n",
@@ -663,6 +710,50 @@
     "pg.output_columns(network)\n",
     "pg.output_link_performance(network)"
    ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "5d68b5d7",
+   "metadata": {},
+   "source": [
+    "### 7.3 Evaluate Multimodal Accessibility"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "4b3decc8",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# zone info must be present in node.csv\n",
+    "# no need to load demand file for accessibility evaluation\n",
+    "network = pg.read_network()\n",
+    "\n",
+    "pg.evaluate_accessibility(network)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "6226ee32",
+   "metadata": {},
+   "source": [
+    "### 7.4 Evaluate Multimodal Equity"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "87a65ad8",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# zone info must be present in node.csv\n",
+    "# no need to load demand file for accessibility evaluation\n",
+    "network = pg.read_network()\n",
+    "\n",
+    "pg.evaluate_equity(network)"
+   ]
   }
  ],
  "metadata": {