{ "cells": [ { "cell_type": "markdown", "id": "0", "metadata": { "editable": true, "slideshow": { "slide_type": "" }, "tags": [] }, "source": [ "# Use Case Example\n", "\n", "This example illustrates a use case that covers the essential steps involved in building a hydrological model and conducting a climate change analysis:\n", "\n", "- **Identification of the watershed and its key characteristics**\n", " - Beaurivage watershed in Southern Quebec, at the location of the 023401 streamflow gauge.\n", "- **Collection of observed data**\n", " - ERA5-Land and streamflow gauge data.\n", "- **Preparation and calibration of the hydrological model**\n", " - GR4JCN emulated by the Raven hydrological framework.\n", "- **Calculation of hydrological indicators**\n", " - Mean summer flow\n", " - Mean monthly flow\n", " - 20- and 100-year maximum flow\n", " - 2-year minimum 7-day average summer flow\n", "- **Assessment of the impact of climate change**\n", " - Bias-adjusted CMIP6 simulations from the ESPO-G6-R2 dataset\n", "\n", "## Identification of a watershed and its characteristics\n", "\n", "
| \n", " | HRU_ID | \n", "area | \n", "latitude | \n", "longitude | \n", "elevation | \n", "SubId | \n", "DowSubId | \n", "geometry | \n", "
|---|---|---|---|---|---|---|---|---|
| 0 | \n", "7120365812 | \n", "585.585577 | \n", "46.452161 | \n", "-71.260464 | \n", "222.55365 | \n", "1 | \n", "-1 | \n", "POLYGON ((-71.09758 46.40035, -71.09409 46.403... | \n", "
<xarray.Dataset> Size: 454GB\n",
"Dimensions: (time: 27790, lat: 801, lon: 1700)\n",
"Coordinates:\n",
" * time (time) datetime64[ns] 222kB 1950-01-01 1950-01-02 ... 2026-01-31\n",
" * lat (lat) float32 3kB 10.0 10.1 10.2 10.3 10.4 ... 89.7 89.8 89.9 90.0\n",
" * lon (lon) float32 7kB -179.9 -179.8 -179.7 -179.6 ... -10.2 -10.1 -10.0\n",
"Data variables:\n",
" pr (time, lat, lon) float32 151GB dask.array<chunksize=(365, 50, 50), meta=np.ndarray>\n",
" tasmin (time, lat, lon) float32 151GB dask.array<chunksize=(365, 50, 50), meta=np.ndarray>\n",
" tasmax (time, lat, lon) float32 151GB dask.array<chunksize=(365, 50, 50), meta=np.ndarray>\n",
"Attributes: (12/30)\n",
" Conventions: CF-1.9\n",
" cell_methods: time: mean (interval: 1 day)\n",
" doi: https://doi.org/10.24381/cds.e2161bac\n",
" domain: NAM\n",
" frequency: day\n",
" history: [2022-12-25 09:07:39.901698] Converted variabl...\n",
" ... ...\n",
" institute_id: ECMWF\n",
" dataset_id: ERA5-Land\n",
" abstract: ERA5-Land provides hourly high resolution info...\n",
" dataset_description: https://www.ecmwf.int/en/era5-land\n",
" attribution: Contains modified Copernicus Climate Change Se...\n",
" citation: Muñoz Sabater, J., (2021): ERA5-Land hourly da...<xarray.Dataset> Size: 9MB\n",
"Dimensions: (time: 10958, lat: 8, lon: 8)\n",
"Coordinates:\n",
" * time (time) datetime64[ns] 88kB 1991-01-01 1991-01-02 ... 2020-12-31\n",
" * lat (lat) float32 32B 46.1 46.2 46.3 46.4 46.5 46.6 46.7 46.8\n",
" * lon (lon) float32 32B -71.6 -71.5 -71.4 -71.3 -71.2 -71.1 -71.0 -70.9\n",
"Data variables:\n",
" pr (time, lat, lon) float32 3MB dask.array<chunksize=(355, 8, 8), meta=np.ndarray>\n",
" tasmin (time, lat, lon) float32 3MB dask.array<chunksize=(355, 8, 8), meta=np.ndarray>\n",
" tasmax (time, lat, lon) float32 3MB dask.array<chunksize=(355, 8, 8), meta=np.ndarray>\n",
"Attributes: (12/30)\n",
" Conventions: CF-1.9\n",
" cell_methods: time: mean (interval: 1 day)\n",
" doi: https://doi.org/10.24381/cds.e2161bac\n",
" domain: NAM\n",
" frequency: day\n",
" history: [2026-03-31 14:35:41] shape spatial subsetting...\n",
" ... ...\n",
" institute_id: ECMWF\n",
" dataset_id: ERA5-Land\n",
" abstract: ERA5-Land provides hourly high resolution info...\n",
" dataset_description: https://www.ecmwf.int/en/era5-land\n",
" attribution: Contains modified Copernicus Climate Change Se...\n",
" citation: Muñoz Sabater, J., (2021): ERA5-Land hourly da...<xarray.Dataset> Size: 9MB\n",
"Dimensions: (time: 10958, latitude: 8, longitude: 8)\n",
"Coordinates:\n",
" * time (time) datetime64[ns] 88kB 1991-01-01 1991-01-02 ... 2020-12-31\n",
" * latitude (latitude) float32 32B 46.1 46.2 46.3 46.4 46.5 46.6 46.7 46.8\n",
" * longitude (longitude) float32 32B -71.6 -71.5 -71.4 ... -71.1 -71.0 -70.9\n",
" elevation (latitude, longitude) float32 256B dask.array<chunksize=(8, 8), meta=np.ndarray>\n",
"Data variables:\n",
" pr (time, latitude, longitude) float32 3MB dask.array<chunksize=(355, 8, 8), meta=np.ndarray>\n",
" tasmin (time, latitude, longitude) float32 3MB dask.array<chunksize=(355, 8, 8), meta=np.ndarray>\n",
" tasmax (time, latitude, longitude) float32 3MB dask.array<chunksize=(355, 8, 8), meta=np.ndarray>\n",
"Attributes: (12/30)\n",
" Conventions: CF-1.9\n",
" cell_methods: time: mean (interval: 1 day)\n",
" doi: https://doi.org/10.24381/cds.e2161bac\n",
" domain: NAM\n",
" frequency: day\n",
" history: [2026-03-31 14:35:41] shape spatial subsetting...\n",
" ... ...\n",
" institute_id: ECMWF\n",
" dataset_id: ERA5-Land\n",
" abstract: ERA5-Land provides hourly high resolution info...\n",
" dataset_description: https://www.ecmwf.int/en/era5-land\n",
" attribution: Contains modified Copernicus Climate Change Se...\n",
" citation: Muñoz Sabater, J., (2021): ERA5-Land hourly da...<xarray.Dataset> Size: 132kB\n",
"Dimensions: (time: 10958, station_id: 1)\n",
"Coordinates: (12/15)\n",
" * time (time) datetime64[ns] 88kB 1991-01-01 ... 2020-12-31\n",
" * station_id (station_id) <U6 24B '023401'\n",
" drainage_area (station_id) float32 4B 708.0\n",
" end_date (station_id) datetime64[ns] 8B 2020-12-31\n",
" latitude (station_id) float32 4B 46.66\n",
" longitude (station_id) float32 4B -71.29\n",
" ... ...\n",
" source (station_id) <U102 408B 'Ministère de l’Environnement, de ...\n",
" spatial_agg (station_id) <U9 36B 'watershed'\n",
" start_date (station_id) datetime64[ns] 8B 1991-01-01\n",
" variable (station_id) <U10 40B 'streamflow'\n",
" time_agg <U4 16B 'mean'\n",
" timestep <U1 4B 'D'\n",
"Data variables:\n",
" q (time) float32 44kB 46.0 33.9 26.2 21.0 ... 19.98 15.76 12.93<xarray.Dataset> Size: 316B\n",
"Dimensions: (horizon: 1, month: 12)\n",
"Coordinates:\n",
" * horizon (horizon) <U9 36B '1991-2020'\n",
" * month (month) <U3 144B 'JAN' 'FEB' 'MAR' ... 'OCT' 'NOV' 'DEC'\n",
" subbasin_id <U1 4B '1'\n",
" elevation float32 4B 222.6\n",
" drainage_area float64 8B 585.6\n",
" centroid_longitude float64 8B -71.26\n",
" centroid_latitude float64 8B 46.45\n",
"Data variables:\n",
" qmoy_summer (horizon) float64 8B 9.589\n",
" qmoy_monthly (horizon, month) float64 96B 5.919 4.565 ... 12.27 9.125\n",
"Attributes:\n",
" Conventions: CF-1.6\n",
" featureType: timeSeries\n",
" history: Created on 2026-03-31T14:36:41 by Raven 4.1\n",
" description: Standard Output\n",
" references: Craig J.R. and the Raven Development Team Raven us...\n",
" model_id: GR4JCN\n",
" Raven_version: 4.1\n",
" RavenPy_version: 0.20.0\n",
" cat:xrfreq: fx\n",
" cat:frequency: fx\n",
" cat:processing_level: horizons\n",
" cat:variable: ('qmoy_monthly',)<xarray.Dataset> Size: 436B\n",
"Dimensions: (scipy_dist: 4, dparams: 4)\n",
"Coordinates:\n",
" * scipy_dist (scipy_dist) <U10 160B 'genextreme' ... 'pearson3'\n",
" * dparams (dparams) <U5 80B 'c' 'skew' 'loc' 'scale'\n",
" horizon <U9 36B '1991-2020'\n",
" subbasin_id <U1 4B '1'\n",
" elevation float32 4B 222.6\n",
" drainage_area float64 8B 585.6\n",
" centroid_longitude float64 8B -71.26\n",
" centroid_latitude float64 8B 46.45\n",
"Data variables:\n",
" q_max_annual (scipy_dist, dparams) float64 128B 0.08161 nan ... 87.46\n",
"Attributes: (12/13)\n",
" Conventions: CF-1.6\n",
" featureType: timeSeries\n",
" history: Created on 2026-03-31T14:36:41 by Raven 4.1\n",
" description: Standard Output\n",
" references: Craig J.R. and the Raven Development Team Raven us...\n",
" model_id: GR4JCN\n",
" ... ...\n",
" RavenPy_version: 0.20.0\n",
" cat:xrfreq: YS-JAN\n",
" cat:frequency: yr\n",
" cat:processing_level: indicators\n",
" cat:variable: ('q_max_annual',)\n",
" cat:id: <xarray.Dataset> Size: 148B\n",
"Dimensions: (return_period: 2)\n",
"Coordinates:\n",
" * return_period (return_period) int64 16B 20 100\n",
" p_quantile (return_period) float64 16B 0.95 0.99\n",
" horizon <U9 36B '1991-2020'\n",
" scipy_dist <U8 32B 'gumbel_r'\n",
" subbasin_id <U1 4B '1'\n",
" elevation float32 4B 222.6\n",
" drainage_area float64 8B 585.6\n",
" centroid_longitude float64 8B -71.26\n",
" centroid_latitude float64 8B 46.45\n",
"Data variables:\n",
" q_max_annual (return_period) float64 16B 363.4 473.8\n",
"Attributes: (12/13)\n",
" Conventions: CF-1.6\n",
" featureType: timeSeries\n",
" history: Created on 2026-03-31T14:36:41 by Raven 4.1\n",
" description: Standard Output\n",
" references: Craig J.R. and the Raven Development Team Raven us...\n",
" model_id: GR4JCN\n",
" ... ...\n",
" RavenPy_version: 0.20.0\n",
" cat:xrfreq: YS-JAN\n",
" cat:frequency: yr\n",
" cat:processing_level: indicators\n",
" cat:variable: ('q_max_annual',)\n",
" cat:id: <xarray.Dataset> Size: 568B\n",
"Dimensions: (horizon: 2, month: 12, return_period: 2)\n",
"Coordinates:\n",
" * horizon (horizon) <U9 72B '1991-2020' '2070-2099'\n",
" * month (month) <U3 144B 'JAN' 'FEB' 'MAR' ... 'OCT' 'NOV' 'DEC'\n",
" * return_period (return_period) int64 16B 20 100\n",
" p_quantile (return_period) float64 16B 0.95 0.99\n",
" subbasin_id <U1 4B '1'\n",
" elevation float32 4B 222.6\n",
" drainage_area float64 8B 585.6\n",
" centroid_longitude float64 8B -71.26\n",
" centroid_latitude float64 8B 46.45\n",
" scipy_dist <U8 32B 'gumbel_r'\n",
"Data variables:\n",
" qmoy_summer (horizon) float64 16B 9.707 8.611\n",
" qmoy_monthly (horizon, month) float64 192B 7.359 6.124 ... 11.74\n",
" q_max_annual (return_period, horizon) float64 32B 325.4 ... 437.9\n",
" q7_min_summer (horizon) float64 16B 2.109 1.983\n",
"Attributes:\n",
" Conventions: CF-1.6\n",
" featureType: timeSeries\n",
" history: Created on 2026-03-31T14:40:01 by Raven 4.1\n",
" description: Standard Output\n",
" references: Craig J.R. and the Raven Development Team Raven us...\n",
" model_id: GR4JCN\n",
" Raven_version: 4.1\n",
" RavenPy_version: 0.20.0\n",
" cat:xrfreq: fx\n",
" cat:frequency: fx\n",
" cat:processing_level: horizons\n",
" cat:variable: ('qmoy_monthly',)<xarray.Dataset> Size: 404B\n",
"Dimensions: (month: 12, return_period: 2)\n",
"Coordinates:\n",
" * month (month) <U3 144B 'JAN' 'FEB' 'MAR' ... 'OCT' 'NOV' 'DEC'\n",
" * return_period (return_period) int64 16B 20 100\n",
" p_quantile (return_period) float64 16B 0.95 0.99\n",
" subbasin_id <U1 4B '1'\n",
" elevation float32 4B 222.6\n",
" drainage_area float64 8B 585.6\n",
" centroid_longitude float64 8B -71.26\n",
" centroid_latitude float64 8B 46.45\n",
" horizon <U9 36B '2070-2099'\n",
" scipy_dist <U8 32B 'gumbel_r'\n",
"Data variables:\n",
" qmoy_summer float64 8B -11.29\n",
" qmoy_monthly (month) float64 96B 14.88 10.29 61.14 ... 22.37 24.68\n",
" q_max_annual (return_period) float64 16B 4.637 7.371\n",
" q7_min_summer float64 8B -5.966\n",
"Attributes:\n",
" Conventions: CF-1.6\n",
" featureType: timeSeries\n",
" history: Created on 2026-03-31T14:40:01 by Raven 4.1\n",
" description: Standard Output\n",
" references: Craig J.R. and the Raven Development Team Raven us...\n",
" model_id: GR4JCN\n",
" Raven_version: 4.1\n",
" RavenPy_version: 0.20.0\n",
" cat:xrfreq: fx\n",
" cat:frequency: fx\n",
" cat:processing_level: deltas\n",
" cat:variable: ('qmoy_monthly',)<xarray.Dataset> Size: 2kB\n",
"Dimensions: (percentiles: 5, month: 12, return_period: 2)\n",
"Coordinates:\n",
" * percentiles (percentiles) int64 40B 10 25 50 75 90\n",
" * month (month) <U3 144B 'JAN' 'FEB' ... 'NOV' 'DEC'\n",
" * return_period (return_period) int64 16B 20 100\n",
" p_quantile (return_period) float64 16B 0.95 0.99\n",
" basin_name <U7 28B 'sub_001'\n",
" horizon <U9 36B '2070-2099'\n",
" subbasin_id <U1 4B '1'\n",
" elevation float32 4B 222.6\n",
" drainage_area float64 8B 585.6\n",
" centroid_longitude float64 8B -71.26\n",
" centroid_latitude float64 8B 46.45\n",
"Data variables: (12/32)\n",
" qmoy_summer (percentiles) float64 40B -14.0 ... 19.14\n",
" qmoy_monthly (month, percentiles) float64 480B dask.array<chunksize=(12, 5), meta=np.ndarray>\n",
" q_max_annual (return_period, percentiles) float64 80B dask.array<chunksize=(2, 5), meta=np.ndarray>\n",
" q7_min_summer (percentiles) float64 40B -28.54 ... 11.68\n",
" qmoy_summer_changed float64 8B 1.0\n",
" qmoy_summer_positive float64 8B 0.5714\n",
" ... ...\n",
" q7_min_summer_positive float64 8B 0.2143\n",
" q7_min_summer_changed_positive float64 8B 0.2143\n",
" q7_min_summer_negative float64 8B 0.7857\n",
" q7_min_summer_changed_negative float64 8B 0.7857\n",
" q7_min_summer_valid float64 8B 1.0\n",
" q7_min_summer_agree float64 8B 0.7857\n",
"Attributes:\n",
" cat:xrfreq: fx\n",
" cat:frequency: fx\n",
" cat:processing_level: ensemble\n",
" cat:variable: qmoy_monthly\n",
" ensemble_size: 4"
],
"text/plain": [
"