API Reference

TData{D, F}

A container for transformed time series data used in nowcasting models.

Type Parameters

• D: Type for dates/timestamps (e.g., Date, DateTime)
• F: Type for numeric values, automatically promoted from input types

Fields

• ds::Vector{D}: Vector of dates or timestamps corresponding to observations
• y::Vector{F}: Vector of transformed target values (result of applying transformation)
• values::Vector{F}: Vector of original values, converted to common type with y

Constructor

TData(ds, values; transformation)

Create a TData instance by applying a transformation to the input values.

Arguments

• ds: Vector of dates or timestamps
• values: Vector of original numeric values
• transformation: Function to apply element-wise to values to create y

The constructor automatically promotes types using promote_type to ensure y and values have compatible numeric types.

Example

using Dates

dates = [Date(2023, 1, 1), Date(2023, 1, 2), Date(2023, 1, 3)]
raw_values = [10, 20, 30]

# Apply log transformation
tdata = TData(dates, raw_values; transformation = log)

# Apply custom transformation
tdata = TData(dates, raw_values; transformation = x -> (x - mean(raw_values)) / std(raw_values))

Validation

The constructor ensures that ds and values have the same length and throws an ArgumentError if they don't match.

_get_offset(values::Vector{F}) where {F <: Real}

Internal function to compute an offset for transformations to ensure numerical stability.

_inv_boxcox(λ::Real, offset::F, max_values) where {F}

Internal function to compute the inverse Box-Cox transformation with edge case handling.

create_nowcast_data(nowcasts::AbstractMatrix, dates::Vector{Date}; transformation = y -> y)

Create nowcast data structures from a matrix of nowcast scenarios.

Arguments

• nowcasts: A matrix where each column represents one nowcast scenario. The number of rows must match the length of dates.
• dates: A vector of Date objects corresponding to the nowcast time points.
• transformation: A function to apply to the nowcast values (default: identity).

Returns

A vector of NamedTuples, where each NamedTuple represents one nowcast scenario with fields:

• ds: The dates vector
• y: The transformed nowcast values
• values: The original (untransformed) nowcast values

Notes

This method converts the matrix to a vector of columns internally and delegates to the vector method.

Example

# Matrix with 3 time points (rows) and 2 scenarios (columns)
nowcasts = [10.5 9.8; 11.2 10.9; 12.1 11.5]
dates = [Date(2024,1,1), Date(2024,1,2), Date(2024,1,3)]
nowcast_data = create_nowcast_data(nowcasts, dates; transformation = log)
# Returns vector of 2 NamedTuples, each with transformed and original values

create_nowcast_data(nowcasts::AbstractVector, dates::Vector{Date}; transformation = y -> y)

Create nowcast data structures from a vector of nowcast scenarios.

Arguments

• nowcasts: A vector where each element is a vector of nowcast values representing one scenario. All inner vectors must have the same length as dates.
• dates: A vector of Date objects corresponding to the nowcast time points.
• transformation: A function to apply to the nowcast values (default: identity).

Returns

A vector of NamedTuples, where each NamedTuple represents one nowcast scenario with fields:

• ds: The dates vector
• y: The transformed nowcast values
• values: The original (untransformed) nowcast values

Example

# Two nowcast scenarios for 3 dates
nowcasts = [[10.5, 11.2, 12.1], [9.8, 10.9, 11.5]]
dates = [Date(2024,1,1), Date(2024,1,2), Date(2024,1,3)]
nowcast_data = create_nowcast_data(nowcasts, dates; transformation = log)
# Returns vector of 2 NamedTuples, each with transformed and original values

create_transformed_data(ds, values; transformation)

Convenience function to create a TData instance from any iterable inputs of dates/times and values.

forecast(model, forecast_dates, forecast_draws::Int)

Generate forecast samples from a fitted AutoGP model.

Arguments

• model: Fitted AutoGP.GPModel.
• forecast_dates: Vector or range of dates to predict.
• forecast_draws: Number of samples to draw.

Keyword arguments

• inv_transformation: Function applied elementwise to map forecasts back to the original scale (default: identity).
• forecast_n_hmc: If nothing, draw from the current model state. If an Int, run that many HMC parameter steps before each draw (default: nothing).
• verbose: If true, display progress information during forecasting (default: false).

Returns

• A matrix of samples with size (length(forecast_dates), forecast_draws).

forecast_with_nowcasts(base_model, nowcasts, forecast_dates, forecast_draws_per_nowcast;
                      inv_transformation = y -> y, n_mcmc = 0, n_hmc = 0, ess_threshold = 0.0)

Generate forecasts by conditioning on multiple nowcast scenarios.

Arguments

• base_model: Fitted AutoGP.GPModel trained on confirmed (non-nowcast) data.
• nowcasts: Vector of TData scenarios with fields ds, y, and values.
• forecast_dates: Vector or range of dates to predict.
• forecast_draws_per_nowcast: Samples per scenario.

Keyword arguments

• inv_transformation: Function applied elementwise to map forecasts back to the original scale (default: identity).
• n_mcmc: Number of MCMC structure steps after adding each nowcast (default: 0). If > 0, n_hmc must also be > 0.
• n_hmc: Number of HMC parameter steps per MCMC step (default: 0). Can be > 0 even if n_mcmc == 0.
• ess_threshold: Effective sample size threshold for particle resampling, as a fraction of total particles (default: 0.0).
• forecast_n_hmc: Number of HMC steps to run before each forecast draw (default: nothing). If nothing, no HMC steps are taken during forecasting.
• verbose: If true, display progress information during forecasting (default: false).

Returns

• A matrix with size (length(forecast_dates), length(nowcasts) * forecast_draws_per_nowcast).

Notes

• Each scenario is added, optionally refined, forecasted, and then removed to restore the model state.
• n_mcmc == 0 && n_hmc > 0 performs parameter-only updates to the particle ensemble; n_mcmc > 0 && n_hmc > 0 performs full MCMC.
• forecast_n_hmc is independent of n_mcmc and n_hmc and controls HMC steps only during forecasting, not during nowcast incorporation.

If n_mcmc == 0 && n_hmc == 0 && forecast_n_hmc > 0, HMC steps are only taken during forecasting, not during nowcast incorporation.

Example

nowcast_scenarios = [
    (ds = [Date(2024,1,1), Date(2024,1,2)], y = [10.5, 11.2], values = [10.5, 11.2]),
    (ds = [Date(2024,1,1), Date(2024,1,2)], y = [9.8, 10.9], values = [9.8, 10.9]),
]
forecast_dates = Date(2024,1,1):Day(1):Date(2024,1,10)
forecasts = forecast_with_nowcasts(base_model, nowcast_scenarios, forecast_dates, 100)

get_transformations(transform_name::String, values::Vector{F}) where {F <: Real}

Return a tuple of transformation and inverse transformation functions for the specified transformation type.

This function creates appropriate data transformations for Gaussian Process modeling, where the goal is to transform the input data to make it more suitable for modeling (typically more Gaussian-like) and then provide the inverse transformation to convert predictions back to the original scale.

Arguments

• transform_name::String: The name of the transformation to apply. Supported values:
  • "percentage": For data bounded between 0 and 100 (e.g., percentages, rates)
  • "positive": For strictly positive data (uses log transformation)
  • "boxcox": Applies Box-Cox transformation with automatically fitted λ parameter
• values::Vector{F}: The input data values used to fit transformation parameters and determine offset

Returns

A tuple (forward_transform, inverse_transform) where:

• forward_transform: Function that transforms data from original scale to transformed scale
• inverse_transform: Function that transforms data from transformed scale back to original scale

Transformation Details

Percentage Transformation

• Use case: Data bounded between 0 and 100 (percentages, rates)
• Forward: y ↦ logit((y + offset) / 100)
• Inverse: y ↦ max(logistic(y) * 100 - offset, 0)
• Note: Uses logit/logistic to map [0,100] to (-∞,∞) and back

Positive Transformation

• Use case: Strictly positive continuous data
• Forward: y ↦ log(y + offset)
• Inverse: y ↦ max(exp(y) - offset, 0)
• Note: Log transformation for positive data with offset for numerical stability

Box-Cox Transformation

• Use case: General purpose transformation for positive data
• Forward: y ↦ BoxCox_λ(y + offset) where λ is automatically fitted
• Inverse: Custom inverse function handling edge cases for numerical stability
• Note: Automatically determines optimal λ parameter via maximum likelihood

Offset Calculation

An offset is automatically calculated using _get_offet(values):

• If minimum value is 0: offset = (minimum positive value) / 2
• Otherwise: offset = 0
• Purpose: Ensures numerical stability and handles boundary cases

Examples

# Percentage data (0-100 range)
values = [10.5, 25.3, 67.8, 89.2]
forward, inverse = get_transformations("percentage", values)
transformed = forward.(values)
recovered = inverse.(transformed)

# Strictly positive data
values = [1.2, 3.4, 8.9, 15.6]
forward, inverse = get_transformations("positive", values)

# General positive data with automatic Box-Cox fitting
values = [0.1, 0.5, 2.3, 5.7, 12.1]
forward, inverse = get_transformations("boxcox", values)

Throws

• AssertionError: If transform_name is not one of the supported transformation types
• AssertionError: Via _get_offet if values is empty or contains negative values

See Also

• _get_offset: Calculates the offset value for numerical stability
• _inv_boxcox: Handles inverse Box-Cox transformation with edge case handling

make_and_fit_model(data; n_particles=8, smc_data_proportion=0.1, n_mcmc=200, n_hmc=50, kwargs...)

Create and fit a Gaussian Process (GP) model using Sequential Monte Carlo (SMC) sampling.

Arguments

• data: A data structure containing the dataset (data.ds) and the target values (data.y).
• n_particles: The number of particles to use in the SMC sampling (default: 8).
• smc_data_proportion: The proportion of the data to use in each SMC step (default: 0.1).
• n_mcmc: The number of MCMC samples (default: 200).
• n_hmc: The number of HMC samples (default: 50).
• kwargs...: Additional keyword arguments to pass to the AutoGP.fit_smc! function.

Returns

• model: The fitted GP model.