DESCRIPTION OF RHITA OUTPUT FOLDERS
==============================

Collection of extreme events organized by hazard type.

ROOT FOLDER STRUCTURE
---------------------
.
├── coldspell/                  # Cold spell events
│   ├── catalogue.csv
│   ├── events_3D/
│   └── events_tracking/
│
├── heatwave/                   # Heatwave events
│   ├── catalogue.csv
│   ├── events_3D/
│   └── events_tracking/
│
└── [other_hazard_types]/       # Additional hazard categories
    ├── catalogue.csv
    ├── events_3D/
    └── events_tracking/

HAZARD-TYPE FOLDER STRUCTURE
----------------------------
Each hazard type folder (e.g., heatwave/) contains:
.
├── catalogue.csv               # Master catalogue for this hazard
├── events_3D/                  # 3D event data (Zarr format)
└── events_tracking/            # Daily tracking metrics (CSV)

FILE DESCRIPTIONS (per hazard type)
-----------------------------------

1. catalogue.csv
----------------
Central registry of all events for this hazard type with columns:
- Id: Unique identifier (format: YYYYMMDD-YYYYMMDD_NNN)
- Date: First day of occurrence (YYYY-MM-DD)
- Duration: Event length in days
- Countries: Affected countries as string arrays (['A' 'B'])
- Volume: Total spatial extent in km²
- Mean area: Daily average area in km²
- Max area: Maximum daily area in km²
- Mean severity: Average intensity metric (°C for temperature events)
- Max severity: Peak intensity metric (°C for temperature events)

2. events_3D/
-------------
Contains Zarr format files for each event:
- Filename pattern: <event_id>.zarr
- Contains 3D spatial-temporal data (latitude × longitude × time)

3. events_tracking/
-------------------
Contains daily CSV tracking files for each event:
- Filename pattern: <event_id>.csv
- Columns in each CSV:
  * centroid_lat, centroid_lon: Geographic center coordinates
  * date: Observation timestamp (YYYY-MM-DDTHH-MM-SS)
  * area: Daily spatial extent in km²
  * severity_mean, severity_max: Intensity metrics
  * timestamp: Day index (0 = first day)

DATA RELATIONSHIPS
------------------
For each hazard type:
- All files are linked by the event Id from catalogue.csv
- For any event in catalogue.csv:
  - 3D data exists in events_3D/<Id>.zarr
  - Tracking data exists in events_tracking/<Id>.csv

USAGE EXAMPLE
-------------
Python workflow for heatwaves:

import pandas as pd
import xarray as xr

# Load metadata
catalogue = pd.read_csv("heatwave/catalogue.csv")

# Access specific event
event = catalogue[catalogue["Id"] == "20230610-20230612_003"].iloc[0]

# Load 3D data
ds = xr.open_zarr(f"heatwave/events_3D/{event['Id']}.zarr")

# Load tracking data
tracking = pd.read_csv(f"heatwave/events_tracking/{event['Id']}.csv")