generic_ns: Non-stationary precision matrix operator with custom matrix...

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

Non-stationary precision matrix operator with custom matrix combinations

Description

Creates a flexible non-stationary precision matrix K by allowing both linear combinations and matrix multiplications with parameter-dependent diagonal matrices. This enables modeling spatially varying parameters through basis expansions.

Usage

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

Arguments

theta_K	List of parameter vectors (in real scale)
matrices	List of fixed matrices to be used in the model
position	List of vectors specifying matrix combinations (required)
h	The integration weights vector
model	The model type name stored on the returned operator
B_theta_K	List of basis matrices for parameters, defaults to matrices of 1s if not provided
trans	List of transformations for each parameter (one transformation per parameter)
mesh	The mesh object
zero_trace	Whether the trace of K should be zero
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

The key distinction from 'generic' is that 'generic_ns': 1. Requires explicit position specification for matrix combinations 2. Converts parameters to diagonal matrices for multiplication with fixed matrices 3. Allows for basis expansions via B_theta_K

The 'generic_ns' operator constructs K through the following steps:

1. Create diagonal matrices for each parameter using basis expansions: D_param = diag(B_param * theta_param) 2. Combine parameter matrices with fixed matrices according to position specifications 3. Sum all the resulting combinations

The 'position' parameter defines how matrices are combined: - Each element of the list represents a term in the sum - Each vector contains indices of matrices to multiply (parameter matrices first, then fixed matrices) - For example: 'position = list(c(1, 3), c(2, 4))' with one parameter means: Multiply the parameter diagonal matrix (index 1) with fixed matrix 1 (index 3), then add parameter diagonal matrix 2 (index 2) multiplied by fixed matrix 2 (index 4)

Spatially-varying parameters can be created using basis matrices in B_theta_K.

Value

An object of class ngme_operator. The object stores the sparse non-stationary precision matrix K, integration weights h, the flattened parameter vector theta_K, basis matrices B_theta_K, parameter grouping metadata param_map, matrix combination rules position, and an update function for rebuilding K. It is intended for use as the latent model inside f().

Examples

# Simple example with one parameter
n <- 5
A <- matrix(1, n, n)
B <- matrix(2, n, n)
alpha <- 0.4

# Create a simple generic_ns model: D_alpha * A + B
model <- generic_ns(
  theta_K = list(alpha = c(alpha)),
  matrices = list(A, B),
  position = list(c(1, 2), c(3)), # D_alpha * A + B
  h = rep(1, n)
)

# AR1 model representation: rho * C + G
ar1_obj <- ar1(1:10, rho = 0.5)
g <- name2fun("tanh", inv = TRUE)
generic_ar1 <- generic_ns(
  theta_K = list(x = c(g(0.5))), # Transform from real scale
  trans = list(x = "tanh"), # Apply tanh transformation
  matrices = list(ar1_obj$C, ar1_obj$G),
  position = list(c(1, 2), c(3)), # D_rho * C + G
  h = ar1_obj$h,
  mesh = 1:10
)

# Spatially varying Matern model
# Create a simple 1D mesh
mesh <- fmesher::fm_mesh_1d(seq(0, 1, length.out = 10))

# Create basis for spatially-varying kappa
n <- 10
B_kappa <- matrix(0, n, 2)
B_kappa[1:(n / 2), 1] <- 1 # First half of the domain
B_kappa[(n / 2 + 1):n, 2] <- 1 # Second half of the domain

# Create standard Matern components
matern_model <- matern(mesh)

# Create model with space-varying kappa
ns_model <- generic_ns(
  theta_K = list(kappa = c(log(1), log(2))), # Different values for each region
  matrices = list(matern_model$C, matern_model$G),
  B_theta_K = list(kappa = B_kappa),
  trans = list(kappa = "exp2"), # kappa^2 transformation for C
  h = matern_model$h,
  position = list(c(1, 2), c(3)), # D_kappa * C + G
  mesh = mesh
)

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