Weather Sampling

This guide explains how to align raw weather time steps with model requirements.

Why Sampling?

A model often needs weather at a different temporal scale than the source data. Examples:

• source meteo is hourly, model step is 3 hours
• source meteo is sub-hourly, model step is daily
• a simulation needs both rolling and calendar-based aggregates

The sampling API makes these choices explicit and testable.

Sampling Workflow

1. define the source weather table
2. prepare a sampler object (with optional caching)
3. choose a window specification
4. sample one step or materialize full sampled tables

1. Create a Small, Predictable Weather Series

For this example we'll use simple values so aggregation effects are easy to verify. We make 48 hourly rows (two days) with monotonic T:

using PlantMeteo
using Dates
using Statistics

base = DateTime(2025, 1, 1)
meteo = Weather([
    Atmosphere(
        date = base + Hour(i),
        duration = Hour(1),
        T = 10.0 + i,
        Wind = 1.0,
        Rh = 0.50 + 0.005 * i,
        P = 100.0,
        Ri_SW_f = 100.0 + 10.0 * i
    )
    for i in 0:47
])

meteo

2. Prepare Sampler State

We can normalize transforms and enable query-level memoization with prepare_weather_sampler. This is optional but can speed up repeated calls with the same windows. This is done so that repeated identical calls can return cached objects (lazy=true).

prepared = prepare_weather_sampler(meteo)  # lazy cache enabled by default
typeof(prepared)

PreparedWeather{TimeStepTable{Atmosphere{(:date, :duration, :T, :Wind, :P, :Rh, :Precipitations, :Cₐ, :e, :eₛ, :VPD, :ρ, :λ, :γ, :ε, :Δ, :clearness, :Ri_SW_f, :Ri_PAR_f, :Ri_NIR_f, :Ri_TIR_f, :Ri_custom_f), Tuple{DateTime, Hour, Vararg{Float64, 20}}}}, Vector{MeteoTransform}, Dict{Tuple{Int64, UInt64, UInt64}, Any}, Dict{UInt64, Any}}

3. Rolling Window Sampling

We can then aggregate over a trailing window in source-step units using sample_weather, which returns one aggregated Atmosphere.

window2 = RollingWindow(2.0)
row3 = sample_weather(prepared, 3; window = window2)
row3_cached = sample_weather(prepared, 3; window = window2)

(row3.T, row3.Tmin, row3.Tmax, row3_cached === row3)

(11.5, 11.0, 12.0, true)

sample_weather provides default transforms for common variables (i.e. the ones in Atmosphere), but you can override them with custom rules (see next section).

4. Override Variable-wise Aggregation Rules

We can match aggregation logic to model semantics by overriding variable-wise aggregation rules. Custom transforms are normalized and applied for this call.

custom = (
    T = MeanWeighted(),
    Tmax = (source = :T, reducer = MaxReducer()),
    Tsum = (source = :T, reducer = SumReducer())
)

row_custom = sample_weather(prepared, 3; window = window2, transforms = custom)
(row_custom.T, row_custom.Tmax, row_custom.Tsum)

(11.5, 12.0, 23.0)

5. Calendar Window Sampling

Sometimes model logic is tied to civil periods (day/week/month) rather than fixed trailing windows. In this case, we can use CalendarWindow to aggregate all source steps that fall within the same period. This is useful for e.g. daily models that need to aggregate all hourly steps that fall within the same day, regardless of how many there are or where they fall in the source data. For example if you need the average temperature for the day, you can use a CalendarWindow anchored to the current period:

window_day = CalendarWindow(:day)
day_sample = sample_weather(prepared, 5; window = window_day)
(day_sample.T, day_sample.Tmin, day_sample.Tmax, day_sample.duration)

(21.5, 10.0, 33.0, Millisecond(86400000))

We sample the fifth hour of the series, which falls on the first day. The sampled T is the average of the 24 hourly steps that fall within that day, which matches our expectation for a daily aggregation:

mean(meteo[i].T for i in 1:24)

21.5

The result would be the same for any hour from 1 to 24, since they all fall in the same day:

day_sample2 = sample_weather(prepared, 20; window = window_day)
day_sample2.T == day_sample.T

true

The aggregated results are cached, so repeated calls with the same window and query step will return the same values, and it means that performance will be ensured for long simulation loops with repeated calls:

day_sample_cached = sample_weather(prepared, 6; window = window_day)
day_sample_cached.T === day_sample.T

true

The returned Atmosphere is different though, since the date (and sometimes duration) are different for each query step, even if the aggregated values are the same:

day_sample.date, day_sample_cached.date, day_sample2.date

(DateTime("2025-01-01T04:00:00"), DateTime("2025-01-01T05:00:00"), DateTime("2025-01-01T19:00:00"))

Note that CalendarWindow expects a date::DateTime column in the weather. By default, it checks for completeness of the period, but you can use completeness = :allow_partial to authorize incomplete periods. This is also faster since it doesn't have to perform checks.

6. Precompute for Simulation Loops

When running long simulations, you can precompute all sampled weather tables upfront rather than sampling on-demand at each step. This trades a one-time preprocessing cost for faster lookups during the simulation loop. The materialize_weather function returns one sampled table per requested sampling window, allowing efficient access throughout your simulation.

windows = [window2, window_day]
tables = materialize_weather(prepared; windows = windows)

(length(tables), length(tables[window2]), tables[window2][3].T ≈ row3.T)

(2, 48, true)

This is typically the best approach when you perform many simulations with the same weather, e.g. for model calibration, sensitivity analysis, or system optimization.