Reproducible examples with VNDesign

VNDesign authors

1 Overview

VNDesign implements the Virtual Noise algorithm for computing D-optimal experimental designs under correlated observations. This vignette introduces the basic workflow and points to the reproducible examples included with the package.

The main steps are:

  1. 1.

    Define a candidate set chi.

  2. 2.

    Build the regressor or gradient matrix Xchi.

  3. 3.

    Build the covariance matrix Sigma_chi.

  4. 4.

    Run the Virtual Noise algorithm.

  5. 5.

    Optionally convert the approximate design measure into an exact design.

2 A minimal one-dimensional example

The following example uses a linear model with candidate points in [−1,1].

library(VNDesign)

chi <- seq(-1, 1, length.out = 15)
theta <- c(0, 1)
kappa <- 0.99 / length(chi)

grad_fun <- function(x, theta) {
  c(1, x)
}

res <- vndesign_Dopt(
  chi = chi,
  theta = theta,
  grad_fun = grad_fun,
  kappa = kappa,
  max_iter = 10,
  verbose = FALSE,
  cov_type = "exp",
  range = 0.4,
  vn_alt = 3,
  vn_lambda = 2,
  return_components = TRUE
)

head(res$xi)
#> [1] 0.1 0.1 0.1 0.1 0.0 0.1

For the classical VN algorithm implemented in VNDesign, kappa is used as a virtual-noise threshold and is typically chosen slightly below the initial uniform design weight. In the reproducible examples we use kappa = 0.99/N, where N is the number of candidate points.

An exact design can be constructed from the approximate design measure:

exact <- exact_design(
  res = res,
  Xchi = res$Xchi,
  Sigma_chi = res$Sigma_chi,
  chi = chi,
  n = 3,
  method = "quantile"
)

exact$points
#> [1] -0.7142857 -0.2857143  0.4285714

3 Full reproducible examples

The package includes three full scripts in inst/examples/. These scripts are intended to show complete workflows for the examples discussed in the accompanying article and for a self-contained two-dimensional case.

  • •

    example_pazman2003_ex1.R: one-dimensional linear model with compactly supported covariance from Pázman et al. 2003.

  • •

    example_pazman2022_ex1.R: a classical one-parameter one-dimensional model from Pázman et al. 2022.

  • •

    example_2D.R: self-contained two-dimensional example on a regular grid.

The script example_2D.R is intentionally a toy example. It uses a regular grid and a simple planar trend only to illustrate how VNDesign handles a two-dimensional candidate set without requiring external spatial data. For real spatial applications, users should prepare their own candidate coordinates outside VNDesign; for example, a shapefile can be read, projected, and converted into an N×2 matrix or data frame of coordinates using specialised spatial packages such as sf. The resulting coordinate object can then be supplied directly as the argument chi.

After installing the package, their location can be found with:

system.file("examples", package = "VNDesign")

Run an individual example with:

source(system.file("examples", "example_pazman2003_ex1.R", package = "VNDesign"))
source(system.file("examples", "example_pazman2022_ex1.R", package = "VNDesign"))
source(system.file("examples", "example_2D.R", package = "VNDesign"))

When working from the source directory, the same scripts can be run with:

source("inst/examples/example_pazman2003_ex1.R")
source("inst/examples/example_pazman2022_ex1.R")
source("inst/examples/example_2D.R")

4 Quick Checks

For a quick check of the example scripts, set:

Sys.setenv(VNDESIGN_EXAMPLE_MAX_ITER = "40")
Sys.setenv(VNDESIGN_EXAMPLE_PLOTS = "false")

Then source the desired script.