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 forecasts using the fitted AutoGP model.

Arguments

• model: The fitted GP model.
• forecast_dates: A vector of dates for which to generate forecasts.
• forecast_draws: The number of forecast samples to draw (default: 2000).

Returns

• A matrix of forecast samples, where each column corresponds to a sample for the respective date.

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 incorporating uncertainty from nowcast data by updating a base GP model with each nowcast scenario.

Arguments

• base_model: A fitted GP model representing the baseline model (trained on historical data without nowcast period).
• nowcasts: A vector of nowcast data objects, each a NamedTuple with fields ds (dates), y (transformed values), and values (original values).
• forecast_dates: A vector or range of dates for which to generate forecasts.
• forecast_draws_per_nowcast: The number of forecast samples to draw per nowcast scenario.
• inv_transformation: A function to apply inverse transformation to forecasts (default: identity).
• n_mcmc: Number of MCMC structure steps for model refinement after adding nowcast data (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 for parameter-only updates.
• ess_threshold: Effective Sample Size threshold for particle resampling, as a fraction of total particles (default: 0.0, meaning don't resample).

Returns

A matrix with dimensions (length(forecast_dates), length(nowcasts) * forecast_draws_per_nowcast). Each set of forecast_draws_per_nowcast columns represents forecasts for one nowcast scenario, concatenated horizontally across all scenarios.

Notes

• The base_model should be fitted on historical data that does not temporally overlap with the nowcast period
• Each nowcast represents a different realization of the uncertain nowcast values
• Setting n_mcmc = 0, n_hmc > 0 performs only parameter updates without structure changes
• Setting both n_mcmc > 0, n_hmc > 0 performs full MCMC including structure updates
• The function asserts that nowcasts is non-empty and validates MCMC parameter combinations

Example

# Assume base_model is fitted on historical data
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]),
    # ... more nowcast scenarios
]
forecast_dates = Date(2024,1,1):Day(1):Date(2024,1,10) # Can overlap with nowcast dates for predictive sampling as well as forecasting
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.