kub-event-weather

1. Overview

kub-event-weather is a command-line tool for fetching historical weather and air quality data from the Open-Meteo APIs. It is designed to support event-based simulations such as fire scenarios, where historical atmospheric conditions are needed.

The tool retrieves:

  • Historical weather data from the Open-Meteo Archive API:

    • Temperature, humidity, dew point

    • Wind speed, direction, and gusts

    • Surface pressure, cloud cover

    • Solar radiation (direct, diffuse, DNI)

    • Precipitation

  • Air quality data from the Open-Meteo CAMS API (optional):

    • PM2.5, PM10 background concentrations

    • CO, NO₂, SO₂, O₃ background concentrations

  • Computed data:

    • Pasquill-Gifford atmospheric stability class (A-F)

2. Installation

The tool is included with the ktirio-ub package:

pip install ktirio-ub
# or with uv
uv pip install -e .

3. Usage

3.1. Synopsis

kub-event-weather [OPTIONS]

3.2. Dataset-Aware Mode (Recommended)

Store event data in the standard CEMDB dataset layout:

kub-event-weather \
    --location cemdb/locations/notre_dame/v0.1.0 \
    --event fire-2019-04-15 \
    --lat 48.853 --lon 2.349 \
    --start 2019-04-15 --end 2019-04-16 \
    --tz Europe/Paris

This creates the following structure:

cemdb/locations/notre_dame/v0.1.0/
└── weather/
    └── events/
        └── fire-2019-04-15/
            ├── weather.csv        # Historical weather + stability class
            └── air-quality.csv    # Background air quality data

3.3. Legacy Mode

Output to a specific file path:

kub-event-weather \
    --output data/events/my-event/weather.csv \
    --lat 48.853 --lon 2.349 \
    --start 2019-04-15 --end 2019-04-16

3.4. Notre-Dame Fire Preset

A convenience preset for the Notre-Dame fire event (April 15-16, 2019):

# Dataset-aware mode
kub-event-weather --notre-dame --location cemdb/locations/notre_dame/v0.1.0

# Legacy mode (outputs to data/events/notre-dame/)
kub-event-weather --notre-dame

4. Options

Option Description

--lat FLOAT

Latitude in degrees (required except with --notre-dame)

--lon FLOAT

Longitude in degrees (required except with --notre-dame)

--start DATE

Start date in YYYY-MM-DD format (required except with --notre-dame)

--end DATE

End date in YYYY-MM-DD format (required except with --notre-dame)

--location PATH

Location version root path (e.g., cemdb/locations/notre_dame/v0.1.0)

--event NAME

Event name (e.g., fire-2019-04-15). Required with --location

--output PATH

Legacy: Output CSV path (use --location instead)

--tz TIMEZONE

Timezone (default: auto). Examples: Europe/Paris, UTC

--no-air-quality

Skip fetching air quality data

--notre-dame

Use pre-configured Notre-Dame fire settings (April 15-16, 2019)

-v, --verbose

Enable verbose logging output

5. Output Data

5.1. Weather Data (weather.csv)

Column Unit Description

time

ISO 8601

Timestamp

temperature_2m

°C

Air temperature at 2m height

relative_humidity_2m

%

Relative humidity at 2m height

dew_point_2m

°C

Dew point temperature

surface_pressure

hPa

Surface atmospheric pressure

cloud_cover

%

Total cloud cover

wind_speed_10m

m/s

Wind speed at 10m height

wind_direction_10m

degrees

Wind direction (0-360°)

wind_gusts_10m

m/s

Wind gust speed at 10m height

direct_radiation

W/m²

Direct solar radiation

diffuse_radiation

W/m²

Diffuse solar radiation

direct_normal_irradiance

W/m²

Direct normal irradiance

precipitation

mm

Precipitation amount

stability_class

A-F

Pasquill-Gifford stability class

5.2. Air Quality Data (air-quality.csv)

Column Unit Description

time

ISO 8601

Timestamp

PM2_5_background_ug_m3

µg/m³

PM2.5 background concentration

PM10_background_ug_m3

µg/m³

PM10 background concentration

CO_background_ug_m3

µg/m³

Carbon monoxide background

NO2_background_ug_m3

µg/m³

Nitrogen dioxide background

SO2_background_ug_m3

µg/m³

Sulfur dioxide background

O3_background_ug_m3

µg/m³

Ozone background

6. Atmospheric Stability Classes

The tool computes Pasquill-Gifford stability classes using a simplified Turner method based on wind speed, cloud cover, and time of day:

Class Conditions

A

Very unstable - Light winds, strong daytime solar heating

B

Moderately unstable - Light to moderate winds, moderate daytime heating

C

Slightly unstable - Moderate winds, slight daytime heating

D

Neutral - Strong winds or overcast conditions

E

Slightly stable - Light winds, clear nighttime

F

Moderately stable - Very light winds, clear nighttime

Stability class is important for atmospheric dispersion modeling in fire and pollution scenarios.

7. Python API

The module can also be used programmatically:

from feelpp.ktirio.ub.dataset.sources.events import (
    fetch_event_to_location,
    fetch_event_weather,
    fetch_historical_weather,
    fetch_historical_air_quality,
    fetch_notre_dame_fire_weather,
)

# Fetch event data to dataset location
event_dir = fetch_event_to_location(
    location_root="cemdb/locations/notre_dame/v0.1.0",
    event_name="fire-2019-04-15",
    lat=48.853, lon=2.349,
    start="2019-04-15", end="2019-04-16",
    tz="Europe/Paris",
)
print(f"Event data saved to: {event_dir}")

# Get combined weather + air quality DataFrame
df = fetch_event_weather(
    lat=48.853, lon=2.349,
    start="2019-04-15", end="2019-04-16",
    include_air_quality=True,
    tz="Europe/Paris",
)
print(df.head())

# Notre-Dame convenience function
df = fetch_notre_dame_fire_weather(
    location_root="cemdb/locations/notre_dame/v0.1.0"
)

8. Data Sources

Open-Meteo provides free access for non-commercial use. For commercial applications, please review their licensing terms.

9. See Also