This toolbox generates weights of grid cells contributing to individual shapes. The grid weights are, for example, helpful to spatially aggregate a gridded model output to a irregular shaped domain or, in general, to map grid cells to a polygon shape.
In this case here, any given gridded model output (see examples in example/input_*/*.nc) shall be mapped to a subbasin discretization for the purpose of routing. The subbasin discretization is derived using the RoutingToolbox described by Han et al. (2020a), Han et al. (2020b) and available through Han et al. (2020c). Parts of the Routing Toolbox output is provided here for convenience for an example watershed draining to the WSC streamflow gauge station 02LE024 (see shapefiles in example/maps/*.shp).
The generated file containing the grid weights can be used in the hydrologic modeling framework Raven to handle gridded NetCDF inputs and map them to the subbasins/ HRUs a distributed model is based on. The grid weights file produced here (based on the Routing Toolbox discretization) is then primarily used to run Raven in routing-mode and route gridded model outputs (from any model).
The script is tested under Python 3.6 and 3.8 on MacOS and Windows. It requires the following Python packages:
pip install GDAL(gets youosgeo)pip install argparsepip install numpypip install geopandaspip install netCDF4
In case you are working of ComputeCanada's cluster systems, e.g., Graham you can find instructions on how to setup those Python environments here.
python derive_grid_weights.py -i [your-nc-file] -d [dim-names] -v [var-names] -r [tlbx-shp-file] -s [subbasin-id] -b [gauge-id] -f [shp-attr-name] -o [weights-file] with
[your-nc-file] ... [in] filename of NetCDF file or shapefile that contains how
you discretized your model
[dim-names] ... [in] names of NetCDF dimensions of longitude (x)
and latitude (y) in this order,
e.g. "rlon,rlat"
[var-names] ... [in] names of 2D NetCDF variables containing
longitudes and latitudes (in this order) of
centroids of grid cells,
e.g. "lon,lat"
[tlbx-shp-file] ... [in] name of shapefile routing toolbox provides;
shapefile contains shapes of all land and lake HRUs,
e.g. "HRUs.shp"
[subbasin-id] ... [in] (either this or [gauge-id] must be set)
ID of subbasin most downstream (likely a subbasin
that contains a streamflow gauge station but can
be any subbasin ID); script will include all subbasins
upstream of the given subbasin automatically; according
attribute in [tlbx-shp-file] is called "SubId";
e.g. "7202"
[gauge-id] ... [in] (either this or [subbasin-id] must be set)
ID of streamflow gauging station; according attribute in
[tlbx-shp-file] is called "Obs_NM";
e.g. "02LE024"
[weights-file] ... [in] name of file where derived grid weights
should be stored,
e.g. "GridWeights.txt"
[shp-attr-name] ... [in] in case your model discretization (-i) is a shapefile you
need to provide the attribute name that contains the
numbering from [0...N-1] of your subbasins (this order
needs to match the order of your model outputs in NetCDF file)
Using coarse routing discretization (see file used for -r):
python derive_grid_weights.py -i example/input_VIC/VIC_streaminputs.nc -d "lon,lat" -v "lon,lat" -r example/maps/HRUs_coarse.shp -b 02LE024 -o example/input_VIC/GridWeights.txtUsing fine routing discretization (see file used for -r):
python derive_grid_weights.py -i example/input_VIC/VIC_streaminputs.nc -d "lon,lat" -v "lon,lat" -r example/maps/HRUs_fine.shp -b 02LE024 -o example/input_VIC/GridWeights.txtUsing coarse routing discretization (see file used for -r):
python derive_grid_weights.py -i example/input_MESH/RFF_H_GRD.nc -d "rlon,rlat" -v "longitude,latitude" -r example/maps/HRUs_coarse.shp -b 02LE024 -o example/input_MESH/GridWeights_RFF_H_GRD.txtUsing fine routing discretization (see file used for -r):
python derive_grid_weights.py -i example/input_MESH/RFF_H_GRD.nc -d "rlon,rlat" -v "longitude,latitude" -r example/maps/HRUs_fine.shp -b 02LE024 -o example/input_MESH/GridWeights_RFF_H_GRD.txtUsing coarse routing discretization (see file used for -r):
python derive_grid_weights.py -i example/input_ERA5/era5-crop.nc -d "longitude,latitude" -v "longitude,latitude" -r example/maps/HRUs_coarse.shp -b 02LE024 -o example/input_ERA5/GridWeights_ERA5.txtUsing fine routing discretization (see file used for -r):
python derive_grid_weights.py -i example/input_ERA5/era5-crop.nc -d "longitude,latitude" -v "longitude,latitude" -r example/maps/HRUs_fine.shp -b 02LE024 -o example/input_ERA5/GridWeights_ERA5.txtUsing coarse routing discretization (see file used for -r):
python derive_grid_weights.py -i example/input_SWAT/OTT_sub.shp -f "NetCDF_col" -r example/maps/HRUs_coarse.shp -b 02LE024 -o example/input_SWAT/GridWeights_SWAT.txtFor several subbasins there is a mismatch between the provided domain of SWAT (OTT_sub.shp) and the domain the routing product requires (HRUs_coarse.shp). Basins with large errors are reported on the command-line when you run the script. To force the script to resolve these errors by rescaling the weights available such that they add up to one you can use option -e and set a threshold to which errors are exceptable for you (default: 5% = 0.05). To resolve all previously reported basins use:
python derive_grid_weights.py -i example/input_SWAT/OTT_sub.shp -f "NetCDF_col" -r example/maps/HRUs_coarse.shp -b 02LE024 -o example/input_SWAT/GridWeights_SWAT.txt -e 0.42Using fine routing discretization (see file used for -r):
python derive_grid_weights.py -i example/input_SWAT/OTT_sub.shp -f "NetCDF_col" -r example/maps/HRUs_fine.shp -b 02LE024 -o example/input_SWAT/GridWeights_SWAT.txtHan, M., Mai, J., Tolson, B. A., Craig, J. R., Gaborit, É., Liu, H., and Lee, K. (2020a):
Subwatershed-based lake and river routing products for hydrologic and land surface models applied over Canada
Canadian Water Resources Journal, 0, 1-15. (publication)
Han, M. et al. (2020b):
An automated GIS toolbox for watershed delineation with lakes
In preparation.
Han, M., Mai, J., Tolson, B. A., Craig, J. R., Gaborit, É., Liu, H., and Lee, K. (2020c):
A catchment-based lake and river routing product for hydrologic and land surface models in Canada (Dataset)
Zenodo. (dataset)