Why this vignette?

The main modelling decision in mcgf is the covariance structure. The package separates it into:

1. a symmetric base model, and
2. an optional Lagrangian component for directional space-time asymmetry.

The combined model is

\[ C(\mathbf h,u) = (1-\lambda)C_{\mathrm{base}}(\mathbf h,u) + \lambda C_{\mathrm{Lagr}}(\mathbf h,u). \]

This vignette shows how the available functions fit together.

library(mcgf)

h1 <- array(
    c(0, -1, 1, 0),
    dim = c(2, 2, 3)
)
h2 <- array(
    c(0, -2, 2, 0),
    dim = c(2, 2, 3)
)
h <- sqrt(h1^2 + h2^2)
u <- array(
    rep(0:2, each = 4),
    dim = c(2, 2, 3)
)

Pure spatial and temporal kernels

cor_exp() implements the powered exponential correlation.

c_exp <- cor_exp(
    h,
    c = 0.2,
    gamma = 0.5,
    nugget = 0.05,
    is.dist = TRUE
)

cor_cauchy() implements the Cauchy correlation and is commonly used for the temporal component.

c_time <- cor_cauchy(
    u,
    a = 0.4,
    alpha = 0.5
)

Separable covariance

A separable model multiplies the spatial and temporal components:

par_s <- list(
    nugget = 0.05,
    c = 0.2,
    gamma = 0.5
)

par_t <- list(
    a = 0.4,
    alpha = 0.5
)

c_sep <- cor_sep(
    spatial = "exp",
    temporal = "cauchy",
    par_s = par_s,
    par_t = par_t,
    h = h,
    u = u
)

This is a good baseline because it is simple and easy to interpret.

Fully symmetric Gneiting model

cor_fs() introduces the space-time interaction parameter beta (Gneiting 2002).

c_fs <- cor_fs(
    nugget = 0.05,
    c = 0.2,
    gamma = 0.5,
    a = 0.4,
    alpha = 0.5,
    beta = 0.5,
    h = h,
    u = u
)

When beta = 0, this formulation reduces to the corresponding separable model.

Use the fully symmetric model when the strength or scale of spatial dependence changes with temporal lag but you do not yet need directional asymmetry.

Lagrangian covariance functions

The Lagrangian functions use signed distances and a prevailing velocity \(\mathbf v=(v_1,v_2)^\top\).

c_tri <- cor_lagr_tri(
    v1 = 2,
    v2 = 1,
    k = 3,
    h1 = h1,
    h2 = h2,
    u = u
)

c_askey <- cor_lagr_askey(
    v1 = 2,
    v2 = 1,
    k = 3,
    h1 = h1,
    h2 = h2,
    u = u
)

c_lagr_exp <- cor_lagr_exp(
    v1 = 2,
    v2 = 1,
    k = 3,
    h1 = h1,
    h2 = h2,
    u = u
)

Combine the base and Lagrangian terms

cor_stat() constructs the general stationary model.

par_base_fs <- list(
    nugget = 0.05,
    c = 0.2,
    gamma = 0.5,
    a = 0.4,
    alpha = 0.5,
    beta = 0.3
)

par_lagr <- list(
    v1 = 2,
    v2 = 1,
    k = 3
)

c_stat <- cor_stat(
    base = "fs",
    lagrangian = "lagr_exp",
    par_base = par_base_fs,
    par_lagr = par_lagr,
    lambda = 0.2,
    h = h,
    h1 = h1,
    h2 = h2,
    u = u
)

A practical model-selection sequence

For a new dataset, the following progression is usually easiest to diagnose:

1. Fit a separable model (model = "sep").
2. Fit a fully symmetric model (model = "fs").
3. Compare their errors and fitted correlations.
4. Inspect empirical lagged cross-correlations for directional asymmetry.
5. If asymmetry is scientifically meaningful, fit a Lagrangian component with fit_lagr().
6. For known atmospheric or operating regimes, move to mcgf_rs() and allow selected parameters to vary by regime.

The Lagrangian regime-switching framework is used for short-term wind forecasting in Jia and Sezer (2025).

Parameter interpretation

References