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:

  1. 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