\documentclass[a4paper]{article}
\usepackage[utf8]{inputenc}
\usepackage[T1]{fontenc}
\usepackage{hyperref}
\usepackage{geometry}
\geometry{margin=1in}

%\VignetteIndexEntry{Reproducible examples with VNDesign}
%\VignetteEngine{knitr::knitr}
%\VignetteEncoding{UTF-8}

\title{Reproducible examples with VNDesign}
\author{VNDesign authors}
\date{}

\begin{document}

\maketitle

<<setup, include=FALSE>>=
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.width = 7,
  fig.height = 4
)
@

\section{Overview}

\texttt{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:

\begin{enumerate}
\item Define a candidate set \texttt{chi}.
\item Build the regressor or gradient matrix \texttt{Xchi}.
\item Build the covariance matrix \texttt{Sigma\_chi}.
\item Run the Virtual Noise algorithm.
\item Optionally convert the approximate design measure into an exact design.
\end{enumerate}

\section{A minimal one-dimensional example}

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

<<minimal-example>>=
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)
@

For the classical VN algorithm implemented in \texttt{VNDesign},
\texttt{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 \texttt{kappa = 0.99/N}, where \texttt{N} is the number of candidate
points.

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

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

exact$points
@

\section{Full reproducible examples}

The package includes three full scripts in \texttt{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.

\begin{itemize}
\item \texttt{example\_pazman2003\_ex1.R}: one-dimensional linear model with compactly supported covariance from Pázman et al. 2003.
\item \texttt{example\_pazman2022\_ex1.R}: a classical one-parameter one-dimensional model from
  Pázman et al. 2022.
\item \texttt{example\_2D.R}: self-contained two-dimensional
  example on a regular grid.
\end{itemize}

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

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

<<examples-location, eval=FALSE>>=
system.file("examples", package = "VNDesign")
@

Run an individual example with:

<<run-examples-installed, eval=FALSE>>=
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:

<<run-examples-source, eval=FALSE>>=
source("inst/examples/example_pazman2003_ex1.R")
source("inst/examples/example_pazman2022_ex1.R")
source("inst/examples/example_2D.R")
@

\section{Quick Checks}

For a quick check of the example scripts, set:

<<quick-check, eval=FALSE>>=
Sys.setenv(VNDESIGN_EXAMPLE_MAX_ITER = "40")
Sys.setenv(VNDESIGN_EXAMPLE_PLOTS = "false")
@

Then source the desired script.

\end{document}