4. Hydrological modelling - HYDROTEL¶

WARNING

xHydro provides tools to execute HYDROTEL, but will not prepare the model itself. This should be done beforehand.

INFO

The HYDROTEL executable can be acquired from this GitHub repository.

xHydro provides a collection of functions designed to facilitate hydrological modelling, focusing on two key models: HYDROTEL and a suite of models emulated by the Raven Hydrological Framework. It is important to note that Raven already possesses an extensive Python library, RavenPy, which enables users to build, calibrate, and execute models. xHydro wraps some of these functions to support multi-model assessments with HYDROTEL, though users seeking advanced functionalities may prefer to use RavenPy directly.

The primary contribution of xHydro to hydrological modelling is thus its support for HYDROTEL, a model that previously lacked a dedicated Python library. However, building a HYDROTEL project is best done using PHYSITEL and the HYDROTEL GUI, both of which are proprietary software. Therefore, for the time being, xHydro is designed to facilitate the execution and modification of an already established HYDROTEL project, rather than assist in building one from scratch.

A similar Notebook to this one, but that covers RavenPy models, is available here.

4.1. Basic information¶

[1]:

from IPython.display import clear_output
import xhydro as xh
import xhydro.modelling as xhm
clear_output(wait=False)

The xHydro modelling framework is based on a model_config dictionary, which is meant to contain all necessary information to execute a given hydrological model. For example, depending on the model, it can store meteorological datasets directly, paths to datasets (netCDF files or other), csv configuration files, parameters, and basically anything that is required to configure and execute an hydrological model.

The list of required inputs for the dictionary can be obtained one of two ways. The first is to look at the hydrological model’s class, such as xhydro.modelling.Hydrotel. The second is to use the xh.modelling.get_hydrological_model_inputs function to get a list of the required keys for a given model, as well as the documentation.

[3]:

help(xhm.get_hydrological_model_inputs)

Help on function get_hydrological_model_inputs in module xhydro.modelling.hydrological_modelling:

get_hydrological_model_inputs(model_name: str, required_only: bool = False) -> tuple[dict, str]
    Get the required inputs for a given hydrological model.

    Parameters
    ----------
    model_name : str
        The name of the hydrological model to use.
        Currently supported models are ["HYDROTEL", "Blended", "GR4JCN", "HBVEC", "HMETS", "HYPR", "Mohyse", "SACSMA"].
    required_only : bool
        If True, only the required inputs will be returned.

    Returns
    -------
    dict
        A dictionary containing the required configuration for the hydrological model.
    str
        The documentation for the hydrological model.

[4]:

# This function can be called to get a list of the keys for a given model, as well as its documentation.
inputs, docs = xhm.get_hydrological_model_inputs("Hydrotel", required_only=False)
inputs

[4]:

{'model_name': 'HYDROTEL',
 'project_dir': str | os.PathLike,
 'project_file': str,
 'executable': str | os.PathLike,
 'project_config': dict | None,
 'simulation_config': dict | None,
 'output_config': dict | None}

[5]:

print(docs)


Class to handle HYDROTEL simulations.

Parameters
----------
project_dir : str or Path
    Path to the project folder.
project_file : str
    Name of the project file (e.g. 'projet.csv').
executable : str or Path
    Command to execute HYDROTEL.
    On Windows, this should be the path to hydrotel.exe.
project_config : dict, optional
    Dictionary of configuration options to overwrite in the project file.
simulation_config : dict, optional
    Dictionary of configuration options to overwrite in the simulation file. See the Notes section for more details.
output_config : dict, optional
    Dictionary of configuration options to overwrite in the output file (output.csv).

Notes
-----
The name of the simulation file must match the name of the 'SIMULATION COURANTE' option in the project file.

This class is designed to handle the execution of HYDROTEL simulations, with the ability to overwrite configuration options,
but it does not handle the creation of the project folder itself. The project folder must be created beforehand.

For more information on how to configure the project, refer to the documentation of HYDROTEL:
https://github.com/INRS-Modelisation-hydrologique/hydrotel

HYDROTEL and Raven vary in terms of required inputs and available functions, but an effort will be made to standardize the outputs as much as possible. Currently, all models include the following three functions:

.run(): Executes the model, reformats the outputs to be compatible with analysis tools in xHydro, and returns the simulated streamflow as a xarray.Dataset.
- The streamflow variable will be named q and will have units of m3 s-1.
- For 1D data (such as hydrometric stations), the corresponding dimension in the dataset will be identified by the cf_role: timeseries_id attribute.
.get_inputs(): Retrieves the meteorological inputs used by the model.
.get_outputs(): Retrieves the simulated outputs from the model.
- Use .get_outputs("q") to obtain the simulated streamflow as a xarray.Dataset.
.standardize_outputs(): Standardizes the outputs to ensure consistency across different models, facilitating comparison and analysis. This function is used by default in the .run() method, but can also be called separately if needed.

4.3. Retrieving additional outputs¶

The output_config allows users to specify which variables to output. It is thus easy to retrieve additional variables by simply updating the configuration and re-running the model.

[22]:

# "Couvert nival" is the snow water equivalent
hm.update_config(output_config={"COUVERT_NIVAL": "1"})
hm.run(overwrite=True, return_streamflow=False)
clear_output(wait=False)

The .get_outputs() function can be used to retrieve any of these variables as a xarray.Dataset.

[23]:

help(hm.get_outputs)

Help on method get_outputs in module xhydro.modelling._hydrotel:

get_outputs(output: str, return_paths: bool = False, **kwargs) -> xr.Dataset | Path | list[Path] method of xhydro.modelling._hydrotel.Hydrotel instance
    Get the outputs of the simulation.

    Parameters
    ----------
    output : str
        "path" to return the output directory.
        Otherwise, the name of the output to retrieve, or "q" for the streamflow.
        This should match the name of the output file without the extension (e.g. "neige" for "neige.nc").
    return_paths : bool
        If True, return the path to the output file(s) instead of the dataset. Default is False.
    \*\*kwargs : dict
        Keyword arguments to pass to :py:func:`xarray.open_dataset`.

    Returns
    -------
    xr.Dataset
        The requested output variable.
    Path
        The path to the output directory if output is set to "path".
    list[Path]
        The path to the output file(s) if return_path is True.

[24]:

files = hm.get_outputs("*", return_paths=True)
files

[24]:

[PosixPath('/tmp/tmpbn030vdz/hydrotel_demo/simulation/simulation/resultat/couvert_nival.nc'),
 PosixPath('/tmp/tmpbn030vdz/hydrotel_demo/simulation/simulation/resultat/debit_aval.nc')]

[25]:

snow = hm.get_outputs("nival")
snow

[25]:

<xarray.Dataset> Size: 791kB
Dimensions:                  (time: 364, unit_id: 495)
Coordinates: (12/14)
  * time                     (time) datetime64[ns] 3kB 1981-01-01 ... 1981-12-30
  * unit_id                  (unit_id) <U3 6kB '1' '2' '3' ... '493' '494' '495'
    dowsub_id                (unit_id) <U3 6kB dask.array<chunksize=(495,), meta=np.ndarray>
    station_id               (unit_id) <U7 14kB dask.array<chunksize=(495,), meta=np.ndarray>
    subbasin_id              (unit_id) <U3 6kB dask.array<chunksize=(495,), meta=np.ndarray>
    lon                      (unit_id) float64 4kB dask.array<chunksize=(495,), meta=np.ndarray>
    ...                       ...
    unit_centroid_latitude   (unit_id) float64 4kB dask.array<chunksize=(495,), meta=np.ndarray>
    drainage_area            (unit_id) float64 4kB dask.array<chunksize=(495,), meta=np.ndarray>
    subbasin_drainage_area   (unit_id) float64 4kB dask.array<chunksize=(495,), meta=np.ndarray>
    unit_drainage_area       (unit_id) float64 4kB dask.array<chunksize=(495,), meta=np.ndarray>
    subbasin_elevation       (unit_id) float64 4kB dask.array<chunksize=(495,), meta=np.ndarray>
    unit_elevation           (unit_id) float64 4kB dask.array<chunksize=(495,), meta=np.ndarray>
Data variables:
    couvert_nival            (time, unit_id) float32 721kB dask.array<chunksize=(364, 495), meta=np.ndarray>
Attributes:
    description:              Variable de sortie simulation Hydrotel
    creation_time:            01-04-2026 12:59:08
    HYDROTEL_version:         4.3.6.0000
    HYDROTEL_config_version:  4.3.1.0000

[26]:

snow["couvert_nival"].isel(unit_id=0).plot()

[26]:

[<matplotlib.lines.Line2D at 0x7f1ef41faf90>]

../_images/notebooks_hydrological_modelling_hydrotel_37_1.png

A few important notes regarding these additional outputs:

There is currently no standardization of the variable names or their units.
In an effort to standardize the outputs across different models, the following aggregation levels have been defined. These are noted in a aggregation_level attribute in the variable’s metadata, and can be used to identify the spatial resolution of the output:
- ComputationalUnit: In HYDROTEL, this corresponds to the Relatively Homogeneous Hydrological Units (RHHUs).
- Subbasin: Following the Raven convention, this corresponds to the immediate drainage area of a river segment, excluding the upstream drainage area.
- DrainageArea: This corresponds to the cumulative drainage area of a river segment.

With one exception which is at the subbasin level (APPORT LATERAL), all additional outputs in HYDROTEL are provided at the computational unit level. The aggregate_outputs function has thus been implemented in xHydro to allow the aggregation of outputs in post-processing, if needed. Note that this function relies on multiple watershed properties which are deduced from the model’s files.

[27]:

help(hm.aggregate_outputs)

Help on method aggregate_outputs in module xhydro.modelling._hydrotel:

aggregate_outputs(
to: Literal['subbasin', 'drainage_area'],
subset: list[str] | None = None,
**kwargs
) -> None method of xhydro.modelling._hydrotel.Hydrotel instance
Aggregate the model outputs to a different spatial unit. See the Notes section for more details.

Parameters
----------
to : {"subbasin", "drainage_area"}
The spatial unit to aggregate to.
subset : list[str] | None
The list of variables to aggregate. If None, all variables will be processed.
The strings should match the names produced by the HYDROTEL model.
\*\*kwargs : dict
Keyword arguments to pass to :py:func:`xarray.open_dataset`.

Returns
-------
None
The aggregated outputs will be saved as new NetCDF files in the output directory, with a name pattern
roughly following what is produced by HYDROTEL (e.g. "variable}_By{aggregation}.nc").
Aggregation will be 'BySubbasin' or 'ByDrainageArea', depending on the 'to' parameter.

Notes
-----
Unlike Raven, HYDROTEL always produces output files at the RHHU level, which is the finest spatial unit in the model.
Therefore, unlike its Raven variant, this method does not need a 'by' parameter to specify the spatial unit of the input files.
Furthermore, this method expects that the 'standardize_outputs' method has been called beforehand to ensure that the output
files are in a consistent format and contain the necessary spatial information for the aggregation.

[28]:

hm.aggregate_outputs(to="drainage_area")

[29]:

snow_agg = hm.get_outputs("nival_ByDrainageArea")
snow_agg

[29]:

<xarray.Dataset> Size: 589kB
Dimensions:        (time: 364, subbasin_id: 196)
Coordinates:
  * time           (time) datetime64[ns] 3kB 1981-01-01 ... 1981-12-30
  * subbasin_id    (subbasin_id) <U3 2kB '1' '2' '3' '4' ... '194' '195' '196'
    dowsub_id      (subbasin_id) <U3 2kB dask.array<chunksize=(196,), meta=np.ndarray>
    station_id     (subbasin_id) <U7 5kB dask.array<chunksize=(196,), meta=np.ndarray>
    lon            (subbasin_id) float64 2kB dask.array<chunksize=(196,), meta=np.ndarray>
    lat            (subbasin_id) float64 2kB dask.array<chunksize=(196,), meta=np.ndarray>
    drainage_area  (subbasin_id) float64 2kB dask.array<chunksize=(196,), meta=np.ndarray>
Data variables:
    couvert_nival  (time, subbasin_id) float64 571kB dask.array<chunksize=(364, 196), meta=np.ndarray>
Attributes:
    description:              Variable de sortie simulation Hydrotel
    creation_time:            01-04-2026 12:59:08
    HYDROTEL_version:         4.3.6.0000
    HYDROTEL_config_version:  4.3.1.0000

4.4. Model calibration¶

WARNING

Only Raven-based models are currently implemented.

4. Hydrological modelling - HYDROTEL¶

4.1. Basic information¶

4.2. Initializing and running a calibrated model¶

4.2.1. Formatting meteorological data¶

4.2.2. Validating the Meteorological Data¶

4.2.3. Executing the model¶

4.3. Retrieving additional outputs¶

4.4. Model calibration¶