Components

HydroUnits

class hydrobricks.HydroUnits(land_cover_types=None, land_cover_names=None)

Bases: object

Class for the hydro units

create_file(path)

Create a file containing the hydro unit properties. Such a file can be used in the command-line version of hydrobricks.

Parameters:

path (str) – Path of the file to create.

get_ids()

Get the hydro unit ids.

load_from_csv(path, area_unit, column_elevation=None, column_area=None, column_fractions=None, columns_areas=None)

Read hydro units properties from csv file.

Parameters:

• path (str|Path) – Path to the csv file containing hydro units data.

• area_unit (str) – Unit for the area values: “m2” or “km2”

• column_elevation (str) – Column name containing the elevation values in [m] (optional).

• column_area (str) – Column name containing the area values (optional).

• column_fractions (dict) – Column name containing the area fraction values for each land cover (optional).

• columns_areas (dict) – Column name containing the area values for each land cover (optional).

ParameterSet

class hydrobricks.ParameterSet

Bases: object

Class for the parameter sets

add_data_parameter(name, value=None, min_value=None, max_value=None, unit=None)

Add a parameter related to the data.

Parameters:

• name (str) – The name of the parameter.

• value (float/list) – The parameter value.

• min_value (float/list) – Minimum value allowed for the parameter.

• max_value (float/list) – Maximum value allowed for the parameter.

• unit (str) – The unit of the parameter.

property allow_changing

change_range(parameter, min_value, max_value)

Change the value range of a parameter.

Parameters:

• parameter (str) – Name (or alias) of the parameter

• min_value – New minimum value

• max_value – New maximum value

constraints_satisfied() → bool

Check if the constraints between parameters are satisfied.

Return type:

True is constraints are satisfied, False otherwise.

create_file(directory, name, file_type='both')

Create a configuration file containing the parameter values.

Such a file can be used when using the command-line version of hydrobricks. It contains the model parameter values.

Parameters:

• directory (str) – The directory to write the file.

• name (str) – The name of the generated file.

• file_type (file_type) – The type of file to generate: ‘json’, ‘yaml’, or ‘both’.

define_constraint(parameter_1, operator, parameter_2)

Defines a constraint between 2 parameters (e.g., paramA > paramB)

Parameters:

• parameter_1 (str) – The name of the first parameter.

• operator (str) – The operator (e.g. ‘<=’).

• parameter_2 (str) – The name of the second parameter.

Examples

parameter_set.define_constraint(‘paramA’, ‘>=’, ‘paramB’)

define_parameter(component, name, unit=None, aliases=None, min_value=None, max_value=None, default_value=None, mandatory=True)

Define a parameter by setting its properties.

Parameters:

• component (str) – The component (brick) name to which the parameter refer (e.g., snowpack, glacier, surface-runoff).

• name (str) – The name of the parameter in the C++ code of hydrobricks (e.g., degree_day_factor, response_factor).

• unit (str) – The unit of the parameter.

• aliases (list) – Aliases to the parameter name, such as names used in other implementations (e.g., kgl, an). Aliases must be unique.

• min_value (float/list) – Minimum value allowed for the parameter.

• max_value (float/list) – Maximum value allowed for the parameter.

• default_value (float/list) – The parameter default value.

• mandatory (bool) – If the parameter needs to be defined or if it can silently use the default value.

get(name)

Get the value of a parameter by name.

Parameters:

name (str) – The name of the parameter.

Return type:

The parameter value.

get_for_spotpy()

Get the parameters to assess ready to be used in spotpy.

Return type:

A list of the parameters as spotpy objects.

get_model_parameters()

Get the model-only parameters (excluding data-related parameters).

has(name)

Check if a parameter exists.

Parameters:

name (str) – The name of the parameter.

Return type:

True if found, False otherwise.

is_for_forcing(parameter_name)

Check if the parameter relates to forcing data.

Parameters:

parameter_name – The name of the parameter.

Return type:

True if relates to forcing data, False otherwise.

list_constraints()

List the constraints currently defined.

needs_random_forcing()

Check if one of the parameters to assess involves the meteorological data.

Return type:

True if one of the parameters to assess involves the meteorological data.

range_satisfied() → bool

Check if the parameter value ranges are satisfied.

Return type:

True is ranges are satisfied, False otherwise.

remove_constraint(parameter_1, operator, parameter_2)

Removes a constraint between 2 parameters (e.g., paramA > paramB)

Parameters:

• parameter_1 (str) – The name of the first parameter.

• operator (str) – The operator (e.g. ‘<=’).

• parameter_2 (str) – The name of the second parameter.

Examples

parameter_set.remove_constraint(‘paramA’, ‘>=’, ‘paramB’)

set_prior(parameter, prior)

Change the value range of a parameter.

Parameters:

• parameter (str) – Name (or alias) of the parameter

• prior (spotpy.parameter) – The prior distribution (instance of spotpy.parameter)

set_random_values(parameters)

Set the provided parameter to random values.

Parameters:

parameters (list) – The name or alias of the parameters to set to random values. Example: [‘kr’, ‘A’]

Return type:

A dataframe with the assigned parameter values.

set_values(values, check_range=True, allow_adapt=False)

Set the parameter values.

Parameters:

• values (dict) – The values must be provided as a dictionary with the parameter name with the related component or one of its aliases as the key. Example: {‘k’: 32, ‘A’: 300} or {‘slow-reservoir:capacity’: 300}

• check_range (bool) – Check that the parameter value falls into the allowed range.

• allow_adapt (bool) – Allow the parameter values to be adapted to enforce defined constraints (e.g.: min, max).

Forcing

class hydrobricks.Forcing(hydro_units)

Bases: TimeSeries

Class for forcing data

apply_defined_spatialization(parameters, parameters_to_apply=None)

Apply the spatialization operations defined by define_spatialization().

Parameters:

• parameters (ParameterSet) – The parameter object instance.

• parameters_to_apply (list) – A list of parameters to apply. The spatialization will only be applied for the variables related to parameters in this list. If None, all variables are spatialized.

create_file(path, max_compression=False)

Read hydro units properties from csv file.

Parameters:

• path (str) – Path of the file to create.

• max_compression (bool) – Option to allow maximum compression for data in file.

define_spatialization(**kwargs)

Define the spatialization operations.

Parameters:

kwargs – All the parameters needed by the function spatialize() to perform the spatialization for the given forcing variable.

get_total_precipitation()

spatialize(variable, method='constant', ref_elevation=None, gradient=0, gradient_1=0, gradient_2=0, elevation_threshold=None, correction_factor=None)

Spatializes the provided variable to all hydro units using the defined method.

Parameters:

• variable (str) – Name of the variable to spatialize.

• method (str) –

  Name of the method to use. Can be: * constant: the same value will be used * additive_elevation_gradient: use of an additive elevation gradient that

  is either constant or changes for every month. Parameters: ‘ref_elevation’, ‘gradient’.

  • multiplicative_elevation_gradient: use of a multiplicative elevation gradient that is either constant or changes for every month. Parameters: ‘ref_elevation’, ‘gradient’.

  • multiplicative_elevation_threshold_gradients: same as multiplicative_elevation_gradient, but with an elevation threshold with a gradient below and a gradient above. Parameters: ‘ref_elevation’, ‘gradient’, ‘gradient_2’, ‘elevation_threshold’

• ref_elevation (float) – Reference elevation. For method(s): ‘elevation_gradient’

• gradient (float/list) – Gradient of the variable to apply per 100m (e.g., °C/100m). Can be a unique value or a list providing a value for every month. For method(s): ‘elevation_gradient’, ‘elevation_multi_gradients’

• gradient_1 (float/list) – Same as parameter ‘gradient’

• gradient_2 (float/list) – Gradient of the variable to apply per 100m (e.g., °C/100m) for the units above the elevation threshold defined by ‘elevation_threshold’. For method(s): ‘elevation_multi_gradients’

• elevation_threshold (int/float) – Threshold elevation to switch from gradient to gradient_2

• correction_factor (float) – Correction factor to apply to the precipitation data before spatialization

spatialize_pet(ref_elevation=None, gradient=0)

Spatializes the PET using a gradient that is either constant or changes for every month.

Parameters:

• ref_elevation (float) – Elevation of the reference station.

• gradient (float/list) – Gradient [mm/100m] to compute the PET for every hydro unit. Can be a unique value or a list providing a value for every month.

spatialize_precipitation(ref_elevation, gradient=None, gradient_1=None, gradient_2=None, elevation_threshold=None, correction_factor=None)

Spatializes the precipitation using a single gradient for the full elevation range or a two-gradients approach with an elevation threshold.

Parameters:

• ref_elevation (float) – Elevation of the reference station.

• gradient (float) – Precipitation gradient (ratio) per 100 m of altitude.

• gradient_1 (float) – Same as parameter ‘gradient’

• gradient_2 (float) – Precipitation gradient (ratio) per 100 m of altitude for the units above the threshold elevation (optional).

• elevation_threshold (float) – Threshold to switch from gradient 1 to gradient 2 (optional).

• correction_factor (float) – Correction factor to apply to the precipitation data before spatialization

spatialize_temperature(ref_elevation, lapse)

Spatializes the temperature using a temperature lapse that is either constant or changes for every month.

Parameters:

• ref_elevation (float) – Elevation of the reference station.

• lapse (float/list) – Temperature lapse [°C/100m] to compute the temperature for every hydro unit. Can be a unique value or a list providing a value for every month.

Observations

class hydrobricks.Observations

Bases: TimeSeries

Class for forcing data