API Reference

Public API

TemporalDisaggregations.disaggregate Function

disaggregate(method, aggregate_values, interval_start, interval_end;
             loss_norm=:L2, output_period=Month(1), output_start=nothing,
             output_end=nothing, weights=nothing)

Reconstruct an instantaneous time series from interval-averaged observations.

Arguments

• method::DisaggregationMethod: Algorithm configuration. One of:

  • Spline(; smoothness=1e-1, n_knots, penalty_order, tension)

  • Sinusoid(; smoothness_interannual)

  • GP(; kernel, obs_noise, n_quad)

• aggregate_values: Vector of n observed averages over each interval.

• interval_start, interval_end: Interval boundaries as Date/DateTime.

• loss_norm::Symbol = :L2: :L2 or :L1 (robust to outliers via IRLS).

• output_period::Dates.Period = Month(1): Output grid spacing.

• output_start: Grid anchor Date or DateTime (default nothing).

• output_end: Last date of the output grid as Date or DateTime. Defaults to the end of the data domain.

• weights: Optional vector of n positive per-observation weights (e.g. 1 ./ σ²). nothing (default) uses uniform weights. For :L1 loss, these are multiplied element-wise with the IRLS weights at each iteration.

Returns

DimStack with :signal and :std layers indexed by Ti(dates). For all methods, :std is the spatially-varying sandwich standard deviation: std(t*) = σ̂ · sqrt(q(t*)), where σ̂ is the weighted residual RMS of predicted vs. observed interval averages and q(t*) is a dimensionless coverage factor that is smaller where observations are dense and larger where they are sparse.

Examples

result = disaggregate(Spline(smoothness=1e-3), y, t1, t2)
result = disaggregate(GP(obs_noise=4.0), y, t1, t2; loss_norm=:L1)
result = disaggregate(Sinusoid(), y, t1, t2; output_period=Day(1))
result = disaggregate(Spline(), y, t1, t2; output_end=Date(2020, 6, 1))
result = disaggregate(Spline(), y, t1, t2; weights = 1 ./ σ²_obs)

source

Missing docstring.

Missing docstring for yeardecimal. Check Documenter's build log for details.

TemporalDisaggregations.DisaggregationMethod Type

DisaggregationMethod

Abstract supertype for temporal disaggregation algorithms. Subtypes hold algorithm-specific parameters with sensible defaults.

source

TemporalDisaggregations.Spline Type

Spline(; smoothness=1e-3, n_knots=nothing, penalty_order=3, tension=0.0)

Quartic B-spline antiderivative fit with P-spline regularization.

Models the antiderivative F(t) as a B-spline so that F(t2ᵢ) − F(t1ᵢ) equals the observed area for each interval; the instantaneous signal is x(t) = F′(t).

The :std layer in the returned DimStack is a spatially-varying sandwich standard deviation: lower where observations are dense, higher where they are sparse.

Keywords

• smoothness::Float64 = 1e-1: Regularization strength λ (larger = smoother).

• n_knots::Union{Int,Nothing} = nothing: Number of knots (nothing = auto monthly, 0 = dense).

• penalty_order::Int = 3: Order of the difference penalty.

• tension::Float64 = 0.0: Tension penalty strength (0 = standard P-spline).

source

TemporalDisaggregations.Sinusoid Type

Sinusoid(; smoothness_interannual=1e-2)

Parametric model: mean + trend + per-year anomalies + annual sinusoid. All interval integrals are solved analytically (no quadrature) — the fastest method.

The :std layer in the returned DimStack is a spatially-varying sandwich standard deviation: lower where observations are dense, higher where they are sparse.

Keywords

• smoothness_interannual::Float64 = 1e-2: Ridge penalty on inter-annual anomalies γ.

source

TemporalDisaggregations.GP Type

GP(; kernel=with_lengthscale(Matern52Kernel(), 1/6), obs_noise=1.0, n_quad=5)

Sparse inducing-point Gaussian Process (DTC approximation) on a monthly grid. Supports arbitrary KernelFunctions.jl kernels (sums, products, periodic, etc.).

The :std layer in the returned DimStack is a spatially-varying sandwich standard deviation: lower where observations are dense, higher where they are sparse.

Keywords

• kernel: Any KernelFunctions.jl kernel. Default: Matérn-5/2 with 2-month lengthscale.

• obs_noise::Float64 = 1.0: Observation noise variance σ² in the same units as y². Controls the GP posterior smoothness: smaller values → tighter fit to observations.

• n_quad::Int = 5: Gauss-Legendre quadrature points per interval.

source

TemporalDisaggregations.interval_average Function

interval_average(result, t1, t2) → Vector{Float64}

Compute the time-average of a disaggregated signal over each observation interval [t1[i], t2[i]] using trapezoidal integration on the high-resolution output grid.

Arguments

• result: return value of disaggregate (has .signal field with a :Ti dimension)

• t1, t2: vectors of interval start/end times (DateTime or any type accepted by DateFormats.yeardecimal)

Returns

Vector{Float64} of length length(t1), each entry being the mean signal value over the corresponding interval. Intervals that fall entirely outside the output grid are filled with the nearest boundary value.

Author

Alex S. Gardner, JPL, Caltech.

source