tutorial.ipynb

{
  "cells": [
    {
      "cell_type": "markdown",
      "id": "fifteen-beast",
      "metadata": {
        "id": "fifteen-beast"
      },
      "source": [
        "# Quick Start\n",
        "\n",
        "This notebook serves as a tutorial and illustrates how to use Path4GMNS step by step."
      ]
    },
    {
      "cell_type": "markdown",
      "id": "accompanied-express",
      "metadata": {
        "id": "accompanied-express"
      },
      "source": [
        "## 1. Install Path4GMNS"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 1,
      "id": "global-waste",
      "metadata": {
        "scrolled": true,
        "id": "global-waste",
        "outputId": "0a6a96da-5e71-48f7-c642-f260c38f3e68",
        "colab": {
          "base_uri": "https://localhost:8080/"
        }
      },
      "outputs": [
        {
          "output_type": "stream",
          "name": "stdout",
          "text": [
            "Looking in indexes: https://pypi.org/simple, https://us-python.pkg.dev/colab-wheels/public/simple/\n",
            "Collecting path4gmns\n",
            "  Downloading path4gmns-0.9.0-py3-none-any.whl (1.2 MB)\n",
            "\u001b[2K     \u001b[90m━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\u001b[0m \u001b[32m1.2/1.2 MB\u001b[0m \u001b[31m33.1 MB/s\u001b[0m eta \u001b[36m0:00:00\u001b[0m\n",
            "\u001b[?25hInstalling collected packages: path4gmns\n",
            "Successfully installed path4gmns-0.9.0\n"
          ]
        }
      ],
      "source": [
        "pip install path4gmns"
      ]
    },
    {
      "cell_type": "markdown",
      "id": "third-oklahoma",
      "metadata": {
        "id": "third-oklahoma"
      },
      "source": [
        "## 2. Prepare Input Data\n",
        "\n",
        "node.csv and link.csv complying GMNS is the minimum requirement for you to get started. You can either download the sample data sets with the built-in function or prepare your own data set."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 2,
      "id": "verified-aircraft",
      "metadata": {
        "id": "verified-aircraft",
        "outputId": "84717998-79a6-47df-d0d7-bc55a3df4530",
        "colab": {
          "base_uri": "https://localhost:8080/"
        }
      },
      "outputs": [
        {
          "output_type": "stream",
          "name": "stdout",
          "text": [
            "path4gmns, version 0.9.0\n"
          ]
        }
      ],
      "source": [
        "import path4gmns as pg"
      ]
    },
    {
      "cell_type": "markdown",
      "id": "de5b5eab",
      "metadata": {
        "id": "de5b5eab"
      },
      "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. node.csv\n",
        "2. link.csv\n",
        "3. demand.csv\n",
        "4. settings.yml (for multimodal analyses)\n",
        "5. settings.csv (for DTALite)"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 3,
      "id": "helpful-spending",
      "metadata": {
        "id": "helpful-spending",
        "outputId": "0adf8ab5-c3b6-48f4-c4f0-d1958ba293b9",
        "colab": {
          "base_uri": "https://localhost:8080/"
        }
      },
      "outputs": [
        {
          "output_type": "stream",
          "name": "stdout",
          "text": [
            "downloading starts\n",
            "downloading completes\n",
            "check /content/data for downloaded data sets\n"
          ]
        }
      ],
      "source": [
        "pg.download_sample_data_sets()"
      ]
    },
    {
      "cell_type": "markdown",
      "id": "annoying-berry",
      "metadata": {
        "id": "annoying-berry"
      },
      "source": [
        "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."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 14,
      "id": "inner-vintage",
      "metadata": {
        "id": "inner-vintage",
        "outputId": "c43f010e-bb61-46c9-b7f4-ad1779045f57",
        "colab": {
          "base_uri": "https://localhost:8080/",
          "height": 36
        }
      },
      "outputs": [
        {
          "output_type": "execute_result",
          "data": {
            "text/plain": [
              "'/content/data/ASU'"
            ],
            "application/vnd.google.colaboratory.intrinsic+json": {
              "type": "string"
            }
          },
          "metadata": {},
          "execution_count": 14
        }
      ],
      "source": [
        "pwd"
      ]
    },
    {
      "cell_type": "markdown",
      "id": "1ed8250f",
      "metadata": {
        "id": "1ed8250f"
      },
      "source": [
        "If you are working in an online environment, e.g., Google Colab. You can move to one of the downloaded sample data sets, say ASU, via the following lines. "
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 15,
      "id": "284e6817",
      "metadata": {
        "id": "284e6817"
      },
      "outputs": [],
      "source": [
        "import os\n",
        "os.chdir('/content/data/Chicago_Sketch')"
      ]
    },
    {
      "cell_type": "markdown",
      "id": "understanding-discretion",
      "metadata": {
        "id": "understanding-discretion"
      },
      "source": [
        "## 3. The Basic Functionalities\n",
        "### 3.1 Get the Shortest Path between Two Nodes\n",
        "Find the (static) shortest path (based on distance) and output it in the format of a sequence of node/link IDs."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 16,
      "id": "introductory-laser",
      "metadata": {
        "id": "introductory-laser",
        "outputId": "c0bac782-187e-46ff-8703-b17e08ce87b5",
        "colab": {
          "base_uri": "https://localhost:8080/"
        }
      },
      "outputs": [
        {
          "output_type": "stream",
          "name": "stdout",
          "text": [
            "read settings.yml\n",
            "read node.csv\n",
            "the number of nodes is 933\n",
            "read link.csv\n",
            "the number of links is 2950\n",
            "\n",
            "shortest path (node id) from node 1 to node 2, distance: 3.06 mi | node path: 1;547;548;2\n",
            "\n",
            "shortest path (link id) from node 1 to node 2, distance: 3.06 mi | link path: 1;986;989\n"
          ]
        }
      ],
      "source": [
        "# create the network object by reading node.csv and link.csv\n",
        "network = pg.read_network()\n",
        "\n",
        "# node path from node 1 to node 2\n",
        "print('\\nshortest path (node id) from node 1 to node 2, '\n",
        "      +network.find_shortest_path(1, 2))\n",
        "# link path from node 1 to node 2\n",
        "print('\\nshortest path (link id) from node 1 to node 2, '\n",
        "      +network.find_shortest_path(1, 2, seq_type='link'))"
      ]
    },
    {
      "cell_type": "markdown",
      "id": "85bf294e",
      "metadata": {
        "id": "85bf294e"
      },
      "source": [
        "Path4GMNS uses **mile** and **mile per hour (mph)** as the default units for length and speed in its internal calculation and all outputs. If your link.csv features different length and speed units, please specify them in read_network(). The supported units are list as blow.\n",
        "\n",
        " **Length Units**\n",
        " * meter and m\n",
        " * kilometer and km\n",
        " * mile and mi\n",
        "\n",
        " **Speed Units**\n",
        " * kmh or kph\n",
        " * mph\n",
        " \n",
        " You would have to do manual conversion if your units are not among the above ones."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 19,
      "id": "a07d88b4",
      "metadata": {
        "id": "a07d88b4",
        "outputId": "83c750a5-2883-4313-b20e-f2373a3a00c1",
        "colab": {
          "base_uri": "https://localhost:8080/"
        }
      },
      "outputs": [
        {
          "output_type": "stream",
          "name": "stdout",
          "text": [
            "read settings.yml\n",
            "read node.csv\n",
            "the number of nodes is 933\n",
            "read link.csv\n",
            "the number of links is 2950\n",
            "\n",
            "shortest path (node id) from node 1 to node 2, distance: 3.06 mi | node path: 1;547;548;2\n",
            "\n",
            "shortest path (link id) from node 1 to node 2, distance: 3.06 mi | link path: 1;986;989\n"
          ]
        }
      ],
      "source": [
        "# the default are length_unit='mile' and speed_unit='mph'\n",
        "network = pg.read_network(length_unit='mile', speed_unit='mph')\n",
        "\n",
        "# node path from node 1 to node 2\n",
        "print('\\nshortest path (node id) from node 1 to node 2, '\n",
        "      +network.find_shortest_path(1, 2))\n",
        "# link path from node 1 to node 2\n",
        "print('\\nshortest path (link id) from node 1 to node 2, '\n",
        "      +network.find_shortest_path(1, 2, seq_type='link'))"
      ]
    },
    {
      "cell_type": "markdown",
      "id": "stuffed-roman",
      "metadata": {
        "id": "stuffed-roman"
      },
      "source": [
        "### 3.2 Find Shortest Paths for All Individual Agents\n",
        "\n",
        "Agents are disaggregated demand using the aggregated travel demand between each OD pair, which is specified in demand.csv. Individual agents will be automatically set up via find_path_for_agents() on its first call.\n",
        "\n",
        "You will need both **demand.csv** and **zone.csv** to proceed. As our sample data sets **DO NOT have zone.csv**, please go through the following step to synthesize zones and OD demand matrix in the first place. Note that it will overwrite any existing zone.csv and demand.csv if you have them."
      ]
    },
    {
      "cell_type": "markdown",
      "id": "registered-complexity",
      "metadata": {
        "id": "registered-complexity"
      },
      "source": [
        "#### 3.2.1 Synthesize Zones and OD Demand Matrix\n",
        "Path4GMNS can synthesize zones and OD demand matrix for you. If you have zone.csv and demand.csv, you can skip this step and go to *** 3.2.2 Load the synthesized zones and OD demand matrix***."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 20,
      "id": "viral-civilian",
      "metadata": {
        "scrolled": false,
        "id": "viral-civilian",
        "outputId": "c0824afc-1770-4ecb-dcdd-5604d43e1247",
        "colab": {
          "base_uri": "https://localhost:8080/"
        }
      },
      "outputs": [
        {
          "output_type": "stream",
          "name": "stdout",
          "text": [
            "read settings.yml\n",
            "read node.csv\n",
            "the number of nodes is 933\n",
            "read link.csv\n",
            "the number of links is 2950\n",
            "\n",
            "check zone.csv in /content/data/Chicago_Sketch for synthesized zones\n",
            "\n",
            "check demand.csv in /content/data/Chicago_Sketch for synthesized demand\n"
          ]
        }
      ],
      "source": [
        "network = pg.read_network()\n",
        "\n",
        "# by default, grid_dimension is 8, total_demand is 10,000,\n",
        "# time_budget is 120 min, mode is 'auto'\n",
        "pg.network_to_zones(network)\n",
        "pg.output_zones(network)\n",
        "# synthesized demand will be saved as demand.csv \n",
        "# and will overwrite any existing demand file with the same name.\n",
        "# synthesized zone will be output as zone.csv.\n",
        "pg.output_synthesized_demand(network)"
      ]
    },
    {
      "cell_type": "markdown",
      "id": "flush-electricity",
      "metadata": {
        "id": "flush-electricity"
      },
      "source": [
        "#### 3.2.2 Load the Synthesized Zones and OD Demand Matrix"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 21,
      "id": "brilliant-court",
      "metadata": {
        "id": "brilliant-court",
        "outputId": "62e1564c-7404-4b38-e261-d0959ad60c0b",
        "colab": {
          "base_uri": "https://localhost:8080/"
        }
      },
      "outputs": [
        {
          "output_type": "stream",
          "name": "stdout",
          "text": [
            "read settings.yml\n",
            "read node.csv\n",
            "the number of nodes is 933\n",
            "read link.csv\n",
            "the number of links is 2950\n",
            "read zone.csv\n",
            "the number of zones is 29\n",
            "read demand.csv\n",
            "the number of agents is 10425\n"
          ]
        }
      ],
      "source": [
        "network = pg.read_network()\n",
        "\n",
        "# it reads zone.csv by default\n",
        "pg.read_zones(network)\n",
        "# it reads demand.csv by default\n",
        "pg.load_demand(network)"
      ]
    },
    {
      "cell_type": "markdown",
      "id": "systematic-criminal",
      "metadata": {
        "id": "systematic-criminal"
      },
      "source": [
        "#### 3.2.3 Find Shortest Paths"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 22,
      "id": "fifth-geometry",
      "metadata": {
        "id": "fifth-geometry",
        "outputId": "e1293e0c-736f-44bb-8c45-bc5476f0f4f1",
        "colab": {
          "base_uri": "https://localhost:8080/"
        }
      },
      "outputs": [
        {
          "output_type": "stream",
          "name": "stdout",
          "text": [
            "setting up individual agents\n",
            "the number of agents is 10425\n",
            "\n",
            "check agent_paths.csv in /content/data/Chicago_Sketch for unique agent paths\n"
          ]
        }
      ],
      "source": [
        "# individual agents will be automatically set up \n",
        "# according to demand from loaded demand.csv.\n",
        "# different with find_shortest_path(), this function does not return anything.\n",
        "network.find_path_for_agents( )\n",
        "\n",
        "# output unique agent paths to agent_paths.csv\n",
        "# if you do not want to include geometry info in the output file,\n",
        "# use pg.output_agent_paths(network, False)\n",
        "pg.output_agent_paths(network)"
      ]
    },
    {
      "cell_type": "markdown",
      "id": "mysterious-diamond",
      "metadata": {
        "id": "mysterious-diamond"
      },
      "source": [
        "### 3.3 Perform Path-Based UE Traffic Assignment\n",
        "\n",
        "Similar to Finding Shortest Paths for All Individual Agents, OD demand matrix is also need to perform this functionality. You will need to load the demand via pg.load_demand(network). Then you can conduct traffic assignment via the following lines."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 23,
      "id": "advance-bridges",
      "metadata": {
        "id": "advance-bridges",
        "outputId": "94e6569e-7256-40e9-ee58-5d84dae3fa2b",
        "colab": {
          "base_uri": "https://localhost:8080/"
        }
      },
      "outputs": [
        {
          "output_type": "stream",
          "name": "stdout",
          "text": [
            "read settings.yml\n",
            "read node.csv\n",
            "the number of nodes is 933\n",
            "read link.csv\n",
            "the number of links is 2950\n",
            "read zone.csv\n",
            "the number of zones is 29\n",
            "read demand.csv\n",
            "the number of agents is 10425\n",
            "current iteration number in column generation: 0\n",
            "current iteration number in column generation: 1\n",
            "current iteration number in column generation: 2\n",
            "current iteration number in column generation: 3\n",
            "current iteration number in column generation: 4\n",
            "current iteration number in column generation: 5\n",
            "current iteration number in column generation: 6\n",
            "current iteration number in column generation: 7\n",
            "current iteration number in column generation: 8\n",
            "current iteration number in column generation: 9\n",
            "\n",
            "processing time of generating columns: 0.40 s\n",
            "current iteration number in column update: 0\n",
            "total gap: 0.18\n",
            "relative gap: 0.000%\n",
            "current iteration number in column update: 1\n",
            "total gap: 0.18\n",
            "relative gap: 0.000%\n",
            "current iteration number in column update: 2\n",
            "total gap: 0.18\n",
            "relative gap: 0.000%\n",
            "current iteration number in column update: 3\n",
            "total gap: 0.18\n",
            "relative gap: 0.000%\n",
            "current iteration number in column update: 4\n",
            "total gap: 0.18\n",
            "relative gap: 0.000%\n",
            "current iteration number in column update: 5\n",
            "total gap: 0.18\n",
            "relative gap: 0.000%\n",
            "current iteration number in column update: 6\n",
            "total gap: 0.18\n",
            "relative gap: 0.000%\n",
            "current iteration number in column update: 7\n",
            "total gap: 0.18\n",
            "relative gap: 0.000%\n",
            "current iteration number in column update: 8\n",
            "total gap: 0.18\n",
            "relative gap: 0.000%\n",
            "current iteration number in column update: 9\n",
            "total gap: 0.18\n",
            "relative gap: 0.000%\n",
            "\n",
            "check agent.csv in /content/data/Chicago_Sketch for path finding results\n",
            "\n",
            "check link_performance.csv in /content/data/Chicago_Sketch for link performance\n"
          ]
        }
      ],
      "source": [
        "network = pg.read_network()\n",
        "pg.read_zones(network)\n",
        "pg.load_demand(network)\n",
        "\n",
        "# specify the parameters for traffic assignment\n",
        "column_gen_num = 10\n",
        "column_update_num = 10\n",
        "\n",
        "# path-based UE only\n",
        "pg.perform_column_generation(column_gen_num, column_update_num, network)\n",
        "\n",
        "# if you do not want to include geometry info in the output file,\n",
        "# use pg.output_columns(network, False)\n",
        "# output column information to agent.csv\n",
        "pg.output_columns(network)\n",
        "# output link performance to link_performance.csv\n",
        "pg.output_link_performance(network)"
      ]
    },
    {
      "cell_type": "markdown",
      "id": "identified-timer",
      "metadata": {
        "id": "identified-timer"
      },
      "source": [
        "### 3.4 Evaluate Accessibility\n",
        "\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 **in minutes** (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. Zone information is necessary for accessibility evaluation."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 12,
      "id": "supreme-module",
      "metadata": {
        "id": "supreme-module",
        "outputId": "c23b81d1-5f53-47c6-8e20-f1748458b6ba",
        "colab": {
          "base_uri": "https://localhost:8080/"
        }
      },
      "outputs": [
        {
          "output_type": "stream",
          "name": "stdout",
          "text": [
            "read settings.yml\n",
            "read node.csv\n",
            "the number of nodes is 998\n",
            "read link.csv\n",
            "the number of links is 1836\n",
            "read zone.csv\n",
            "the number of zones is 24\n",
            "\n",
            "check zone_accessibility.csv in /content/data/ASU for zone accessibility\n",
            "check od_accessibility.csv in /content/data/ASU for OD accessibility\n",
            "\n"
          ]
        }
      ],
      "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)"
      ]
    },
    {
      "cell_type": "markdown",
      "id": "ordinary-chance",
      "metadata": {
        "id": "ordinary-chance"
      },
      "source": [
        "### 3.5 Evaluate Equity\n",
        "\n",
        "Transportation equity is accessibility with respect to different demographics. Path4GMNS rovides the following simple info and statistics on equity given a time budget and a segmentation of zones.\n",
        "\n",
        "1. accessible zones.\n",
        "2. min accessibility. This metric refers to the zone with the minimum number of accessible zones. \n",
        "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. Zone information is still required here."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 24,
      "id": "dressed-enemy",
      "metadata": {
        "id": "dressed-enemy",
        "outputId": "c7a9ee22-04d0-4124-8a05-45254535c0eb",
        "colab": {
          "base_uri": "https://localhost:8080/"
        }
      },
      "outputs": [
        {
          "output_type": "stream",
          "name": "stdout",
          "text": [
            "read settings.yml\n",
            "read node.csv\n",
            "the number of nodes is 933\n",
            "read link.csv\n",
            "the number of links is 2950\n",
            "read zone.csv\n",
            "the number of zones is 29\n",
            "\n",
            "check equity_60 min.csv in /content/data/Chicago_Sketch for equity evaluation\n"
          ]
        }
      ],
      "source": [
        "# no need to load demand file for equity evaluation\n",
        "network = pg.read_network()\n",
        "pg.read_zones(network)\n",
        "\n",
        "pg.evaluate_equity(network, single_mode=True)"
      ]
    },
    {
      "cell_type": "markdown",
      "id": "accepting-indian",
      "metadata": {
        "id": "accepting-indian"
      },
      "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. \n",
        "\n",
        "pyyaml must be installed before running any multimodal evaluation."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 25,
      "id": "31fde7f0",
      "metadata": {
        "id": "31fde7f0",
        "outputId": "bb3e3201-c238-4305-b6e3-b420e6486801",
        "colab": {
          "base_uri": "https://localhost:8080/"
        }
      },
      "outputs": [
        {
          "output_type": "stream",
          "name": "stdout",
          "text": [
            "Looking in indexes: https://pypi.org/simple, https://us-python.pkg.dev/colab-wheels/public/simple/\n",
            "Requirement already satisfied: pyyaml in /usr/local/lib/python3.8/dist-packages (6.0)\n"
          ]
        }
      ],
      "source": [
        "pip install pyyaml"
      ]
    },
    {
      "cell_type": "markdown",
      "id": "abbb261f",
      "metadata": {
        "id": "abbb261f"
      },
      "source": [
        "### 4.1 Sample setting.yml\n",
        "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",
        "  - 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",
        "\n",
        "You can download a sample settings.yml (to your PWD) if you do not have one by the following command."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 26,
      "id": "disabled-mobility",
      "metadata": {
        "id": "disabled-mobility",
        "outputId": "7d694289-6f52-401d-ef0c-2064f14088c0",
        "colab": {
          "base_uri": "https://localhost:8080/"
        }
      },
      "outputs": [
        {
          "output_type": "stream",
          "name": "stdout",
          "text": [
            "downloading completes\n",
            "check /content/data/Chicago_Sketch for downloaded settings.yml\n"
          ]
        }
      ],
      "source": [
        "pg.download_sample_setting_file()"
      ]
    },
    {
      "cell_type": "markdown",
      "id": "great-catholic",
      "metadata": {
        "id": "great-catholic"
      },
      "source": [
        "### 4.2 Get the Shortest Path between Two Nodes under a Specific Mode\n",
        "In 3.1, we used this functionlity implicitly for the default mode, which is 'a' or equivalently 'auto'. Now with 'walk' defined in settings.yml, we are able to find the shortest path under mode 'w' or 'walk'."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 27,
      "id": "continuous-baker",
      "metadata": {
        "id": "continuous-baker",
        "outputId": "dbf705dc-3b81-4a80-ae53-17ddaadee264",
        "colab": {
          "base_uri": "https://localhost:8080/"
        }
      },
      "outputs": [
        {
          "output_type": "stream",
          "name": "stdout",
          "text": [
            "read settings.yml\n",
            "read node.csv\n",
            "the number of nodes is 933\n",
            "read link.csv\n",
            "the number of links is 2950\n",
            "\n",
            "shortest path (node id) from node 1 to node 2, distance: 3.06 mi | node path: 1;547;548;2\n",
            "\n",
            "shortest path (link id) from node 1 to node 2, distance: 3.06 mi | link path: 1;986;989\n"
          ]
        }
      ],
      "source": [
        "network = pg.read_network()\n",
        "\n",
        "print('\\nshortest path (node id) from node 1 to node 2, '\n",
        "      +network.find_shortest_path(1, 2, mode='w'))\n",
        "print('\\nshortest path (link id) from node 1 to node 2, '\n",
        "      +network.find_shortest_path(1, 2, mode='w', seq_type='link'))"
      ]
    },
    {
      "cell_type": "markdown",
      "id": "balanced-cattle",
      "metadata": {
        "id": "balanced-cattle"
      },
      "source": [
        "For this test data set, 3.1 and 4.1 have the same results as each link is open to all modes, i.e., their \"allowed_uses\" are \"all\". \n",
        "\n",
        "### 4.3 Find Shortest Paths for All Individual Agents under a Specific Mode\n",
        "\n",
        "The following code snippet illustrates how to find the shortest paths for all individal angents under mode 'w' or 'walk'."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 28,
      "id": "velvet-creator",
      "metadata": {
        "id": "velvet-creator",
        "outputId": "612292df-b519-411e-c2b3-06d35d4e96df",
        "colab": {
          "base_uri": "https://localhost:8080/"
        }
      },
      "outputs": [
        {
          "output_type": "stream",
          "name": "stdout",
          "text": [
            "read settings.yml\n",
            "read node.csv\n",
            "the number of nodes is 933\n",
            "read link.csv\n",
            "the number of links is 2950\n",
            "read zone.csv\n",
            "the number of zones is 29\n",
            "read demand.csv\n",
            "the number of agents is 10425\n",
            "setting up individual agents\n",
            "the number of agents is 10425\n",
            "\n",
            "check agent_paths.csv in /content/data/Chicago_Sketch for unique agent paths\n"
          ]
        }
      ],
      "source": [
        "network = pg.read_network()\n",
        "\n",
        "pg.read_zones(network)\n",
        "pg.load_demand(network)\n",
        "\n",
        "# if you have demand.csv with zone info, you can replace the above three lines by\n",
        "# network = pg.read_network(load_demand=True)\n",
        "\n",
        "# or equivalently network.find_path_for_agents('walk')\n",
        "network.find_path_for_agents('w')\n",
        "\n",
        "# retrieving the origin, the destination, and the shortest path of a given agent\n",
        "# is exactly the same as before as well as outputting all unique agent paths\n",
        "pg.output_agent_paths(network)"
      ]
    },
    {
      "cell_type": "markdown",
      "id": "further-sampling",
      "metadata": {
        "id": "further-sampling"
      },
      "source": [
        "### 4.4 Perform Multimodal Accessibility Evaluation\n",
        "\n",
        "It is very similar to what we have done in 3.4 for a single-mode analysis."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 29,
      "id": "anticipated-stage",
      "metadata": {
        "id": "anticipated-stage",
        "outputId": "f75f5d4a-b6b0-4521-fe2f-eca53ecca615",
        "colab": {
          "base_uri": "https://localhost:8080/"
        }
      },
      "outputs": [
        {
          "output_type": "stream",
          "name": "stdout",
          "text": [
            "read settings.yml\n",
            "read node.csv\n",
            "the number of nodes is 933\n",
            "read link.csv\n",
            "the number of links is 2950\n",
            "read zone.csv\n",
            "the number of zones is 29\n",
            "\n",
            "check zone_accessibility.csv in /content/data/Chicago_Sketch for zone accessibility\n"
          ]
        }
      ],
      "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)"
      ]
    },
    {
      "cell_type": "markdown",
      "id": "premium-italian",
      "metadata": {
        "id": "premium-italian"
      },
      "source": [
        "### 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"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "id": "appointed-monte",
      "metadata": {
        "id": "appointed-monte"
      },
      "outputs": [],
      "source": [
        "# no need to load demand file for equity evaluation\n",
        "network = pg.read_network()\n",
        "pg.read_zones(network)\n",
        "\n",
        "pg.evaluate_equity(network)"
      ]
    },
    {
      "cell_type": "markdown",
      "id": "f4dbe11a",
      "metadata": {
        "id": "f4dbe11a"
      },
      "source": [
        "### 4.6 Conduct Traffic Simulation\n",
        "\n",
        "Traffic simulation requires routing decision for each agent, which could come from the shortest path or the UE traffic assignment. v0.9.0 only supports the first one."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "id": "79aeb0a0",
      "metadata": {
        "id": "79aeb0a0"
      },
      "outputs": [],
      "source": [
        "network = pg.read_network()\n",
        "\n",
        "pg.read_zones(network)\n",
        "pg.load_demand(network)\n",
        "\n",
        "network.find_path_for_agents()\n",
        "pg.perform_simple_simulation(network)\n",
        "print('complete simple simulation.\\n')\n",
        "\n",
        "print('writing agent trajectories')\n",
        "pg.output_agent_trajectory(network)"
      ]
    },
    {
      "cell_type": "markdown",
      "id": "signed-marsh",
      "metadata": {
        "id": "signed-marsh"
      },
      "source": [
        "## 5. Advanced Features\n",
        "\n",
        "### 5.1 In Case of Special Events\n",
        "\n",
        "A special event often comes with capacity reduction over affected links. You can introduce one special event for each demand period in settings.yml as below. \n",
        "\n",
        "```yaml\n",
        "demand_periods:\n",
        "  - period: AM\n",
        "    time_period: 0700_0800\n",
        "    special_event:\n",
        "      name: work_zone\n",
        "      enable: true\n",
        "      # with respect to iterations in column generation\n",
        "      beg_iteration: 1\n",
        "      end_iteration: 20\n",
        "      affected_links:\n",
        "        - link_id: 1\n",
        "          reduction_ratio: 0.5\n",
        "        - link_id: 2\n",
        "          reduction_ratio: 0.4\n",
        "        - link_id: 3\n",
        "          reduction_ratio: 0.6\n",
        "        - link_id: 4\n",
        "          reduction_ratio: 0\n",
        "```\n",
        "\n",
        "If the original capacity of an affected link i is C, its capacity then will be r * C with a reduction ratio of r when a special event is present. For an affected link, setting its reduction_ratio to 0 is equivalent to removing it from the entire demand period. You can turn on or off a special event by setting enable to true or false.\n",
        "\n",
        "Then you can conduct traffic assignment (as shown in 3.3) and see the impact from a special event.\n",
        "\n",
        "### 5.2 Accessibility Considering Time-Dependent Link Travel Time\n",
        "\n",
        "In 3.4 and 4.4, accessiblity is evluated using the link free flow travel time, which is determined by link length and link free-flow speed under a specific mode. \n",
        "\n",
        "Link travel time varies over time so does accessibility. When the time-dependent accessibility is of interested, time-dependent link travel time (i.e., VDF_fftt from a given demand period in link.csv) will come into play by overwriting the (static) link free-flow speed (from either link.csv or settings.yml. both are denoted as \"free_speed\")."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "id": "sought-commercial",
      "metadata": {
        "id": "sought-commercial"
      },
      "outputs": [],
      "source": [
        "network = pg.read_network()\n",
        "\n",
        "# time-dependent accessibility under the default mode auto (i.e., 'a')\n",
        "# for demand period 0 (i.e., VDF_fftt1 in link.csv will be used in the evaluation)\n",
        "pg.evaluate_accessibility(network, single_mode=True, time_dependent=True)\n",
        "\n",
        "# if you would like to evaluate accessibility under a target mode, say walk, then\n",
        "pg.evaluate_accessibility(network, single_mode=True, mode='w', time_dependent=True)"
      ]
    },
    {
      "cell_type": "markdown",
      "id": "clear-celtic",
      "metadata": {
        "id": "clear-celtic"
      },
      "source": [
        "## 6. DTALite\n",
        "\n",
        "Path4GMNS also serves as an API to the C++-based DTALite to conduct various multimodal traffic assignments including,\n",
        "\n",
        "    0: Link-based UE,\n",
        "    1: Path-based UE,\n",
        "    2: UE + Dynamic Traffic Assignment (DTA),\n",
        "    3: OD Matrix Estimation (ODME).\n",
        "\n",
        "Here we only demonstrate how to perform path-based UE (i.e., mode 1) using DTALite from Path4GMNS. You would need [settings.csv](https://github.com/jdlph/Path4GMNS/blob/dev/tests/settings.csv) to get started.\n",
        "\n",
        "In order to use DTALite embedded in Path4GMNS, run-time support OpenMP must be installed in the first space. See [Installation](https://path4gmns.readthedocs.io/en/latest/installation.html) for details."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 30,
      "id": "anonymous-services",
      "metadata": {
        "id": "anonymous-services",
        "outputId": "68f64fa2-d175-40d7-eaf9-3b28cbfbffa8",
        "colab": {
          "base_uri": "https://localhost:8080/"
        }
      },
      "outputs": [
        {
          "output_type": "stream",
          "name": "stdout",
          "text": [
            "\n",
            "DTALite run starts\n",
            "\n",
            "DTALite run completes\n",
            "\n",
            "check link_performance.csv in /content/data/Chicago_Sketch for link performance\n",
            "check agent.csv in /content/data/Chicago_Sketch for unique agent paths\n",
            "\n"
          ]
        }
      ],
      "source": [
        "mode = 1\n",
        "column_gen_num = 10\n",
        "column_update_num = 10\n",
        "\n",
        "pg.perform_network_assignment_DTALite(mode, column_gen_num, column_update_num)"
      ]
    },
    {
      "cell_type": "markdown",
      "id": "intelligent-finder",
      "metadata": {
        "id": "intelligent-finder"
      },
      "source": [
        "## 7. Legacy Way to Load Demand and Zone Info\n",
        "\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",
        "\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",
        "---\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",
        "```\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",
        "**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",
        "### 7.1 Find Shortest Paths for All Individual Agents"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "id": "interpreted-purple",
      "metadata": {
        "id": "interpreted-purple"
      },
      "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 = 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",
        "      f'{network.get_agent_dest_node_id(agent_id)}')\n",
        "print('shortest path (node id) of agent, '\n",
        "      f'{network.get_agent_node_path(agent_id)}')\n",
        "print('shortest path (link id) of agent, '\n",
        "      f'{network.get_agent_link_path(agent_id)}')\n",
        "\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",
        "      f'{network.get_agent_dest_node_id(agent_id)}')\n",
        "print('shortest path (node id) of agent, '\n",
        "      f'{network.get_agent_node_path(agent_id)}')\n",
        "print('shortest path (link id) of agent, '\n",
        "      f'{network.get_agent_link_path(agent_id)}')\n",
        "\n",
        "# output unique agent paths to a csv file\n",
        "# if you do not want to include geometry info in the output file,\n",
        "# use pg.output_agent_paths(network, False)\n",
        "pg.output_agent_paths(network)"
      ]
    },
    {
      "cell_type": "markdown",
      "id": "insured-electronics",
      "metadata": {
        "id": "insured-electronics"
      },
      "source": [
        "### 7.2 Perform Path-Based UE Traffic Assignment"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "id": "natural-jesus",
      "metadata": {
        "id": "natural-jesus"
      },
      "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 = 10\n",
        "column_update_num = 10\n",
        "\n",
        "# path-based UE only\n",
        "pg.perform_column_generation(column_gen_num, column_update_num, network)\n",
        "\n",
        "# if you do not want to include geometry info in the output file,\n",
        "# use pg.output_columns(network, False)\n",
        "pg.output_columns(network)\n",
        "pg.output_link_performance(network)"
      ]
    },
    {
      "cell_type": "markdown",
      "id": "5d68b5d7",
      "metadata": {
        "id": "5d68b5d7"
      },
      "source": [
        "### 7.3 Evaluate Multimodal Accessibility"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "id": "4b3decc8",
      "metadata": {
        "id": "4b3decc8"
      },
      "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": {
        "id": "6226ee32"
      },
      "source": [
        "### 7.4 Evaluate Multimodal Equity"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "id": "87a65ad8",
      "metadata": {
        "id": "87a65ad8"
      },
      "outputs": [],
      "source": [
        "# zone info must be present in node.csv\n",
        "# no need to load demand file for equity evaluation\n",
        "network = pg.read_network()\n",
        "\n",
        "pg.evaluate_equity(network)"
      ]
    },
    {
      "cell_type": "markdown",
      "id": "f4299b1a",
      "metadata": {
        "id": "f4299b1a"
      },
      "source": [
        "### 7.4 Conduct Traffic Simulation"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 31,
      "id": "f56e61c6",
      "metadata": {
        "id": "f56e61c6",
        "outputId": "f8e4b978-a375-4529-ad1a-875bb9783b2b",
        "colab": {
          "base_uri": "https://localhost:8080/"
        }
      },
      "outputs": [
        {
          "output_type": "stream",
          "name": "stdout",
          "text": [
            "read settings.yml\n",
            "read node.csv\n",
            "the number of nodes is 933\n",
            "the number of zones is 387\n",
            "read link.csv\n",
            "the number of links is 2950\n",
            "read demand.csv\n",
            "the number of agents is 10425\n",
            "setting up individual agents\n",
            "the number of agents is 10425\n",
            "simu time = 0.0 min, CA = 0, CD = 0\n",
            "simu time = 1.0 min, CA = 192, CD = 0\n",
            "simu time = 2.0 min, CA = 346, CD = 0\n",
            "simu time = 3.0 min, CA = 515, CD = 0\n",
            "simu time = 4.0 min, CA = 708, CD = 8\n",
            "simu time = 5.0 min, CA = 883, CD = 38\n",
            "simu time = 6.0 min, CA = 1043, CD = 77\n",
            "simu time = 7.0 min, CA = 1233, CD = 132\n",
            "simu time = 8.0 min, CA = 1418, CD = 199\n",
            "simu time = 9.0 min, CA = 1564, CD = 288\n",
            "simu time = 10.0 min, CA = 1735, CD = 387\n",
            "simu time = 11.0 min, CA = 1894, CD = 495\n",
            "simu time = 12.0 min, CA = 2052, CD = 646\n",
            "simu time = 13.0 min, CA = 2228, CD = 781\n",
            "simu time = 14.0 min, CA = 2388, CD = 927\n",
            "simu time = 15.0 min, CA = 2562, CD = 1093\n",
            "simu time = 16.0 min, CA = 2734, CD = 1243\n",
            "simu time = 17.0 min, CA = 2908, CD = 1411\n",
            "simu time = 18.0 min, CA = 3095, CD = 1586\n",
            "simu time = 19.0 min, CA = 3266, CD = 1746\n",
            "simu time = 20.0 min, CA = 3450, CD = 1917\n",
            "simu time = 21.0 min, CA = 3625, CD = 2103\n",
            "simu time = 22.0 min, CA = 3799, CD = 2269\n",
            "simu time = 23.0 min, CA = 3980, CD = 2456\n",
            "simu time = 24.0 min, CA = 4141, CD = 2634\n",
            "simu time = 25.0 min, CA = 4324, CD = 2787\n",
            "simu time = 26.0 min, CA = 4494, CD = 2971\n",
            "simu time = 27.0 min, CA = 4661, CD = 3135\n",
            "simu time = 28.0 min, CA = 4848, CD = 3294\n",
            "simu time = 29.0 min, CA = 5026, CD = 3460\n",
            "simu time = 30.0 min, CA = 5183, CD = 3645\n",
            "simu time = 31.0 min, CA = 5362, CD = 3817\n",
            "simu time = 32.0 min, CA = 5553, CD = 3996\n",
            "simu time = 33.0 min, CA = 5720, CD = 4162\n",
            "simu time = 34.0 min, CA = 5892, CD = 4344\n",
            "simu time = 35.0 min, CA = 6055, CD = 4518\n",
            "simu time = 36.0 min, CA = 6241, CD = 4697\n",
            "simu time = 37.0 min, CA = 6426, CD = 4870\n",
            "simu time = 38.0 min, CA = 6605, CD = 5029\n",
            "simu time = 39.0 min, CA = 6769, CD = 5182\n",
            "simu time = 40.0 min, CA = 6953, CD = 5385\n",
            "simu time = 41.0 min, CA = 7147, CD = 5568\n",
            "simu time = 42.0 min, CA = 7325, CD = 5731\n",
            "simu time = 43.0 min, CA = 7513, CD = 5908\n",
            "simu time = 44.0 min, CA = 7704, CD = 6083\n",
            "simu time = 45.0 min, CA = 7870, CD = 6279\n",
            "simu time = 46.0 min, CA = 8040, CD = 6474\n",
            "simu time = 47.0 min, CA = 8199, CD = 6665\n",
            "simu time = 48.0 min, CA = 8371, CD = 6841\n",
            "simu time = 49.0 min, CA = 8532, CD = 7026\n",
            "simu time = 50.0 min, CA = 8724, CD = 7209\n",
            "simu time = 51.0 min, CA = 8901, CD = 7363\n",
            "simu time = 52.0 min, CA = 9055, CD = 7519\n",
            "simu time = 53.0 min, CA = 9239, CD = 7721\n",
            "simu time = 54.0 min, CA = 9420, CD = 7891\n",
            "simu time = 55.0 min, CA = 9569, CD = 8061\n",
            "simu time = 56.0 min, CA = 9743, CD = 8238\n",
            "simu time = 57.0 min, CA = 9899, CD = 8401\n",
            "simu time = 58.0 min, CA = 10074, CD = 8567\n",
            "simu time = 59.0 min, CA = 10248, CD = 8757\n",
            "complete simple simulation.\n",
            "\n",
            "writing agent trajectories\n",
            "\n",
            "check trajectory.csv in /content/data/Chicago_Sketch for trajectories\n"
          ]
        }
      ],
      "source": [
        "network = pg.read_network(load_demand=True)\n",
        "\n",
        "network.find_path_for_agents()\n",
        "pg.perform_simple_simulation(network)\n",
        "print('complete simple simulation.\\n')\n",
        "\n",
        "print('writing agent trajectories')\n",
        "pg.output_agent_trajectory(network)"
      ]
    }
  ],
  "metadata": {
    "kernelspec": {
      "display_name": "Python 3",
      "language": "python",
      "name": "python3"
    },
    "language_info": {
      "codemirror_mode": {
        "name": "ipython",
        "version": 3
      },
      "file_extension": ".py",
      "mimetype": "text/x-python",
      "name": "python",
      "nbconvert_exporter": "python",
      "pygments_lexer": "ipython3",
      "version": "3.7.6 (default, Jan  8 2020, 13:42:34) \n[Clang 4.0.1 (tags/RELEASE_401/final)]"
    },
    "vscode": {
      "interpreter": {
        "hash": "40d3a090f54c6569ab1632332b64b2c03c39dcf918b08424e98f38b5ae0af88f"
      }
    },
    "colab": {
      "provenance": []
    }
  },
  "nbformat": 4,
  "nbformat_minor": 5
}