supplement_lonboard_leafmap.ipynb

{
  "cells": [
    {
      "cell_type": "markdown",
      "id": "fd708770-59b8-4fb9-acce-2b2d837d88e6",
      "metadata": {
        "id": "fd708770-59b8-4fb9-acce-2b2d837d88e6"
      },
      "source": [
        "### Visualizing Large Vector Datasets with Lonboard\n",
        "\n",
        "[Lonboard](https://github.com/developmentseed/lonboard) is a deck-gl based Python library that allows you to interactively visualize large vector datasets. You can use Lonboard in Leafmap via the [deckgl module](https://leafmap.org/deckgl/).\n",
        "\n",
        "Lonboard uses a different terminology for different types of vector layers.\n",
        "\n",
        "* [ScatterplotLayer](https://developmentseed.org/lonboard/latest/api/layers/scatterplot-layer/): Reders points as circles.\n",
        "* [PathLayer](https://developmentseed.org/lonboard/latest/api/layers/path-layer/): Renders polylines.\n",
        "* [SolidPolygonLayer](https://developmentseed.org/lonboard/latest/api/layers/solid-polygon-layer/): Renders filled and/or extruded polygons.\n",
        "\n",
        "When visualizing vector data via lonboard, please refer to the documentation for appropriate class for the parameter values."
      ]
    },
    {
      "cell_type": "markdown",
      "source": [
        "We will visualize and style a very large layer of rivers using Leafmap and Lonboard.\n",
        "\n",
        "<img src='https://courses.spatialthoughts.com/images/python_dataviz/lonboard_rivers.png' width=800/>"
      ],
      "metadata": {
        "id": "npjQMm3tWYR4"
      },
      "id": "npjQMm3tWYR4"
    },
    {
      "cell_type": "markdown",
      "source": [
        "#### Setup and Data Download"
      ],
      "metadata": {
        "id": "3LKOmTSadQCJ"
      },
      "id": "3LKOmTSadQCJ"
    },
    {
      "cell_type": "code",
      "source": [
        "%%capture\n",
        "if 'google.colab' in str(get_ipython()):\n",
        "  !pip install leafmap lonboard palettable"
      ],
      "metadata": {
        "id": "J3NQFzscSaKk"
      },
      "id": "J3NQFzscSaKk",
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "id": "df487246-fb38-451f-a76d-ffbb7ad95a0f",
      "metadata": {
        "id": "df487246-fb38-451f-a76d-ffbb7ad95a0f"
      },
      "outputs": [],
      "source": [
        "import os\n",
        "import leafmap.deckgl as leafmap\n",
        "import geopandas as gpd\n",
        "import pandas as pd\n",
        "import requests\n",
        "import palettable\n",
        "import lonboard\n"
      ]
    },
    {
      "cell_type": "code",
      "source": [
        "data_folder = 'data'\n",
        "output_folder = 'output'\n",
        "\n",
        "if not os.path.exists(data_folder):\n",
        "    os.mkdir(data_folder)\n",
        "if not os.path.exists(output_folder):\n",
        "    os.mkdir(output_folder)"
      ],
      "metadata": {
        "id": "lOLD5d1yHZIC"
      },
      "id": "lOLD5d1yHZIC",
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "code",
      "source": [
        "def download(url):\n",
        "    filename = os.path.join(data_folder, os.path.basename(url))\n",
        "    if not os.path.exists(filename):\n",
        "      with requests.get(url, stream=True, allow_redirects=True) as r:\n",
        "          with open(filename, 'wb') as f:\n",
        "              for chunk in r.iter_content(chunk_size=8192):\n",
        "                  f.write(chunk)\n",
        "      print('Downloaded', filename)"
      ],
      "metadata": {
        "id": "PuH1yQv2eWwN"
      },
      "execution_count": null,
      "outputs": [],
      "id": "PuH1yQv2eWwN"
    },
    {
      "cell_type": "code",
      "source": [
        "countries_file = 'ne_10m_admin_0_countries_ind.zip'\n",
        "\n",
        "data_url = 'https://github.com/spatialthoughts/python-dataviz-web/releases/download/'\n",
        "\n",
        "# This is a subset of the main HydroRivers dataset of all\n",
        "# rivers having `UPLAND_SKM` value  greater than 100 sq. km.\n",
        "hydrorivers_file = 'hydrorivers_100.gpkg'\n",
        "hydrorivers_url = data_url + 'hydrosheds/'\n",
        "\n",
        "countries_file = 'ne_10m_admin_0_countries_ind.zip'\n",
        "countries_url = data_url + 'naturalearth/'\n",
        "\n",
        "\n",
        "download(hydrorivers_url + hydrorivers_file)\n",
        "download(countries_url + countries_file)"
      ],
      "metadata": {
        "id": "1PVxJlqkHb0q"
      },
      "id": "1PVxJlqkHb0q",
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "qdQxZDgtTCtr"
      },
      "source": [
        "#### Data Pre-Processing\n",
        "\n",
        "Read the countries shapefile."
      ],
      "id": "qdQxZDgtTCtr"
    },
    {
      "cell_type": "code",
      "source": [
        "countries_filepath = os.path.join(data_folder, countries_file)"
      ],
      "metadata": {
        "id": "0bNFbKlpJumx"
      },
      "execution_count": null,
      "outputs": [],
      "id": "0bNFbKlpJumx"
    },
    {
      "cell_type": "markdown",
      "source": [
        "For the assignment, you need to pick the country for which you want to create the map. We can print a list of values from the `SOVEREIGNT` column of `country_gdf` GeoDataFrame using `country_gdf.SOVEREIGNT.values` to know the names of all countries."
      ],
      "metadata": {
        "id": "-RzAI8_8LG_C"
      },
      "id": "-RzAI8_8LG_C"
    },
    {
      "cell_type": "code",
      "source": [
        "country_gdf = gpd.read_file(countries_filepath)\n",
        "print(sorted(country_gdf.SOVEREIGNT.unique()))"
      ],
      "metadata": {
        "id": "cEOW_zcELAAU"
      },
      "execution_count": null,
      "outputs": [],
      "id": "cEOW_zcELAAU"
    },
    {
      "cell_type": "markdown",
      "source": [
        "Select a country name. Replace the value below with your chosen country."
      ],
      "metadata": {
        "id": "aFdoKW6RdkGn"
      },
      "id": "aFdoKW6RdkGn"
    },
    {
      "cell_type": "code",
      "source": [
        "country = 'United States of America'"
      ],
      "metadata": {
        "id": "Iq8X0KHldp63"
      },
      "execution_count": null,
      "outputs": [],
      "id": "Iq8X0KHldp63"
    },
    {
      "cell_type": "markdown",
      "source": [
        "Apply filters to select the country feature. We use an additional filter `TYPE != 'Dependency'` to exclude overseas territories. You may have to adjust the filter to get the correct country polygon."
      ],
      "metadata": {
        "id": "JR2IcuvqMiy_"
      },
      "id": "JR2IcuvqMiy_"
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "44_-SAHzTBuJ"
      },
      "outputs": [],
      "source": [
        "selected_country = country_gdf[\n",
        "    (country_gdf['SOVEREIGNT'] == country) &\n",
        "    (country_gdf['TYPE'] != 'Dependency')\n",
        "]\n",
        "selected_country"
      ],
      "id": "44_-SAHzTBuJ"
    },
    {
      "cell_type": "markdown",
      "source": [
        "We read the river network data from HydroRivers. We specify the `mask` parameter which clips the layer to the country boundary while reading the data.\n",
        "\n",
        "*This step can take a few minutes depending on the size of the country.*"
      ],
      "metadata": {
        "id": "IJ7RMWZU2odS"
      },
      "id": "IJ7RMWZU2odS"
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "gWC-jLkLVMxs"
      },
      "outputs": [],
      "source": [
        "hydrorivers_filepath = os.path.join(data_folder, hydrorivers_file)\n",
        "river_gdf = gpd.read_file(hydrorivers_filepath, mask=selected_country)\n",
        "river_gdf"
      ],
      "id": "gWC-jLkLVMxs"
    },
    {
      "cell_type": "markdown",
      "source": [
        "#### Visualize GeoDataFrame using Lonboard"
      ],
      "metadata": {
        "id": "1-QBEfUI0cRt"
      },
      "id": "1-QBEfUI0cRt"
    },
    {
      "cell_type": "markdown",
      "source": [
        "Lonboard renders line layers using the [`PathLayer`](https://developmentseed.org/lonboard/latest/api/layers/path-layer/) object. We supply the lonboard parameters as keyword arguents to leafmap."
      ],
      "metadata": {
        "id": "QSvQkbcw3h2O"
      },
      "id": "QSvQkbcw3h2O"
    },
    {
      "cell_type": "code",
      "source": [
        "m = leafmap.Map(height=600)\n",
        "m.add_gdf(river_gdf,\n",
        "          zoom_to_layer=True,\n",
        "          pickable=True,\n",
        "          get_width=2,\n",
        "          get_color='blue',\n",
        "          width_units='pixels'\n",
        ")\n",
        "m"
      ],
      "metadata": {
        "id": "U4weByYJZAIU"
      },
      "id": "U4weByYJZAIU",
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "source": [
        "We want to style the rivers so that the width of the line is proportional to the value in the `UPLAND_SKM` attribute. We add a new column `width` to the GeoDataFrame by scaling the input values to a range of target widths."
      ],
      "metadata": {
        "id": "U-q3Qr6VTxdl"
      },
      "id": "U-q3Qr6VTxdl"
    },
    {
      "cell_type": "code",
      "source": [
        "original_min = 300\n",
        "original_max = 10000\n",
        "target_min = 0.1\n",
        "target_max = 1\n",
        "scaled = (river_gdf['UPLAND_SKM'] - original_min) / (original_max - original_min)\n",
        "river_gdf['width'] = scaled.clip(0, 1) * (target_max - target_min) + target_min\n",
        "river_gdf_final = river_gdf.sort_values(['UPLAND_SKM', 'width'])[\n",
        "    ['MAIN_RIV', 'UPLAND_SKM', 'width', 'geometry']]\n",
        "river_gdf_final"
      ],
      "metadata": {
        "id": "ZKomemSQmGWg"
      },
      "execution_count": null,
      "outputs": [],
      "id": "ZKomemSQmGWg"
    },
    {
      "cell_type": "markdown",
      "source": [
        "We want to assign a color based on the `MAIN_RIV` attribute. We will split the rivers into 10 equal bins."
      ],
      "metadata": {
        "id": "q8hzcHcnUAJE"
      },
      "id": "q8hzcHcnUAJE"
    },
    {
      "cell_type": "code",
      "source": [
        "river_gdf_final['color'] = pd.qcut(\n",
        "    river_gdf_final.MAIN_RIV, q=10,\n",
        "    labels=False, duplicates='drop')\n",
        "river_gdf_final"
      ],
      "metadata": {
        "id": "y-fZmJlYR_B1"
      },
      "id": "y-fZmJlYR_B1",
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "source": [
        "We create a discreate colormap by assigning a color to each bin."
      ],
      "metadata": {
        "id": "MOR4K-6sZ254"
      },
      "id": "MOR4K-6sZ254"
    },
    {
      "cell_type": "code",
      "source": [
        "cmap = palettable.colorbrewer.diverging.Spectral_10\n",
        "\n",
        "colormap = {}\n",
        "for i, color in enumerate(cmap.colors):\n",
        "    colormap[i] = color\n",
        "colormap"
      ],
      "metadata": {
        "id": "r5CDH60rOdZW"
      },
      "id": "r5CDH60rOdZW",
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "code",
      "source": [
        "basemap = lonboard.basemap.CartoBasemap.DarkMatterNoLabels\n",
        "cmap = palettable.colorbrewer.diverging.Spectral_10\n",
        "widths = river_gdf_final['width']\n",
        "colors = lonboard.colormap.apply_categorical_cmap(\n",
        "    river_gdf_final['color'], colormap)\n",
        "\n",
        "m = leafmap.Map(height=700, basemap_style=basemap)\n",
        "m.add_gdf(river_gdf_final,\n",
        "          zoom_to_layer=True,\n",
        "          pickable=True,\n",
        "          get_width=widths,\n",
        "          get_color=colors,\n",
        "          width_units='pixels'\n",
        ")\n",
        "m"
      ],
      "metadata": {
        "id": "Jzl9SWKY0iDl"
      },
      "id": "Jzl9SWKY0iDl",
      "execution_count": null,
      "outputs": []
    }
  ],
  "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.10.5"
    },
    "colab": {
      "provenance": []
    }
  },
  "nbformat": 4,
  "nbformat_minor": 5
}