{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "f1c4253e",
   "metadata": {},
   "source": [
    "# Usage"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "439ee015",
   "metadata": {
    "nbsphinx": "hidden",
    "tags": [
     "remove-cell"
    ]
   },
   "outputs": [],
   "source": [
    "# this cell is hidden from output\n",
    "# it’s used to \n",
    "# - set sys.path to point to the local repo\n",
    "# - make ipython show all outputs of each cell\n",
    "\n",
    "# - set sys.path to point to the local repo\n",
    "import pathlib\n",
    "import sys\n",
    "sys.path.insert(0, str(pathlib.Path().absolute().parent / \"src\"))\n",
    "\n",
    "# - make ipython show all outputs of each cell\n",
    "get_ipython().ast_node_interactivity = \"all\""
   ]
  },
  {
   "cell_type": "markdown",
   "id": "cd224d77",
   "metadata": {},
   "source": [
    "## Python\n",
    "\n",
    "R5py exposes some of R5’s functionality via its [Python API](reference.html), in a syntax similar to r5r’s. At the time of this writing, only the computation of travel time matrices has been fully implemented. \n",
    "\n",
    "Below, you find a minimal example of computing a travel time matrix:"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "53f7a7cc",
   "metadata": {
    "tags": []
   },
   "source": [
    "### Load transport network\n",
    "\n",
    "Virtually all operations of r5py require a transport network. As input files to construct a transport network topology, r5py needs the following data sets:\n",
    "\n",
    "- The street network in the form of an OpenStreetMap extract covering the study area, prepared according to the instructions at https://docs.conveyal.com/prepare-inputs#preparing-the-osm-data, and possibly annotated with LADOT tags (see https://github.com/RSGInc/ladot_analysis_dataprep).\n",
    "- Public transport schedules in GTFS format (optional, r5py can combine multiple GTFS files)\n",
    "\n",
    "In this example, we use data from Helsinki metropolitan area, which you can find in the source code repository of r5py in `docs/data/`. The street network is a cropped and filtered extract of OpenStreetMap (© OpenStreetMap contributors, [ODbL license](https://www.openstreetmap.org/copyright)), the GTFS transport schedule is a cropped and minimised copy of Helsingin seudun liikenne’s (HSL) open data set [Creative Commons BY 4.0](https://www.hsl.fi/hsl/avoin-data#aineistojen-kayttoehdot).\n",
    "\n",
    "To import the street and public transport networks, instantiate an `r5py.TransportNetwork` with the file paths to the OSM extract and the GTFS files:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "846bfb43",
   "metadata": {},
   "outputs": [],
   "source": [
    "from r5py import TransportNetwork\n",
    "\n",
    "transport_network = TransportNetwork(\n",
    "    \"data/kantakaupunki.osm.pbf\",\n",
    "    [\n",
    "        \"data/GTFS.zip\"\n",
    "    ]\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d7b1101f-1f01-462a-9ee2-aa3522d0bdd5",
   "metadata": {},
   "source": [
    "### Compute a travel time matrix\n",
    "\n",
    "A travel time matrix is a data set detailing the travel costs (e.g., time) from each point to each point in a set of origins and destinations in a study area. \n",
    "\n",
    "For the sake of this exercise, we have prepared a grid of points covering parts of Helsinki. The point dataset has been obtained from [Helsinki Region Environmental Services](https://www.hsy.fi/en/environmental-information/open-data/avoin-data---sivut/population-grid-of-helsinki-metropolitan-area/) (HSY) licensed under a Creative Commons By Attribution 4.0. The point data also contains information about residents of each 250 meter cell."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "e7ab7dde-aebb-483f-974b-d0382a5ab7c1",
   "metadata": {},
   "outputs": [],
   "source": [
    "import geopandas\n",
    "\n",
    "grid_points = geopandas.read_file(\"data/population_points_2020.gpkg\")\n",
    "\n",
    "grid_points.head()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "0cc4b64d",
   "metadata": {},
   "source": [
    "\n",
    "We can now visualise the number of people living in each cell (the cells are represented by their centre point):\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "66d5a28e-63cb-4bf0-9e2e-f064f5d216d5",
   "metadata": {},
   "outputs": [],
   "source": [
    "grid_points.explore(\"population\", cmap=\"Reds\", marker_kwds={\"radius\": 12})"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3f1cdb94-b40f-4b83-8be2-a813b2833fef",
   "metadata": {},
   "source": [
    "Now, to compute a travel time matrix between all `grid_points`, we first instantiate an `r5py.TravelTimeMatrixComputer` with the transport network we created earlier, and a list of origins (since we don’t specify a separate set of destinations, r5py will use the same points as destinations and produce a full set of origins and destinations). The constructor also accepts all parameters of [RegionalTask](reference.html#r5py.RegionalTask), such as transport modes, or walking speed. \n",
    "\n",
    "Calling `compute_travel_times()` on the instance will return a `pandas.DataFrame` with travel times between all points."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "b5dabcc1-95a4-4c9f-86ab-533d2c752716",
   "metadata": {},
   "outputs": [],
   "source": [
    "import datetime\n",
    "\n",
    "from r5py import TravelTimeMatrixComputer, TransitMode, LegMode\n",
    "\n",
    "\n",
    "travel_time_matrix_computer = TravelTimeMatrixComputer(\n",
    "    transport_network,\n",
    "    origins=grid_points,\n",
    "    departure=datetime.datetime(2022,2,22,8,30),\n",
    "    transport_modes=[TransitMode.TRANSIT, LegMode.WALK],\n",
    "    #percentiles=[1,25,50,75,99],\n",
    "    #breakdown=True\n",
    ")\n",
    "travel_time_matrix = travel_time_matrix_computer.compute_travel_times()\n",
    "travel_time_matrix"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4a837f5b-1269-47eb-aa53-5329fb800b90",
   "metadata": {},
   "source": [
    "The values in the `travel_time` column are travel times between the points identified by `from_id` and `to_id`, in minutes. \n",
    "\n",
    "The median travel time to or from a certain point gives a good estimate of the overall accessibility to or from it, in relation to other points:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "d026f1e6-05ca-4c9d-ba5b-f45d7ac69d85",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "travel_time_matrix.groupby(\"from_id\")[\"travel_time\"].median()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "0efc3964-68a5-401d-8e4a-323fc44b5f3f",
   "metadata": {},
   "outputs": [],
   "source": [
    "travel_time_matrix.groupby(\"from_id\")[\"travel_time\"].median().median()"
   ]
  }
 ],
 "metadata": {
  "execution": {
   "timeout": 360
  },
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "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.10.4"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}