notebooks/12-node-elevations-edge-grades.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Node elevations and edge grades\n",
    "\n",
    "Author: [Geoff Boeing](https://geoffboeing.com/)\n",
    "\n",
    "  - [Documentation](https://osmnx.readthedocs.io/)\n",
    "  - [Journal article and citation info](https://geoffboeing.com/publications/osmnx-paper/)\n",
    "  - [Code repository](https://github.com/gboeing/osmnx)\n",
    "  - [Examples gallery](https://github.com/gboeing/osmnx-examples)\n",
    "\n",
    "OSMnx allows you to automatically add elevation attributes to your graph's nodes with the `elevation` module, using either local raster files or the Google Maps Elevation API as the elevation data source. If you use the Google API, you will need an API key. Once your nodes have elevation values, OSMnx can automatically calculate your edges' grades (inclines)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import sys\n",
    "\n",
    "import numpy as np\n",
    "import osmnx as ox\n",
    "import pandas as pd\n",
    "\n",
    "ox.__version__"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Elevation from local raster file(s)\n",
    "\n",
    "OSMnx can attach elevations to graph nodes using either a single raster file or a list of raster files. The latter creates a virtual raster VRT composed of the rasters at those filepaths. By default, it uses all available CPUs but you can configure this with an argument."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "address = \"600 Montgomery St, San Francisco, California, USA\"\n",
    "G = ox.graph.graph_from_address(address=address, dist=500, dist_type=\"bbox\", network_type=\"bike\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# add node elevations from a single raster file\n",
    "# some nodes will be null because the single file does not cover the graph's extents\n",
    "raster_path = \"./input_data/elevation1.tif\"\n",
    "G = ox.elevation.add_node_elevations_raster(G, raster_path, cpus=1)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# add node elevations from multiple raster files\n",
    "# no nulls should remain\n",
    "raster_paths = [\"./input_data/elevation1.tif\", \"./input_data/elevation2.tif\"]\n",
    "G = ox.elevation.add_node_elevations_raster(G, raster_paths, cpus=1)\n",
    "assert not np.isnan(np.array(G.nodes(data=\"elevation\"))[:, 1]).any()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# add edge grades and their absolute values\n",
    "G = ox.elevation.add_edge_grades(G, add_absolute=True)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Elevation from Google Maps Elevation API\n",
    "\n",
    "You will need a Google Maps Elevation [API key](https://developers.google.com/maps/documentation/elevation/start). Remember to track your API usage and costs. If you don't want to set up a Google Maps API key, you could use a free alternative web service that provides the same interface, such as [Open Topo Data](https://www.opentopodata.org/) which doesn't require an API key. Note that there is some spatial inaccuracy in elevation data resolution. For example, in San Francisco (where Google's resolution is ~19 meters) a couple of edges in hilly parks have a 50+ percent grade because Google assigns one of their nodes the elevation of a hill adjacent to the street."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# add elevation to each of the nodes, using the Open Topo Data, then calculate edge grades\n",
    "G = ox.graph.graph_from_place(\"Piedmont, California, USA\", network_type=\"drive\")\n",
    "original_elevation_url = ox.settings.elevation_url_template\n",
    "ox.settings.elevation_url_template = (\n",
    "    \"https://api.opentopodata.org/v1/aster30m?locations={locations}\"\n",
    ")\n",
    "G = ox.elevation.add_node_elevations_google(G, batch_size=100, pause=1)\n",
    "G = ox.elevation.add_edge_grades(G)\n",
    "ox.settings.elevation_url_template = original_elevation_url"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# or use the Google Maps Elevation API\n",
    "# replace this with your own API key!\n",
    "try:\n",
    "    from keys import google_elevation_api_key\n",
    "except ImportError:\n",
    "    sys.exit()  # you need an API key to proceed\n",
    "\n",
    "# get the street network for san francisco\n",
    "place = \"San Francisco\"\n",
    "place_query = {\"city\": \"San Francisco\", \"state\": \"California\", \"country\": \"USA\"}\n",
    "G = ox.graph_from_place(place_query, network_type=\"drive\")\n",
    "\n",
    "# add elevation to each of the nodes then calculate edge grades\n",
    "G = ox.elevation.add_node_elevations_google(G, api_key=google_elevation_api_key)\n",
    "G = ox.elevation.add_edge_grades(G)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Calculate some summary stats\n",
    "\n",
    "Use an undirected representation of the network so we don't overcount two-way streets (because they have reciprocal edges pointing in each direction). We use the absolute value of edge grade because we're interested in steepness, not directionality."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# calculate the edges' absolute grades (and drop any infinite/null values)\n",
    "grades = pd.Series([d[\"grade_abs\"] for _, _, d in ox.convert.to_undirected(G).edges(data=True)])\n",
    "grades = grades.replace([np.inf, -np.inf], np.nan).dropna()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "avg_grade = np.mean(grades)\n",
    "print(f\"Average street grade in {place} is {avg_grade * 100:.1f}%\")\n",
    "\n",
    "med_grade = np.median(grades)\n",
    "print(f\"Median street grade in {place} is {med_grade * 100:.1f}%\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Plot the nodes by elevation\n",
    "\n",
    "Plot them colored from low (violet) to high (yellow)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# get one color for each node, by elevation, then plot the network\n",
    "nc = ox.plot.get_node_colors_by_attr(G, \"elevation\", cmap=\"plasma\")\n",
    "fig, ax = ox.plot.plot_graph(G, node_color=nc, node_size=5, edge_color=\"#333333\", bgcolor=\"k\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Plot the edges by grade\n",
    "\n",
    "Grade is the ratio of elevation change to edge length. Plot edges colored from low/flat (violet) to high/steep (yellow)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# get a color for each edge, by grade, then plot the network\n",
    "ec = ox.plot.get_edge_colors_by_attr(G, \"grade_abs\", cmap=\"plasma\", num_bins=5, equal_size=True)\n",
    "fig, ax = ox.plot.plot_graph(G, edge_color=ec, edge_linewidth=0.5, node_size=0, bgcolor=\"k\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Calculate shortest paths, considering grade impedance\n",
    "\n",
    "This example approximates the route of \"The Wiggle\" in San Francisco."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# select an origin and destination node and a bounding box around them\n",
    "origin = ox.distance.nearest_nodes(G, -122.426, 37.77)\n",
    "destination = ox.distance.nearest_nodes(G, -122.441, 37.773)\n",
    "bbox = ox.utils_geo.bbox_from_point((37.772, -122.434), dist=1500)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# define some edge impedance function here\n",
    "\n",
    "\n",
    "def impedance(length, grade):\n",
    "    penalty = grade**2\n",
    "    return length * penalty\n",
    "\n",
    "\n",
    "# add impedance and elevation rise values to each edge in the projected graph\n",
    "# use absolute value of grade in impedance function if you want to avoid uphill and downhill\n",
    "for _, _, _, data in G.edges(keys=True, data=True):\n",
    "    data[\"impedance\"] = impedance(data[\"length\"], data[\"grade_abs\"])\n",
    "    data[\"rise\"] = data[\"length\"] * data[\"grade\"]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### First find the shortest path that minimizes *trip distance*:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "route_by_length = ox.routing.shortest_path(G, origin, destination, weight=\"length\")\n",
    "fig, ax = ox.plot.plot_graph_route(G, route_by_length, bbox=bbox, node_size=0)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Now find the shortest path that avoids slopes by minimizing *impedance* (function of length and grade):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "route_by_impedance = ox.routing.shortest_path(G, origin, destination, weight=\"impedance\")\n",
    "fig, ax = ox.plot.plot_graph_route(G, route_by_impedance, bbox=bbox, node_size=0)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Print some summary stats about these two routes:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def print_route_stats(route):\n",
    "    route_grades = ox.routing.route_to_gdf(G, route, weight=\"grade_abs\")[\"grade_abs\"]\n",
    "    msg = \"The average grade is {:.1f}% and the max is {:.1f}%\"\n",
    "    print(msg.format(np.mean(route_grades) * 100, np.max(route_grades) * 100))\n",
    "\n",
    "    route_rises = ox.routing.route_to_gdf(G, route, weight=\"rise\")[\"rise\"]\n",
    "    ascent = np.sum([rise for rise in route_rises if rise >= 0])\n",
    "    descent = np.sum([rise for rise in route_rises if rise < 0])\n",
    "    msg = \"Total elevation change is {:.1f} meters: {:.0f} meter ascent and {:.0f} meter descent\"\n",
    "    print(msg.format(np.sum(route_rises), ascent, abs(descent)))\n",
    "\n",
    "    route_lengths = ox.routing.route_to_gdf(G, route, weight=\"length\")[\"length\"]\n",
    "    print(f\"Total trip distance: {np.sum(route_lengths):,.0f} meters\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# stats of route minimizing length\n",
    "print_route_stats(route_by_length)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# stats of route minimizing impedance (function of length and grade)\n",
    "print_route_stats(route_by_impedance)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "So, we decreased the average slope along the route from a 5% grade to a 2% grade. The total elevation change is obviously (approximately, due to rounding) the same with either route, but using our impedance function we decrease the total ascent from 69 meters to 42 meters (but the trip distance increases from 1.9 km to 3.3 km)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "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.12.8"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}