Extract_River_Segments_from_HydroRIVERS.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "31fd200c",
   "metadata": {},
   "source": [
    "# Extract river segements from HydroRIVERS\n",
    "\n",
    "The following code takes a continental-scale rivers shapefile from the HydroATLAS \"HydroRIVERS\" database, which is a large polyline file containing segments of all large rivers in the world. The user should first open the shpaefile in a GIS and find the desired river to extract. The user should then choose the most upstream segment they want for the extraction, and record the 'HYRIV_ID' for that segment. 'HYRIV_ID' is a unique numeric for each segment in the dataset. The user then enters the desired dataset name, path, the 'HYRIV_ID', a river name, and an output path (optional). Executing the code extracts all river segments downstream of and including the given 'HYRIV_ID' segment, terminating at the ocean or depositional basin. This is written as a shapefile to the desired output folder and named after the river.\n",
    "\n",
    "Author: James (Huck) Rees; PhD Student, UCSB Geography\n",
    "\n",
    "Date: June 25th, 2024"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "0346ff4d",
   "metadata": {},
   "source": [
    "## Import libraries"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "b498dad0",
   "metadata": {},
   "outputs": [],
   "source": [
    "import geopandas as gpd\n",
    "import pandas as pd\n",
    "import os"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e0b842ae",
   "metadata": {},
   "source": [
    "## Initialize functions"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "id": "e365e85e",
   "metadata": {},
   "outputs": [],
   "source": [
    "def find_downstream_segments(gdf, hyriv_id):\n",
    "    \"\"\"\n",
    "    Find all downstream segments for a given river segment.\n",
    "\n",
    "    Parameters:\n",
    "    gdf (gpd.GeoDataFrame): The GeoDataFrame containing river segments.\n",
    "    hyriv_id (int): The HYRIV_ID of the starting river segment.\n",
    "\n",
    "    Returns:\n",
    "    gpd.GeoDataFrame: A GeoDataFrame containing all downstream segments.\n",
    "    \"\"\"\n",
    "    downstream_segments = []\n",
    "    current_segment = gdf[gdf['HYRIV_ID'] == hyriv_id]\n",
    "\n",
    "    while not current_segment.empty:\n",
    "        downstream_segments.append(current_segment)\n",
    "        next_down_id = current_segment.iloc[0]['NEXT_DOWN']\n",
    "        \n",
    "        if next_down_id == 0:\n",
    "            break\n",
    "        \n",
    "        current_segment = gdf[gdf['HYRIV_ID'] == next_down_id]\n",
    "\n",
    "    return gpd.GeoDataFrame(pd.concat(downstream_segments, ignore_index=True))\n",
    "\n",
    "def extract_downstream_rivers(shapefile_path: str, hyriv_id: int, output_folder: str, river_name: str) -> None:\n",
    "    \"\"\"\n",
    "    Extract and save all downstream river segments starting from a given segment.\n",
    "\n",
    "    Parameters:\n",
    "    shapefile_path (str): The path to the input shapefile containing river segments.\n",
    "    hyriv_id (int): The HYRIV_ID of the starting river segment.\n",
    "    output_folder (str): The folder path where the output shapefile will be stored.\n",
    "    river_name (str): The name of the river to be used as the shapefile name and subfolder.\n",
    "\n",
    "    Returns:\n",
    "    None\n",
    "    \"\"\"\n",
    "    # Construct the full path to the output shapefile, including a subfolder named river_name\n",
    "    output_directory = os.path.join(output_folder, river_name)\n",
    "    output_shapefile_path = os.path.join(output_directory, river_name + '.shp')\n",
    "\n",
    "    # Create the directory if it does not exist\n",
    "    os.makedirs(output_directory, exist_ok=True)\n",
    "\n",
    "    # Load the shapefile into a GeoDataFrame\n",
    "    gdf = gpd.read_file(shapefile_path)\n",
    "\n",
    "    # Find all downstream segments starting from the specified HYRIV_ID\n",
    "    downstream_gdf = find_downstream_segments(gdf, hyriv_id)\n",
    "\n",
    "    # Save the downstream segments to the constructed output shapefile path\n",
    "    downstream_gdf.to_file(output_shapefile_path)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "cf0a3967",
   "metadata": {},
   "source": [
    "## Input variables and run"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "id": "cf50e090",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Required inputs\n",
    "hyriv_id = 40784746  # Replace with your starting HYRIV_ID\n",
    "river_name = 'Brahmaputra'   # Name of river. This will be used to ID it throughout entire future analysis\n",
    "shapefile_path = r'C:\\Users\\huckr\\Desktop\\UCSB\\Dissertation\\Data\\RiverMapping\\HydroATLAS\\HydroRIVERS\\Asia\\HydroRIVERS_Asia.shp'\n",
    "\n",
    "# Optional inputs\n",
    "output_folder = r'C:\\Users\\huckr\\Desktop\\UCSB\\Dissertation\\Data\\RiverMapping\\HydroATLAS\\HydroRIVERS\\Extracted_Rivers'\n",
    "\n",
    "extract_downstream_rivers(shapefile_path, hyriv_id, \n",
    "                          output_folder, \n",
    "                          river_name)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "650acfc0",
   "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.11.5"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}