.. _data_portfolio:

Data Portfolio
==============

HydroMet provides extreme precipitation from the Climate DT model experiments using three data files.
The Kostradamus parameter file (netCDF) contains the Intensity Annual Maxima Series (IAMS) and the parameters of the Generalized 
Extreme Value (GEV) distribution *xi*, *alpha*, *theta*, *eta* and *beta*.
The Depth-Duration-Frequency (DDF) file (netCDF) contains the DDFs derived from the GEV for different return times and durations.
Finally, the event catalogue (csv) lists all extreme events detected in the experiment, along with their characteristics.
For details on how these files are generated, see :ref:`technical_description`.

Available datasets
------------------

HydroMet data is available for three Climate DT models across historical
and projection (SSP3-7.0) periods. All datasets cover Europe at 5 km resolution.

.. list-table::
   :widths: 25 25 25
   :header-rows: 1

   * - Model
     - Historical (1990–2014)
     - Projection (2015–2049)
   * - IFS-NEMO
     - Available
     - Available
   * - IFS-FESOM
     - Available
     - Available
   * - ICON
     - Available
     - Not included in this release

Extreme value distribution and DDF
----------------------------------

The KO file contains the statistical parameters fitted to the model
precipitation data, along with the underlying IAMS values from which
they are derived. These parameters describe the GEV distribution at
each grid cell and duration, and can be used to compute return levels
for return periods beyond those explicitly provided in the DDF file.

The netCDF files describing the GEV distribution have the format
``YYYY_MM_DD_T00_00_to_YYYY_MM_DD_T00_00_KO_params.nc``.
They contain the IAMS values that show the highest rainfall for a specific duration in each year and parameters describing the 
GEV according to Koutsoyiannis et al. (1998) :cite:`koutsoyiannis_mathematical_1998`.

- *xi*: location parameter
- *alpha*: scale parameter
- *theta*: first Koutsoyiannis-Parameter
- *eta*: second Koutsoyiannis-Parameter
- *beta*: balancing parameter

.. list-table::
  :width: 100%
  :widths: 25 25
  :header-rows: 1

  * - **KO file**
    -
  * - Coordinates
    - lat, lon, time, durations
  * - Spatial Resolution and Coverage
    - 5 km / Europe
  * - Data Variables
    - xi, alpha, theta, eta, beta, iams

The DDF files contain the return period and duration frequency information
derived from the GEV parameters. They allow for determining the expected
rainfall depth for a particular duration and return period.

The DDF files have the format
``YYYY_MM_DD_T00_00_to_YYYY_MM_DD_T00_00_DDF.nc`` and are derived from
the GEV distribution for a range of predefined return periods
(1, 2, 3, 5, 10, 20, 30, 50, 100 years).

.. list-table::
  :width: 100%
  :widths: 25 25
  :header-rows: 1
  
  * - **DDF file**
    -
  * - Coordinates
    - lat, lon, return_time, durations
  * - Spatial Resolution and Coverage
    - 5 km / Europe
  * - Data Variables
    - DDF

Extreme event catalog
---------------------

Building on the parameters and the DDF, HydroMet's main output is an event catalogue that tracks all extreme precipitation events
in the observed region. Only events that pass the threshold of a 5-year return period are considered.
The process also includes a filtering of overlapping objects, which selects the object with the highest extreme value.
The data is presented in CSV format, listing the events with their characteristics:

- Object_ID: Code for the object the event was selected from, comprised of end date in numerical form, duration window in hours, and a running number.
- Event_ID: Code for the event, comprised of return period, selection parameter and running number.
- Start_Time: Start date of event.
- End_Time: End date of event.
- Duration: Duration of event [hours].
- Area: Number of pixels included within event [in 25 km²].
- RRmean: Mean precipitation rate within event [mm].
- Tmean_KOSTRA: Mean return period of the event [years].
- Eta_KOSTRA: Extremity of event [dimensionless].
- RRmax: Maximum precipitation within the event [mm].
- RR_Tmax: Precipitation rate with the maximum return period [mm].
- Tmax_KOSTRA: Maximum return period within the event [years].
- x_center: Pixel number on x-axis of the event centre.
- y_center: Pixel number on y-axis of the event centre.
- lon_center: Longitude of the event centre.
- lat_center: Latitude of the event centre.
- x_RRmax: Pixel number on the x-axis of the maximum precipitation within the event.
- y_RRmax: Pixel number on the y-axis of the maximum precipitation within the event.
- lon_RRmax: Longitude of the maximum precipitation within the event.
- lat_RRmax: Latitude of the maximum precipitation within the event.
- MPP_flag: Flag indicating a data anomaly. Set to 1 when the Maximum Pixel Precipitation (MPP) threshold is exceeded.