generic: Generic precision matrix operator

In ngme2: Linear Latent Non-Gaussian Models with Flexible Distributions

Generic precision matrix operator

Description

Creates a flexible precision matrix K by allowing linear combinations of base matrices with parameter-dependent coefficients. The model follows the form: K = sum_i f_i(theta) * matrices_i, where f_i depends on the parameter transformation.

Usage

generic(
  theta_K,
  matrices,
  h,
  trans = NULL,
  mesh = NULL,
  zero_trace = FALSE,
  model = "generic",
  param_name = NULL,
  param_trans = NULL,
  ...
)

Arguments

theta_K	The parameter vector (in real scale). If missing, initialized as double(0)
matrices	A list of matrices to be combined with parameter-dependent coefficients
h	The integration weights vector
trans	Transformation for each parameter. Must be a list where each element is a character vector defining transformations for each matrix. For example, ‘trans=list(kappa=c("exp2", "identity", "null"))' means parameter ’kappa' affects matrix 1 with exp2 transformation, matrix 2 with identity, and doesn't affect matrix 3. Available transformations: "identity", "exp", "exp2", "exp4", "sqrt", "square", "log", "tanh"
mesh	The mesh object
zero_trace	Whether the trace of K should be zero
model	The model type name
param_name	Optional parameter names stored on the returned operator for diagnostics
param_trans	Optional parameter transformations stored on the returned operator for diagnostics
...	Additional arguments (ignored)

Details

This function can be used to represent various models like AR1, Matern, and RW1 in a unified framework.

The 'generic' function provides a flexible way to construct precision matrices by combining existing matrices with transformed parameters. Here's how it works:

1. Each parameter in 'theta_K' can affect one or more matrices in the 'matrices' list 2. The 'trans' list defines how each parameter transforms before multiplying each matrix 3. For each matrix, the coefficients from all parameters are multiplied together 4. The final K is the sum of all transformed matrices

Common use cases:

- **AR1 model**: K = rho * C + G (where rho is between -1 and 1) - **Matern (alpha=2)**: K = kappa^2 * C + G (where kappa > 0) - **Matern (alpha=4)**: K = kappa^4 * C + 2*kappa^2 * G + G * Cinv * G

Value

An object of class ngme_operator. The object stores the sparse precision matrix K, integration weights h, parameter vector theta_K, base matrices, transformation specification trans, and an update_K function that rebuilds K for new parameter values. It is intended for use as the latent model inside f().

Examples

# AR1 model with rho = 0.5
ar1_obj <- ar1(1:10, rho = 0.5)
g <- name2fun("tanh", inv = TRUE)
generic_ar1 <- generic(
  theta_K = c(rho = g(0.5)),  # Transform from real scale
  trans = list(rho = c("tanh", "null")),  # Apply tanh to first matrix
  matrices = list(ar1_obj$C, ar1_obj$G),
  h = ar1_obj$h
)

# Matern model with kappa = 2
mesh <- fmesher::fm_mesh_1d(seq(0, 1, length.out = 10))
matern_obj <- matern(mesh)
log_kappa <- log(2)
generic_matern <- generic(
  theta_K = c(kappa = log_kappa),
  trans = list(kappa = c("exp2", "null")),  # exp(2*kappa) for C, nothing for G
  matrices = list(matern_obj$C, matern_obj$G),
  h = matern_obj$h
)

# Matern model with alpha = 4 and kappa = 2
set.seed(1)
mesh <- fmesher::fm_mesh_2d(cbind(x = runif(20), y = runif(20)))
matern_obj <- matern(mesh, alpha = 4)
C <- matern_obj$C
G <- matern_obj$G
Cinv <- C; diag(Cinv) <- 1 / Matrix::diag(C)

generic_matern4 <- generic(
  theta_K = c(kappa = log(2)),
  trans = list(kappa = c("exp4", "exp2", "null")),
  matrices = list(C, 2*G, G %*% Cinv %*% G),
  h = matern_obj$h
)

ngme2 documentation built on May 20, 2026, 9:10 a.m.