Processes

Raven emulated models

class raven.processes.RavenProcess[source]

raven Run the Raven hydrological framework using model configuration files and forcing time series. In the rvt file, only provide the name of the forcing file, not an absolute or relative path. (v0.1)

Raven hydrological framework

Parameters

  • ts (application/x-netcdf, application/x-ogc-dods, text/plain, application/x-zipped-shp) – Files (text or netCDF) storingdaily liquid precipitation (pr), solid precipitation (prsn), minimum temperature (tasmin), maximum temperature (tasmax), potential evapotranspiration (evspsbl) and observed streamflow (qobs [m3/s]).

  • nc_spec (string, optional) – Configuration of individual netCDF input files, such as linear_transform`and `time_shift. Should be passed as a dictionary keyed by variable, e.g. tas json-serialized.

  • conf (text/plain) – Model configuration files, including the primary input file (rvi), the parameter input file (rvp), the basin definition file (rvh), the time series input file (rvt), the initial conditions file (rvc). For Ostrich, include the Ostrich calibration config (txt) and templates (tpl).

Returns

  • hydrograph (application/x-netcdf, application/zip) – A netCDF file containing the outflow hydrographs (in m3/s) for all subbasins specified as gauged in the .rvh file. It reports period-ending time-averaged flows for the preceding time step, as is consistent with most measured stream gauge data (again, the initial flow conditions at the start of the first time step are included). If observed hydrographs are specified, they will be output adjacent to the corresponding modelled hydrograph.

  • storage (application/x-netcdf, application/zip) – A netCDF file describing the total storage of water (in mm) in all water storage compartments for each time step of the simulation. Mass balance errors, cumulative input (precipitation), and output (channel losses) are also included. Note that the precipitation rates in this file are period-ending, i.e., this is the precipitation rate for the time step preceding the time stamp; all water storage variables represent instantaneous reports of the storage at the time stamp indicate.

  • solution (text/plain, application/zip) – solution.rvc file to restart another simulation with the conditions at the end of this simulation.

  • diagnostics (text/plain, application/zip) – Model diagnostic CSV file.

  • rv_config (application/zip) – Model configuration files, including the primary input file (rvi), the parameter input file (rvp), the basin definition file (rvh), the time series input file (rvt), the initial conditions file (rvc). For Ostrich, include the Ostrich calibration config (txt) and templates (tpl).

class raven.processes.RavenGR4JCemaNeigeProcess[source]

raven-gr4j-cemaneige (v)

Raven GR4J + CEMANEIGE hydrological model

Parameters

  • ts (application/x-netcdf, application/x-ogc-dods, text/plain, application/x-zipped-shp) – Files (text or netCDF) storingdaily liquid precipitation (pr), solid precipitation (prsn), minimum temperature (tasmin), maximum temperature (tasmax), potential evapotranspiration (evspsbl) and observed streamflow (qobs [m3/s]).

  • nc_spec (string, optional) – Configuration of individual netCDF input files, such as linear_transform`and `time_shift. Should be passed as a dictionary keyed by variable, e.g. tas json-serialized.

  • params (string, optional) – Parameters: GR4J_X1, GR4J_X2, GR4J_X3, GR4J_X4, CEMANEIGE_X1, CEMANEIGE_X2

  • start_date (dateTime, optional) – Start date of the simulation (AAAA-MM-DD). Defaults to the start of the forcing file.

  • end_date (dateTime, optional) – End date of the simulation (AAAA-MM-DD). Defaults to the end of the forcing file.

  • nc_index (integer, optional) – The site index for a multi-basin netCDF file. This is ONLY necessary if the NetCDF variable is 2-dimensional (time, site).

  • duration (nonNegativeInteger, optional) – Number of simulated days, defaults to the length of the input forcings.

  • run_name (string, optional) – The name given to the simulation, for example <watershed>_<experiment>

  • name (string, optional) – The name of the watershed the model is run for.

  • area (float, optional) – Watershed area (km2)

  • latitude (float) – Watershed’s centroid latitude

  • longitude (float) – Watershed’s centroid longitude

  • elevation (float) – Watershed’s mean elevation (m)

  • evaporation ({'PET_CONSTANT', 'PET_PENMAN_MONTEITH', 'PET_PENMAN_COMBINATION', 'PET_PRIESTLEY_TAYLOR', 'PET_HARGREAVES', 'PET_HARGREAVES_1985', 'PET_FROMMONTHLY', 'PET_DATA', 'PET_HAMON_1961', 'PET_TURC_1961', ..}, optional) – Algorithm used to compute potential evapotranspiration (PET).

  • rain_snow_fraction ({'RAINSNOW_DATA', 'RAINSNOW_DINGMAN', 'RAINSNOW_UBC', 'RAINSNOW_HBV', 'RAINSNOW_HARDER', 'RAINSNOW_HSPF'}, optional) – Algorithm used to partition rain and snow from the total precipitions

Returns

  • hydrograph (application/x-netcdf, application/zip) – A netCDF file containing the outflow hydrographs (in m3/s) for all subbasins specified as gauged in the .rvh file. It reports period-ending time-averaged flows for the preceding time step, as is consistent with most measured stream gauge data (again, the initial flow conditions at the start of the first time step are included). If observed hydrographs are specified, they will be output adjacent to the corresponding modelled hydrograph.

  • storage (application/x-netcdf, application/zip) – A netCDF file describing the total storage of water (in mm) in all water storage compartments for each time step of the simulation. Mass balance errors, cumulative input (precipitation), and output (channel losses) are also included. Note that the precipitation rates in this file are period-ending, i.e., this is the precipitation rate for the time step preceding the time stamp; all water storage variables represent instantaneous reports of the storage at the time stamp indicate.

  • solution (text/plain, application/zip) – solution.rvc file to restart another simulation with the conditions at the end of this simulation.

  • diagnostics (text/plain, application/zip) – Model diagnostic CSV file.

  • rv_config (application/zip) – Model configuration files, including the primary input file (rvi), the parameter input file (rvp), the basin definition file (rvh), the time series input file (rvt), the initial conditions file (rvc). For Ostrich, include the Ostrich calibration config (txt) and templates (tpl).

RAVEN emulator for the GR4J-Cemaneige model.

This process runs the GR4J-Cemaneige model using a RAVEN emulator. Users need to provide netCDF input files for rain, snow minimum and maximum temperature as well as potential evapotranspiration. To run diagnostics, observed stream flows are also required.

class raven.processes.RavenMOHYSEProcess[source]

raven-mohyse TODO (v)

MOHYSE hydrological model

Parameters

  • ts (application/x-netcdf, application/x-ogc-dods, text/plain, application/x-zipped-shp) – Files (text or netCDF) storingdaily liquid precipitation (pr), solid precipitation (prsn), minimum temperature (tasmin), maximum temperature (tasmax), potential evapotranspiration (evspsbl) and observed streamflow (qobs [m3/s]).

  • nc_spec (string, optional) – Configuration of individual netCDF input files, such as linear_transform`and `time_shift. Should be passed as a dictionary keyed by variable, e.g. tas json-serialized.

  • params (string, optional) – Parameters: par_x01, par_x02, par_x03, par_x04, par_x05, par_x06, par_x07, par_x08, par_x09, par_x10

  • start_date (dateTime, optional) – Start date of the simulation (AAAA-MM-DD). Defaults to the start of the forcing file.

  • end_date (dateTime, optional) – End date of the simulation (AAAA-MM-DD). Defaults to the end of the forcing file.

  • nc_index (integer, optional) – The site index for a multi-basin netCDF file. This is ONLY necessary if the NetCDF variable is 2-dimensional (time, site).

  • duration (nonNegativeInteger, optional) – Number of simulated days, defaults to the length of the input forcings.

  • run_name (string, optional) – The name given to the simulation, for example <watershed>_<experiment>

  • name (string, optional) – The name of the watershed the model is run for.

  • area (float, optional) – Watershed area (km2)

  • latitude (float) – Watershed’s centroid latitude

  • longitude (float) – Watershed’s centroid longitude

  • elevation (float) – Watershed’s mean elevation (m)

  • rain_snow_fraction ({'RAINSNOW_DATA', 'RAINSNOW_DINGMAN', 'RAINSNOW_UBC', 'RAINSNOW_HBV', 'RAINSNOW_HARDER', 'RAINSNOW_HSPF'}, optional) – Algorithm used to partition rain and snow from the total precipitions

  • evaporation ({'PET_CONSTANT', 'PET_PENMAN_MONTEITH', 'PET_PENMAN_COMBINATION', 'PET_PRIESTLEY_TAYLOR', 'PET_HARGREAVES', 'PET_HARGREAVES_1985', 'PET_FROMMONTHLY', 'PET_DATA', 'PET_HAMON_1961', 'PET_TURC_1961', ..}, optional) – Algorithm used to compute potential evapotranspiration (PET).

Returns

  • hydrograph (application/x-netcdf, application/zip) – A netCDF file containing the outflow hydrographs (in m3/s) for all subbasins specified as gauged in the .rvh file. It reports period-ending time-averaged flows for the preceding time step, as is consistent with most measured stream gauge data (again, the initial flow conditions at the start of the first time step are included). If observed hydrographs are specified, they will be output adjacent to the corresponding modelled hydrograph.

  • storage (application/x-netcdf, application/zip) – A netCDF file describing the total storage of water (in mm) in all water storage compartments for each time step of the simulation. Mass balance errors, cumulative input (precipitation), and output (channel losses) are also included. Note that the precipitation rates in this file are period-ending, i.e., this is the precipitation rate for the time step preceding the time stamp; all water storage variables represent instantaneous reports of the storage at the time stamp indicate.

  • solution (text/plain, application/zip) – solution.rvc file to restart another simulation with the conditions at the end of this simulation.

  • diagnostics (text/plain, application/zip) – Model diagnostic CSV file.

  • rv_config (application/zip) – Model configuration files, including the primary input file (rvi), the parameter input file (rvp), the basin definition file (rvh), the time series input file (rvt), the initial conditions file (rvc). For Ostrich, include the Ostrich calibration config (txt) and templates (tpl).

class raven.processes.RavenHMETSProcess[source]

raven-hmets (v)

HMETS hydrological model

Parameters

  • ts (application/x-netcdf, application/x-ogc-dods, text/plain, application/x-zipped-shp) – Files (text or netCDF) storingdaily liquid precipitation (pr), solid precipitation (prsn), minimum temperature (tasmin), maximum temperature (tasmax), potential evapotranspiration (evspsbl) and observed streamflow (qobs [m3/s]).

  • nc_spec (string, optional) – Configuration of individual netCDF input files, such as linear_transform`and `time_shift. Should be passed as a dictionary keyed by variable, e.g. tas json-serialized.

  • params (string, optional) – Parameters: GAMMA_SHAPE, GAMMA_SCALE, GAMMA_SHAPE2, GAMMA_SCALE2, MIN_MELT_FACTOR, MAX_MELT_FACTOR, DD_MELT_TEMP, DD_AGGRADATION, SNOW_SWI_MIN, SNOW_SWI_MAX, SWI_REDUCT_COEFF, DD_REFREEZE_TEMP, REFREEZE_FACTOR, REFREEZE_EXP, PET_CORRECTION, HMETS_RUNOFF_COEFF, PERC_COEFF, BASEFLOW_COEFF_1, BASEFLOW_COEFF_2, TOPSOIL, PHREATIC

  • start_date (dateTime, optional) – Start date of the simulation (AAAA-MM-DD). Defaults to the start of the forcing file.

  • end_date (dateTime, optional) – End date of the simulation (AAAA-MM-DD). Defaults to the end of the forcing file.

  • nc_index (integer, optional) – The site index for a multi-basin netCDF file. This is ONLY necessary if the NetCDF variable is 2-dimensional (time, site).

  • duration (nonNegativeInteger, optional) – Number of simulated days, defaults to the length of the input forcings.

  • run_name (string, optional) – The name given to the simulation, for example <watershed>_<experiment>

  • name (string, optional) – The name of the watershed the model is run for.

  • area (float, optional) – Watershed area (km2)

  • latitude (float) – Watershed’s centroid latitude

  • longitude (float) – Watershed’s centroid longitude

  • elevation (float) – Watershed’s mean elevation (m)

  • rain_snow_fraction ({'RAINSNOW_DATA', 'RAINSNOW_DINGMAN', 'RAINSNOW_UBC', 'RAINSNOW_HBV', 'RAINSNOW_HARDER', 'RAINSNOW_HSPF'}, optional) – Algorithm used to partition rain and snow from the total precipitions

  • evaporation ({'PET_CONSTANT', 'PET_PENMAN_MONTEITH', 'PET_PENMAN_COMBINATION', 'PET_PRIESTLEY_TAYLOR', 'PET_HARGREAVES', 'PET_HARGREAVES_1985', 'PET_FROMMONTHLY', 'PET_DATA', 'PET_HAMON_1961', 'PET_TURC_1961', ..}, optional) – Algorithm used to compute potential evapotranspiration (PET).

Returns

  • hydrograph (application/x-netcdf, application/zip) – A netCDF file containing the outflow hydrographs (in m3/s) for all subbasins specified as gauged in the .rvh file. It reports period-ending time-averaged flows for the preceding time step, as is consistent with most measured stream gauge data (again, the initial flow conditions at the start of the first time step are included). If observed hydrographs are specified, they will be output adjacent to the corresponding modelled hydrograph.

  • storage (application/x-netcdf, application/zip) – A netCDF file describing the total storage of water (in mm) in all water storage compartments for each time step of the simulation. Mass balance errors, cumulative input (precipitation), and output (channel losses) are also included. Note that the precipitation rates in this file are period-ending, i.e., this is the precipitation rate for the time step preceding the time stamp; all water storage variables represent instantaneous reports of the storage at the time stamp indicate.

  • solution (text/plain, application/zip) – solution.rvc file to restart another simulation with the conditions at the end of this simulation.

  • diagnostics (text/plain, application/zip) – Model diagnostic CSV file.

  • rv_config (application/zip) – Model configuration files, including the primary input file (rvi), the parameter input file (rvp), the basin definition file (rvh), the time series input file (rvt), the initial conditions file (rvc). For Ostrich, include the Ostrich calibration config (txt) and templates (tpl).

class raven.processes.RavenHBVECProcess[source]

raven-hbv-ec (v)

HBV-EC hydrological model

Parameters

  • ts (application/x-netcdf, application/x-ogc-dods, text/plain, application/x-zipped-shp) – Files (text or netCDF) storingdaily liquid precipitation (pr), solid precipitation (prsn), minimum temperature (tasmin), maximum temperature (tasmax), potential evapotranspiration (evspsbl) and observed streamflow (qobs [m3/s]).

  • nc_spec (string, optional) – Configuration of individual netCDF input files, such as linear_transform`and `time_shift. Should be passed as a dictionary keyed by variable, e.g. tas json-serialized.

  • params (string, optional) – Parameters: par_x01, par_x02, par_x03, par_x04, par_x05, par_x06, par_x07, par_x08, par_x09, par_x10, par_x11, par_x12, par_x13, par_x14, par_x15, par_x16, par_x17, par_x18, par_x19, par_x20, par_x21

  • start_date (dateTime, optional) – Start date of the simulation (AAAA-MM-DD). Defaults to the start of the forcing file.

  • end_date (dateTime, optional) – End date of the simulation (AAAA-MM-DD). Defaults to the end of the forcing file.

  • nc_index (integer, optional) – The site index for a multi-basin netCDF file. This is ONLY necessary if the NetCDF variable is 2-dimensional (time, site).

  • duration (nonNegativeInteger, optional) – Number of simulated days, defaults to the length of the input forcings.

  • run_name (string, optional) – The name given to the simulation, for example <watershed>_<experiment>

  • name (string, optional) – The name of the watershed the model is run for.

  • area (float, optional) – Watershed area (km2)

  • latitude (float) – Watershed’s centroid latitude

  • longitude (float) – Watershed’s centroid longitude

  • elevation (float) – Watershed’s mean elevation (m)

  • rain_snow_fraction ({'RAINSNOW_DATA', 'RAINSNOW_DINGMAN', 'RAINSNOW_UBC', 'RAINSNOW_HBV', 'RAINSNOW_HARDER', 'RAINSNOW_HSPF'}, optional) – Algorithm used to partition rain and snow from the total precipitions

  • evaporation ({'PET_CONSTANT', 'PET_PENMAN_MONTEITH', 'PET_PENMAN_COMBINATION', 'PET_PRIESTLEY_TAYLOR', 'PET_HARGREAVES', 'PET_HARGREAVES_1985', 'PET_FROMMONTHLY', 'PET_DATA', 'PET_HAMON_1961', 'PET_TURC_1961', ..}, optional) – Algorithm used to compute potential evapotranspiration (PET).

  • ow_evaporation ({'PET_CONSTANT', 'PET_PENMAN_MONTEITH', 'PET_PENMAN_COMBINATION', 'PET_PRIESTLEY_TAYLOR', 'PET_HARGREAVES', 'PET_HARGREAVES_1985', 'PET_FROMMONTHLY', 'PET_DATA', 'PET_HAMON_1961', 'PET_TURC_1961', ..}, optional) – Algorithm used to compute potential evapotranspiration (PET) over open water

Returns

  • hydrograph (application/x-netcdf, application/zip) – A netCDF file containing the outflow hydrographs (in m3/s) for all subbasins specified as gauged in the .rvh file. It reports period-ending time-averaged flows for the preceding time step, as is consistent with most measured stream gauge data (again, the initial flow conditions at the start of the first time step are included). If observed hydrographs are specified, they will be output adjacent to the corresponding modelled hydrograph.

  • storage (application/x-netcdf, application/zip) – A netCDF file describing the total storage of water (in mm) in all water storage compartments for each time step of the simulation. Mass balance errors, cumulative input (precipitation), and output (channel losses) are also included. Note that the precipitation rates in this file are period-ending, i.e., this is the precipitation rate for the time step preceding the time stamp; all water storage variables represent instantaneous reports of the storage at the time stamp indicate.

  • solution (text/plain, application/zip) – solution.rvc file to restart another simulation with the conditions at the end of this simulation.

  • diagnostics (text/plain, application/zip) – Model diagnostic CSV file.

  • rv_config (application/zip) – Model configuration files, including the primary input file (rvi), the parameter input file (rvp), the basin definition file (rvh), the time series input file (rvt), the initial conditions file (rvc). For Ostrich, include the Ostrich calibration config (txt) and templates (tpl).

Diagnostics functions

class raven.processes.ObjectiveFunctionProcess[source]

objective-function Objective-function process based on SpotPy and its 17 objective functions. (v1.0)

This process takes two NETCDF files (one containing variable ‘q_sim’ and the other ‘q_obs’) and computes objective-function metrics between them.

Parameters

  • obs (application/x-netcdf) – Steam flow observation time series

  • sim (application/x-netcdf) – Stream flow simulation time series

  • name (string, optional) – One or multiple objective function name. If None, defaults to all.

Returns

metrics – Returns up to 17 objective function values, depending on the user’s requests. By default all 17 are returned. JSON dictionary format.

Return type

application/json

References