vem_fit: Fit a VEM Smooth Model

In fda.vi: Functional Data Analysis using Variational Inference

Fit a VEM Smooth Model

Description

Fits one or more functional curves using Bayesian basis function selection via the Variational EM algorithm, with an Ornstein-Uhlenbeck within-curve correlation structure. Internally calls vem_smooth to run the VEM algorithm.

If a single value is provided for K, the model is fitted using that fixed number of basis functions. If a vector of candidate values is supplied, the function tune_vem_by_gcv is called to automatically select the optimal K based on the GCV criterion. The resulting fitted object provides methods for plot, predict, coef, and summary via the corresponding S3 methods plot.vem_fit, predict.vem_fit, coef.vem_fit, and summary.vem_fit.

Usage

vem_fit(
  y,
  Xt,
  K = NULL,
  basis_type = c("cubic_bspline", "fourier"),
  selection_metric = c("mean", "per_curve"),
  threshold = 0.5,
  center = FALSE,
  scale = FALSE,
  period = NULL,
  initial_values_fn = NULL,
  lambda_1 = NULL,
  lambda_2 = NULL,
  delta_1 = NULL,
  delta_2 = NULL,
  ...
)

Arguments

y	Named list of numeric vectors, one per curve.
Xt	Numeric vector of time points, common across all curves.
K	Integer or integer vector of candidate basis sizes. If a single value, fits directly at that K. If a vector, selects best K via GCV. If NULL, defaults to c(10, 15, 20, 30) for B-splines and Fourier.
basis_type	Character. One of "cubic_bspline" (default), or "fourier".
selection_metric	Character. "mean" selects a single global K minimizing mean GCV across curves. "per_curve" selects the best K independently for each curve, returning a composite fit. Only relevant when K is a vector. Default "mean".
threshold	Numeric in (0,1). Posterior inclusion probability (PIP) threshold for active basis functions in GCV calculation. Default 0.5.
center	Logical. If TRUE, subtract each curve's mean before fitting. If TRUE, the function automatically centralizes the curves before model fitting. Default FALSE.
scale	Logical. If TRUE, the function automatically standardizes the curves before model fitting, by dividing each curve by its standard deviation. Predictions are automatically back-transformed. Default FALSE.
period	Numeric. Period for Fourier bases. Defaults to the domain range diff(range(Xt)) if NULL.
initial_values_fn	Function with signature function(K, m) returning an initial_values list for vem_smooth. If NULL, an empirical initialization based on a dense regression spline fit is used.
lambda_1, lambda_2	Positive scalars. Inverse-Gamma prior hyperparameters for \tau^2. Defaults: lambda_1 = 0.001, lambda_2 = 0.001.
delta_1, delta_2	Positive scalars. Inverse-Gamma prior hyperparameters for \sigma^2. Defaults: delta_1 = 10, delta_2 = 0.09.
...	Additional arguments passed to vem_smooth, such as maxIter, convergence_threshold, and mu_ki.

Value

An object of class "vem_fit" containing:

model

The fitted vem_smooth object (global fit), or a named list of per-curve model objects (composite fit).

selected_K

Integer vector of length m. The K used for each curve.

best_K

The single selected K (global fit), or a vector (composite fit).

tuning

Output of tune_vem_by_gcv, including the full GCV matrix and all candidate fits. NULL if a single K was supplied.

scaling_params

List with means and sds used for standardization. Used by predict.vem_fit and plot.vem_fit to back-transform predictions.

data_orig

The input curves in their original scales.

basis_type, is_composite, Xt, call

Metadata stored for use by S3 methods.

References

da Cruz, A. C., de Souza, C. P. E., & Sousa, P. H. T. O. (2024). Fast Bayesian basis selection for functional data representation with correlated errors. arXiv:2405.20758. https://arxiv.org/abs/2405.20758

See Also

vem_smooth, plot.vem_fit, predict.vem_fit, coef.vem_fit, summary.vem_fit

Examples

  data(toy_curves)

  fit <- vem_fit(
    y    = toy_curves$y,
    Xt   = toy_curves$Xt,
    K    = 8
  )

  summary(fit)
  plot(fit, curve_idx = 1)
  coef(fit)
  predict(fit)

  # GCV tuning over a grid of K values
  fit_gcv <- vem_fit(
    y    = toy_curves$y,
    Xt   = toy_curves$Xt,
    K    = c(6, 8, 10)
  )
  fit_gcv$best_K

fda.vi documentation built on June 20, 2026, 5:06 p.m.