polish tutorial and README

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 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.
+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 [this tutorial](https://github.com/jdlph/Path4GMNS/tree/dev/tests/tutorial.ipynb) written in Jupyter notebook with step-by-step demonstration using the latest version, no matter you are one of the existing users or new to Path4GMNS.
 
 ## User Manual
 
@@ -560,9 +560,8 @@ DTALite uses arrays rather than STL containers to store columns. These arrays ar
 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)
+26. Fix potential issue that bin_index might not start from zero along with potential zero division issue when all zones have the same number of nodes in _synthesize_bin_index() (v0.8.7a1)
+27. 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).
 

tests/tutorial.ipynb

@@ -57,8 +57,8 @@
    "source": [
     "download_sample_data_sets() will download five sample data sets including ASU, Braess Paradox, Chicago Sketch, Lima Network, Sioux Falls, and Two Corridors. Each of them contains the following files.\n",
     "\n",
-    "1. link.csv\n",
-    "2. node.csv\n",
+    "1. node.csv\n",
+    "2. link.csv\n",
     "3. demand.csv\n",
     "4. settings.yml (for multimodal analyses)\n",
     "5. settings.csv (for DTALite)"
@@ -293,9 +293,7 @@
     "\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.\n",
-    "\n",
-    "Zone information is necessary for accessibility evaluation."
+    "The default mode is 'auto' and the default time budget is 240 minutes. We will come back to multimodal evaluation in a later section. Zone information is necessary for accessibility evaluation."
    ]
   },
   {
@@ -336,6 +334,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
+    "# no need to load demand file for equity evaluation\n",
     "network = pg.read_network()\n",
     "pg.read_zones(network)\n",
     "\n",
@@ -468,6 +467,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
+    "# no need to load demand file for accessibility evaluation\n",
     "network = pg.read_network()\n",
     "pg.read_zones(network)\n",
     "\n",
@@ -479,7 +479,7 @@
    "id": "premium-italian",
    "metadata": {},
    "source": [
-    "### 4.5 Perform Multimodal Evaluation\n",
+    "### 4.5 Perform Multimodal Equity Evaluation\n",
     "\n",
     "By removing \"single_mode=True\" from the arugment list in evaluate_equity(), multimodal evaluation will be triggered for all modes defined in settings.yml"
    ]
@@ -491,6 +491,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
+    "# no need to load demand file for equity evaluation\n",
     "network = pg.read_network()\n",
     "pg.read_zones(network)\n",
     "\n",
@@ -599,10 +600,12 @@
     "\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",
+    "\n",
     "```python\n",
     "network = pg.read_network(load_demand=True)\n",
     "```\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",
@@ -749,7 +752,7 @@
    "outputs": [],
    "source": [
     "# zone info must be present in node.csv\n",
-    "# no need to load demand file for accessibility evaluation\n",
+    "# no need to load demand file for equity evaluation\n",
     "network = pg.read_network()\n",
     "\n",
     "pg.evaluate_equity(network)"