{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# State-level Overview of Sewersheds\n",
    "\n",
    "In this Jupyter notebook for Python, we visualize sewersheds at the state level.\n",
    "\n",
    "## Data requirements\n",
    "\n",
    "- Approximate positions of sewersheds represented as points\n",
    "  * Each point needs to have an attribute with size of the population the given sewershed serves.\n",
    "- State boundary"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Software setup \n",
    "\n",
    "We will use a couple of standard Python packages and GRASS GIS.\n",
    "\n",
    "For now, the setup here assumes Linux. Instructions for Windows are available at [GRASS GIS Jupyter notebooks wiki page](https://grasswiki.osgeo.org/wiki/GRASS_GIS_Jupyter_notebooks#Running_a_Jupyter_notebook_locally)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Import Python standard library and IPython packages we need.\n",
    "import os\n",
    "import subprocess\n",
    "import sys\n",
    "from pathlib import Path\n",
    "\n",
    "# Ask GRASS GIS where its Python packages are.\n",
    "sys.path.append(\n",
    "    subprocess.check_output([\"grass\", \"--config\", \"python_path\"], text=True).strip()\n",
    ")\n",
    "\n",
    "# Import the GRASS GIS packages we need.\n",
    "import grass.script as gs\n",
    "import grass.jupyter as gj"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Get the data ready\n",
    "\n",
    "This notebooks needs sewershed locations as vector points with at attributes for population size and name. The file should be in directory `data/sewers_state` and should be named `sewer_points` with file extension appropriate for the format, e.g. `sewer_points.shp`. Either rename the files or modify the code below if needed."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "data_directory = \"data/sewers_state\"\n",
    "point_file = \"sewer_points\"  # Filename without file extension\n",
    "state_boundary_file = \"state_boundary\""
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "grass_project = \"data/state_overview\""
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To compute the data, we will use a GRASS project (aka location)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "!grass -e -c $data_directory $grass_project"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "session = gj.init(grass_project)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "From now on, we will use the following variables to refer to the data in the GRASS project."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "point_vector = \"points\"\n",
    "state_boundary_vector = \"state_boundary_vector\""
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "gs.run_command(\"v.import\", input=data_directory, layer=point_file, output=point_vector)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "gs.run_command(\n",
    "    \"v.import\",\n",
    "    input=data_directory,\n",
    "    layer=state_boundary_file,\n",
    "    output=state_boundary_vector,\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Render"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Extract the large sewersheds.\n",
    "large_sewersheds = \"large_sewersheds\"\n",
    "\n",
    "gs.run_command(\n",
    "    \"v.extract\",\n",
    "    input=point_vector,\n",
    "    output=large_sewersheds,\n",
    "    where=\"pop_2020 > 100000\",\n",
    ")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "gs.run_command(\"g.region\", vector=\"nc_state\", res=1000, grow=50)\n",
    "state_map = gj.Map(width=1024, use_region=True)\n",
    "state_map.d_background(color=\"white\")\n",
    "state_map.d_vect(flags=\"s\", map=state_boundary_vector, fill_color=\"none\")\n",
    "state_map.d_vect_thematic(\n",
    "    map=point_vector,\n",
    "    column=\"pop_2020\",\n",
    "    legend_title=\"Population per sewershed\",\n",
    "    colors=\"#ADA8A7,#6A00A8,#B12A90,#E16462,#FCA636,#F0F921\",\n",
    "    breaks=[100000, 200000, 300000, 400000],\n",
    "    boundary_color=\"none\",\n",
    "    icon=\"basic/circle\",\n",
    "    size=10,\n",
    ")\n",
    "# We rendered the points colored by population. Now we take the large\n",
    "# sewersheds and render their names as labels in the map (this happens in two\n",
    "# steps (first, labels are extracted and laid out, then rendered in\n",
    "# the second step).\n",
    "gs.run_command(\n",
    "    \"v.label.sa\",\n",
    "    map=large_sewersheds,\n",
    "    column=\"site_name\",\n",
    "    labels=\"points_site_name\",\n",
    "    font=\"DejaVuSans\",\n",
    "    size=30000,\n",
    "    color=\"black\",\n",
    "    isize=25000,\n",
    ")\n",
    "state_map.d_labels(labels=\"points_site_name\")\n",
    "state_map.d_legend_vect(flags=\"b\", at=(3, 34), columns=2)\n",
    "state_map.d_barscale(flags=\"n\", at=(2, 7), length=200, units=\"kilometers\")\n",
    "state_map.save(Path(data_directory) / \"nc_sewersheds.png\")\n",
    "state_map.show()"
   ]
  }
 ],
 "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.8.10"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}