Utility Scripts
ravenpy generate-grid-weights
Generate grid weights in various formats.
INPUT_FILE: File containing model discretization. Can be either:
(A) NetCDF file containing at least 1D or 2D latitudes and 1D or 2D longitudes where this grid needs to be representative of model outputs that are then required to be routed. The names of the dimensions and the variables holding the lat/lon information should be specified with options –dim-names (-d) and –var-names (-v).
(B) Shapefile (either a .shp or a .zip) that contains shapes of subbasins and one attribute in this shapefile that is defining its index in the NetCDF model output file (numbering needs to be [0 … N-1]). The name of this attribute should be specified via option –netcdf-input-field (-f).
ROUTING_FILE: Shapefile (either a .shp or a .zip) that contains all information of the routing toolbox for the catchment of interest (and maybe some more catchments). This file should contain an attribute with a unique identifier for the HRUs: the default is “HRU_ID”, but it can be set with –routing-id-field (-c).
The script will output the results as RVT file with a single :GridWeights command block containing the weights (that the user is then free to embed or reference, in her own config context).
ravenpy generate-grid-weights [OPTIONS] INPUT_FILE ROUTING_FILE
Options
- -d, --dim-names <dim_names>
Ordered dimension names of longitude (x) and latitude (y) in the NetCDF INPUT_FILE.
- Default:
lon_dim, lat_dim
- -v, --var-names <var_names>
Variable name of 1D or 2D longitude and latitude variables in the NetCDF INPUT_FILE (in this order).
- Default:
longitude, latitude
- -c, --routing-id-field <routing_id_field>
Name of column in routing information shapefile (ROUTING_FILE) containing a unique key for each dataset.
- Default:
SubId
- -f, --netcdf-input-field <netcdf_input_field>
Attribute name in INPUT_FILE shapefile that defines the index of the shape in NetCDF model output file (numbering needs to be [0 … N-1]).
- Default:
NetCDF_col
- -g, --gauge-id <gauge_ids>
Streamflow gauge IDs of interest (corresponds to ‘Gauge_ID’ in the ROUTING_FILE shapefile).
- -s, --sub-id <sub_ids>
IDs of subbasins of interest (containing usually a gauge station, corresponds to ‘SubId’ in the ROUTING_FILE shapefile).
- -e, --area-error-threshold <area_error_threshold>
Threshold (as fraction) of allowed mismatch in areas between subbasins from routing information (ROUTING_FILE) and overlay with grid-cells or subbasins (INPUT_FILE). If error is smaller than this threshold the weights will be adjusted such that they sum up to exactly 1. Raven will exit gracefully in case weights do not sum up to at least 0.95.
- Default:
0.05
- -o, --output <output>
Text field that will contain the results as a single :GridWeights Raven command containing the weights.
Arguments
- INPUT_FILE
Required argument
- ROUTING_FILE
Required argument
ravenpy aggregate-forcings-to-hrus
Aggregates NetCDF files containing 3-dimensional forcing variables like precipitation and temperature
over (x,y,time) into 2-dimensional forcings for each of the n HRUs of a specific basin over (n,time).
The 3-dimensional NetCDF files are usually used in :GriddedForcing
commands in Raven while the 2-dimensional
ones can be used in :StationForcing
commands. The NetCDF files generated with this function will only
contain the forcings required to simulate an individual basin and hence file sizes are smaller and Raven
runtimes can decrease drastically under certain conditions.
INPUT_NC_FILE: NetCDF file containing 3-dimensional variables that will be aggregated. Either all variables will be aggregated or only a subset specified using –var-to-aggregate (e.g., [precip,temp]). The name of the spatial dimensions of the NetCDF are assumed to be (lon_dim, lat_dim). Otherwise they will need to be specified using –dim-names. The order of the three dimensions for each variable does not matter; the function will arrange them as required.
INPUT_WEIGHT_FILE: A text file containing the grid weights derived using the script “generate-grid-weights”
for the basin forcings are required and the specified NetCDF file. The content of this file must be formatted
as a valid :GridWeights
Raven command.
The script outputs two files:
Aggregated NetCDF file that can be used in a
:StationForcing
command in a Raven config.
(2) A text file (with the same format as INPUT_WEIGHT_FILE) with the updated grid weights, that a :StationForcing
command will require.
ravenpy aggregate-forcings-to-hrus [OPTIONS] INPUT_NC_FILE INPUT_WEIGHT_FILE
Options
- -d, --dim-names <dim_names>
Ordered dimension names of longitude (x) and latitude (y) in the NetCDF INPUT_NC_FILE.
- Default:
lon_dim, lat_dim
- -v, --var-to-aggregate <variables_to_aggregate>
Required Variables to aggregate in INPUT_NC_FILE (at least one).
- --output-nc-file <output_nc_file>
- --output-weight-file <output_weight_file>
Arguments
- INPUT_NC_FILE
Required argument
- INPUT_WEIGHT_FILE
Required argument
ravenpy collect-subbasins-upstream-of-gauge
Find the subbasins upstream of a gauge from a Routing Product shapefile, and save them in a new shapefile.
INPUT_FILE: Routing Product shapefile (e.g. “drainage_region_0003_v2-1/finalcat_info_v2-1.shp”).
GAUGE_ID: ID of the target gauge, to be found in the “Obs_NM” column (e.g. “02LE024”).
ravenpy collect-subbasins-upstream-of-gauge [OPTIONS] INPUT_FILE GAUGE_ID
Options
- -o, --output <output>
Name of the output shapefile.
Arguments
- INPUT_FILE
Required argument
- GAUGE_ID
Required argument
ravenpy generate-hrus-from-routing-product
Create a new HRU shapefile by splitting every subbasin row of a Routing Product V2.1 shapefile into at least a land HRU and possibly an additional lake HRU.
INPUT_FILE: Routing Product V2.1 shapefile (e.g. “drainage_region_0003_v2-1/finalcat_info_v2-1.shp”).
ravenpy generate-hrus-from-routing-product [OPTIONS] INPUT_FILE
Options
- -o, --output <output>
Output shapefiles (will create a folder if no extension)
Arguments
- INPUT_FILE
Required argument