rmvgrf: Multivariate Gaussian Random Field Simulation in R

Fast and exact simulation of multivariate Gaussian Random Fields (GRFs) using circulant embedding and FFT-based spectral methods. Includes analytical cokriging, simulation-based cokriging, and FFT-accelerated cokriging with conjugate gradient solver.

Installation

# Install development version from GitHub
# install.packages("devtools")  # if you don't have devtools yet
devtools::install_github("jtouyz/rmvgrf", build_vignettes = TRUE)

# Install from local source (development)
devtools::install("rmvgrf")

# Or build and install
R CMD build rmvgrf
R CMD INSTALL rmvgrf_0.1.0.tar.gz

Dependencies

The package requires:

• R >= 4.1.0
• Rcpp and RcppArmadillo (for C++ performance optimizations)
• Matrix (for efficient linear algebra)
• tidyverse (for modern R data handling)

Quick Start

library(rmvgrf)
library(tidyverse)

# 1. Define covariance structure
cov_funcs <- generate_matern_covariance_functions(
  p = 2,                          # Number of variables
  nu_list = c(1.5, 2.5),         # Smoothness
  rho_list = c(5.0, 8.0),        # Range
  sigma_list = c(1.0, 1.0),      # Standard deviation
  cross_corr = matrix(c(1.0, 0.7, 0.7, 1.0), nrow = 2)
)

# 2. Generate random field
result <- generate_multivariate_field_nd(c(64, 64), p = 2, cov_funcs)

# 3. Visualize
visualize_fields(result$real, result$imag)

# 4. Sample observations and perform kriging
s_obs <- matrix(sample(1:64, 40, replace = TRUE), ncol = 2)
Z_obs <- matrix(rnorm(40), ncol = 2)
s_target <- matrix(runif(20, 1, 64), ncol = 2)

krig_result <- solve_cokriging_system(s_target, s_obs, Z_obs, cov_funcs, p = 2)

Main Functions

Field Generation

• generate_multivariate_field_nd() - Generate d-dimensional multivariate GRF
• generate_univariate_field() - Generate 2D univariate GRF

Covariance Models

• matern_cov() - Matérn covariance function
• exp_cov() - Exponential covariance function
• gaussian_cov() - Gaussian (squared exponential) covariance
• spherical_cov() - Spherical covariance function
• generate_matern_covariance_functions() - Build multivariate covariance structure

⚠️ Note on Covariance Validity: This package does not validate whether user-specified multivariate covariance structures are valid (i.e., result in a positive definite cross-covariance matrix). For multivariate Matérn models, specific parameter constraints must be satisfied—see Gneiting, Kleiber & Schlather (2010) "Matérn Cross-Covariance Functions for Multivariate Random Fields" (PDF, DOI) for the parsimonious model conditions. Users are responsible for ensuring their covariance specifications are theoretically valid.

Kriging Methods

• solve_cokriging_system() - Analytical cokriging (Cholesky)
• kriging_via_simulation() - Monte Carlo conditional simulation
• solve_cokriging_fft() - FFT-accelerated cokriging (CG solver)

Visualization

• visualize_fields() - Plot generated fields
• plot_kriging_results() - Plot kriging predictions
• plot_kriging_variance() - Plot kriging variance
• plot_covariance_function() - Plot covariance function

Method Comparison

Method	Complexity	Off-grid obs?	Best for
solve_cokriging_system	O(N³)	Yes	Small/medium, arbitrary locations
kriging_via_simulation	O(M × N log N)	Yes (snapped)	Large grids, Monte Carlo
solve_cokriging_fft	O(K × N log N)	No (on-grid)	Large grids, exact solve

Documentation

Vignettes

The package includes comprehensive vignettes:

Vignette	Description
quickstart	Quick introduction to field generation and kriging
I_field_generation	1D/2D fields, custom covariance, visualization
II_covariance_models	Matérn, exponential, Gaussian, spherical; effect of ν, ρ, cross-correlation
III_kriging_simulation	Conditional simulation (Monte Carlo), uncertainty quantification
IV_kriging_spatial	Analytical cokriging with Cholesky solver
V_kriging_time_series	1D interpolation with confidence intervals
VI_model_validation	Covariance decay checks, empirical statistics validation

View vignettes after installation:

# List all vignettes
vignette(package = "rmvgrf")

# View specific vignette
vignette("quickstart", package = "rmvgrf")
vignette("II_covariance_models", package = "rmvgrf")
vignette("IV_kriging_spatial", package = "rmvgrf")

Running Examples

# Find example files
system.file("examples", package = "rmvgrf")

# Run an example
source(system.file("examples", "03_kriging_simulation.R", package = "rmvgrf"))

Recommended Learning Path

1. Getting Started: quickstart → I_field_generation
2. Covariance: II_covariance_models
3. Spatial Prediction: III_kriging_simulation → IV_kriging_spatial
4. Time Series: V_kriging_time_series
5. Validation: VI_model_validation

Testing

devtools::test()

License

MIT License

Author

Joshuah Touyz

Citation & Background

This library implements and extends methodologies originally developed in the author's PhD dissertation, specifically focusing on multivariate circulant embedding (Chapter 4). It provides production-ready implementations that expand the original academic scope with:

• Multiple optimized kriging methods (Analytical, FFT-based, Simulation-based)
• Comprehensive uncertainty quantification
• Performance optimizations for large-scale fields
• Integrated plotting and visualization tools

If you use this work in your research or applications, please cite the original dissertation:

Touyz, J. (2016). Novel Methodologies in Multivariate Spatial Statistics (Doctoral dissertation). The George Washington University. Available at ScholarSpace.