.. _hydroland_examples:

Examples
========

This page describes typical applications of HydroLand and will point to example
material for accessing and visualising the data once it is available on this
website.

Typical applications
--------------------

* **Hydrological dryness screening:** use the HydroLand aridity indicator and
  soil moisture deficit products to identify historically dry regions and assess
  projected changes under SSP scenarios.
* **Flood risk assessment:** apply the ``p90``/``p95``/``p99`` discharge
  indicator products to identify high-flow event frequencies, durations, and
  intensities at the basin scale.
* **Drought monitoring:** use ``p5``/``p10`` discharge thresholds to
  characterise low-flow periods and their persistence across historical and
  projection periods.
* **Climate adaptation planning:** use HydroLand indicators to compare
  hydrological dryness, flood, and drought conditions across historical and
  projection periods.

Hydrological variables behind the indicators
--------------------------------------------

The indicators are derived from HydroLand hydrological variables and forcings.
These include routed river discharge from mRM (``Qrouted``), total runoff from
mHM (``Q``), potential evapotranspiration (PET), and soil moisture
(``SWC_L01``, ``SWC_L02``, ``SWC_L03``). These fields can help users interpret
the hydrological processes behind changes in the indicator products.

Data access
-----------

HydroLand output is published on the DestinE Data Lake under the collection
identifier ``EO.UFZ.DAT.HYDROLAND``. Different model experiments appear as
separate items, so users can identify the experiment, period, and realization
they need and open the corresponding files directly.

Global **IFS-NEMO** HydroLand mHM and mRM model output is organised for the
historical period (1990–2014) and the climate projection period (2015–2049) in
two product families:

* **mHM flux and state files**, containing soil water content (``SWC_L01``,
  ``SWC_L02``, ``SWC_L03``), actual evapotranspiration (``aET``), and total
  runoff (``Q``);
* **mRM routing files**, containing routed river discharge (``Qrouted``).

These products carry the main STAC properties ``model``, ``experiment``,
``generation``, ``activity``, and ``realization``, together with the global
attribute ``application = "HydroLand"`` inherited from the driving climate
forcing.

Data Lake access and STAC metadata conventions are documented in the
`DestinE Data Lake documentation <https://destine-data-lake-docs.data.destination-earth.eu/en/latest/index.html>`_.

Notebook examples
-----------------

The following `example notebook <https://github.com/destination-earth-digital-twins/destine-climate-dt-use-cases/blob/main/HDA-REST-quick-start-ufz-and-use.ipynb>`_
demonstrates data retrieval and simple plotting of HydroLand data. Additional examples will follow.