Package 'SPmodels'

Description

Convert a prediction-target result to its summary table

Usage

## S3 method for class 'spmodels_prediction_target'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

Arguments

Value

The target summary data frame stored in 'x$summary'.

Description

Constructs local Wald intervals from the fitted standard errors. Mean coefficients and random intercept-slope covariance entries use the identity scale, positive parameters use a logarithmic scale, and an estimated intervention impact uses the logit scale.

Usage

## S3 method for class 'spmodels_fit'
confint(object, parm, level = 0.95, ...)

Arguments

Details

These intervals rely on the fitted local observed-Hessian approximation. A missing standard error produces missing limits rather than a fabricated interval. Fixed parameters are omitted. The intervals do not include Monte Carlo error or repair weak identifiability.

Value

A matrix containing lower and upper limits. Its row names identify the model component and term. Attributes record the level and transformation.

Description

Evaluates the unit-variance Matérn correlation with dimensionless argument distance / scale. This scale convention is explicit; the argument is not described as a practical or effective range.

Usage

matern_cor(distance, scale, smoothness)

Arguments

Details

At zero distance the function returns one by continuity. Positive arguments are evaluated on the log scale using R's exponentially scaled modified Bessel function. See the Matérn chapter in the package's technical derivations for the assumptions, algorithm, and validation links.

Value

A numeric object with the dimensions and names of distance, containing correlations between zero and one.

Examples

d <- as.matrix(dist(c(0, 0.5, 1)))
matern_cor(d, scale = 1, smoothness = 0.5)

Description

Calculates the first or second derivative of the SPmodels Matérn correlation with respect to scale, holding distance and smoothness fixed.

Usage

matern_scale_derivative(distance, scale, smoothness, order = 1L)

Arguments

Value

A numeric object preserving the dimensions and names of distance.

Description

Base-graphics views over the unrounded values already stored in SPmodels validation and simulation results. No estimates or summaries are recomputed for display, apart from the displayed Wald endpoints in a recovery plot.

Usage

## S3 method for class 'spmodels_cross_validation'
plot(
  x,
  type = c("observed", "error", "fold"),
  xlab = NULL,
  ylab = NULL,
  main = NULL,
  ...
)

## S3 method for class 'spmodels_simulation_assessment'
plot(
  x,
  type = c("prediction", "error"),
  xlab = NULL,
  ylab = NULL,
  main = NULL,
  ...
)

## S3 method for class 'spmodels_simulation_recovery'
plot(
  x,
  parameter = 1L,
  intervals = TRUE,
  xlab = "Simulation replicate",
  ylab = NULL,
  main = NULL,
  ...
)

Arguments

Value

The input object, invisibly.

Description

Computes conditional Gaussian predictions using universal kriging equations. For binomial and Poisson Laplace fits, computes an approximate Gaussian predictive linear predictor and integrates it through the response link. Prediction uncertainty is conditional on fitted regression and covariance parameters.

Usage

## S3 method for class 'spmodels_fit'
predict(
  object,
  newdata = NULL,
  se.fit = FALSE,
  target = c("latent", "observation"),
  type = c("response", "link"),
  unseen = c("error", "marginal"),
  ...
)

Arguments

Value

A numeric vector, or a list containing fit, se.fit, target, and, for non-Gaussian fits, type.

Description

Generates unconditional Gaussian, binomial or Poisson response replicates at the fitted observation sites using the fitted mean, family and covariance parameters. Binomial output contains simulated success counts with the fitted trial totals.

Usage

## S3 method for class 'spmodels_fit'
simulate(object, nsim = 1L, seed = NULL, ...)

Arguments

Value

A data frame with one simulated response per column.

Description

Partitions projected fitted coordinates into axis-aligned rectangular blocks and assigns whole occupied blocks to validation folds. Repeated coordinates and all rows in one block remain together.

Usage

sp_block_folds(
  object,
  block_size,
  folds = 5L,
  origin = NULL,
  assignment = c("systematic", "random"),
  seed = NULL
)

## S3 method for class 'spmodels_block_folds'
print(x, ...)

Arguments

Details

Systematic assignment follows blocks from top to bottom and left to right, cycling through fold labels. Random assignment permutes whole blocks under a caller-local seed before balanced allocation. This controls the support withheld together; it does not by itself impose a distance buffer.

Value

An integer fold vector in fitted-row order with class spmodels_block_folds. Occupied-block indices, allocation, block size, origin, units and seed are retained as attributes.

Description

Constructs geometry-driven held-out folds and declares a spatial buffer. During cross-validation, rows outside the held-out fold but no farther than the buffer from any test location are excluded from that fold's training fit.

Usage

sp_buffered_folds(object, folds = 5L, buffer, seed = NULL, nstart = 20L)

## S3 method for class 'spmodels_buffered_folds'
print(x, ...)

Arguments

Details

The buffer changes training membership independently for every fold; buffered rows are neither trained on nor scored in that fold. Test rows remain exactly those identified by the fold vector. An over-large buffer that leaves no usable training data fails explicitly.

Value

An integer fold vector carrying the exclusion distance, coordinate units, cluster centres, seed and k-means metadata.

Description

Forms central type-8 empirical predictive intervals at each requested nominal level, evaluates their coverage of the supplied truths and calculates pointwise Wilson uncertainty bounds for the observed proportions.

Usage

sp_calibration(
  object,
  truth,
  levels = c(0.5, 0.8, 0.9, 0.95),
  confidence = 0.95
)

## S3 method for class 'spmodels_calibration'
print(x, ...)

## S3 method for class 'spmodels_calibration'
plot(
  x,
  xlab = "Nominal coverage",
  ylab = "Observed coverage",
  main = "Predictive interval calibration",
  ...
)

Arguments

Details

The bounds quantify finite-location uncertainty in the empirical coverage proportion. They are not simultaneous bands and do not incorporate dependence between spatial locations.

Value

sp_calibration() returns a spmodels_calibration object containing the unrounded nominal and observed coverage values, Wilson bounds and the number of locations. The print and plot methods return x invisibly.

Description

Creates controls for Gaussian geostatistical fitting and shared non-Gaussian covariance settings. The nugget may be fixed independently of the other covariance parameters, including at exactly zero.

Usage

sp_control(
  smoothness = 0.5,
  spatial_variance = NULL,
  scale = NULL,
  nugget_variance = NULL,
  random_variance = NULL,
  estimate = TRUE,
  estimate_nugget = NULL,
  distance_units = NULL,
  maxit = 500L,
  reltol = 1e-8
)

Arguments

Value

An object of class spmodels_control.

Description

Refits the original model after withholding every declared fold, then predicts held-out observations. Reports RMSE, mean absolute error and mean negative log score. Fixed user-supplied fold identifiers are preserved.

Usage

sp_cross_validate(
  object,
  folds = 5L,
  seed = NULL,
  unseen = c("error", "marginal")
)

## S3 method for class 'spmodels_cross_validation'
print(x, ...)

Arguments

Details

Cross-validation currently requires any offset to be written inside the model formula. Random folds are a convenience for reproducible checks; spatially separated folds should normally be supplied for spatial validation. Buffered folds remove near-test rows from training independently for each fold. Group-constrained folds that withhold complete fitted random-effect levels generally require the explicit marginal unseen-level policy.

Value

An object of class spmodels_cross_validation containing held-out row predictions, overall metrics, fold metrics, resolved fold identifiers, per-fold training sizes and optional buffer distance.

Description

Provides family-appropriate residual quantities for checking a fitted spatial model. Gaussian decorrelated residuals and non-Gaussian Pearson, deviance or randomized quantile residuals have different interpretations and are labelled separately.

Usage

sp_diagnostics(object, seed = NULL)

## S3 method for class 'spmodels_diagnostics'
plot(x, ...)

Arguments

Value

For Gaussian fits, sp_diagnostics() returns mean-model, conditional and decorrelated residuals. For binomial and Poisson fits it returns response, Pearson, signed deviance and randomized quantile residuals at the fitted latent mode. Coordinates, distance units and family are retained. The plot method invisibly returns its input.

Description

Calculates all unordered Euclidean coordinate-pair distances and reports counts, duplicate pairs, mean, standard deviation and requested type-8 quantiles.

Usage

sp_distance_summary(
  data,
  coords = NULL,
  distance_units = NULL,
  duplicates = c("include", "exclude", "error"),
  probs = c(0, 0.25, 0.5, 0.75, 1)
)

## S3 method for class 'spmodels_distance_summary'
print(x, ...)

Arguments

Value

An object containing retained pair distances, a one-row summary, units and the duplicate policy.

Description

Clusters unique fitted locations in a declared numeric environmental space. All rows at one coordinate remain together and must have identical environmental values, preventing exact-location leakage.

Usage

sp_environmental_folds(
  object,
  variables,
  folds = 5L,
  scale = TRUE,
  seed = NULL,
  nstart = 20L
)

## S3 method for class 'spmodels_environmental_folds'
print(x, ...)

Arguments

Details

Variables are standardized by default so measurement units do not arbitrarily determine Euclidean k-means distance. The resulting folds test transfer across environmental regimes; they are not spatial distance buffers and need not be geographically compact.

Value

An integer fold vector in fitted-row order with class spmodels_environmental_folds. Environmental centres, variables, scaling values and seed are retained as attributes.

Description

Fits Gaussian identity-link spatial regression by maximum likelihood, or binomial-logit and Poisson-log latent Gaussian spatial regression by a Laplace approximation. All models use a linear mean and stationary isotropic Matern covariance with fixed smoothness, optionally multiplied by exponential temporal correlation.

Usage

sp_fit(
  formula,
  data,
  family = stats::gaussian(),
  coords = NULL,
  spatial = TRUE,
  time = NULL,
  random = NULL,
  intervention = NULL,
  weights = NULL,
  subset = NULL,
  na.action = stats::na.fail,
  offset = NULL,
  control = sp_control(),
  verbose = FALSE,
  random_slope = NULL
)

Arguments

Details

Data frames use two numeric Euclidean coordinate columns and require explicit common units. Point sf data must have a known projected CRS; longitude/latitude geometry is rejected rather than silently projected. New sf prediction data must use the fitted CRS. Binomial responses may be Bernoulli values, a two-column successes/failures matrix, or proportions with integer trial weights. Poisson exposure should be supplied through a log offset. Non-Gaussian fits support point and joint prediction; those predictive calculations use a local Gaussian latent approximation at the fitted parameter values. Latent Gaussian random intercepts add one independent effect per observed level of each grouping variable. Prediction is conditional at known levels by default; unseen = "marginal" in prediction methods integrates a new zero-mean effect with its fitted variance. Positive-definite grouped random-slope covariance matrices may additionally be supplied or estimated with sp_random_slope(); correlated intercept-slope covariance is carried through fitting, prediction, simulation, diagnostics and MCML. Grouped effects are not available for non-spatial fits. A decay-adjusted intervention history may be supplied to a binomial-logit spatial fit with fixed or constrained estimated impact parameters. A sp_temporal() specification supplies one finite numeric time per row. The separable correlation is the product of the Matern spatial correlation and exp(-abs(time_i-time_j)/temporal_scale). New prediction data must contain the declared time variable. Temporal scale may be estimated only when covariance estimation is enabled; Gaussian ML and non-Gaussian Laplace/MCML fits carry it through prediction, simulation and validation.

Value

An object of class spmodels_fit. Its standard methods include coef, vcov, fitted, residuals, logLik, summary, print, and predict.

Examples

d <- data.frame(y = c(1, 2, 1.5, 3), x = c(0, 1, 0, 1),
                east = c(0, 1, 0, 1), north = c(0, 0, 1, 1))
fit <- sp_fit(y ~ x, d, coords = ~ east + north,
              control = sp_control(spatial_variance = 1, scale = 1,
                                   nugget_variance = 0.2, estimate = FALSE,
                                   distance_units = "km"))
coef(fit)

survey <- transform(d, positive = c(0, 1, 0, 1), examined = 1)
binomial_fit <- sp_fit(
  cbind(positive, examined - positive) ~ x, survey,
  family = binomial(), coords = ~ east + north,
  control = sp_control(spatial_variance = 1, scale = 1,
                       nugget_variance = 0.2, estimate = FALSE,
                       distance_units = "km")
)
fitted(binomial_fit)

Description

Fits a Gaussian identity-link geostatistical regression by multiplying ordered conditional densities that retain at most neighbors earlier observations. Only covariance blocks of at most that size are factorized. Retaining every predecessor recovers the dense Gaussian likelihood, regression coefficient estimates and coefficient covariance up to numerical precision. The approximation is explicit and never silently replaces sp_fit().

Usage

sp_fit_neighbor(
  formula,
  data,
  coords,
  neighbors = 30L,
  ordering = c("input", "maximin"),
  observation_order = NULL,
  subset = NULL,
  na.action = stats::na.fail,
  offset = NULL,
  control = sp_control(),
  verbose = FALSE
)

## S3 method for class 'spmodels_neighbor_fit'
coef(object, ...)
## S3 method for class 'spmodels_neighbor_fit'
confint(object, parm, level = 0.95, ...)
## S3 method for class 'spmodels_neighbor_fit'
vcov(object, ...)
## S3 method for class 'spmodels_neighbor_fit'
logLik(object, ...)
## S3 method for class 'spmodels_neighbor_fit'
fitted(object, ...)
## S3 method for class 'spmodels_neighbor_fit'
residuals(object, ...)
## S3 method for class 'spmodels_neighbor_fit'
print(x, ...)
## S3 method for class 'spmodels_neighbor_fit'
summary(object, ...)
## S3 method for class 'summary.spmodels_neighbor_fit'
print(x, ...)
## S3 method for class 'spmodels_neighbor_fit'
predict(
  object,
  newdata = NULL,
  se.fit = FALSE,
  target = c("latent", "observation"),
  ...
)

Arguments

Details

The ordering and neighbor budget are part of the statistical approximation and are retained in the fitted object. Maximin ordering starts at row one and then selects the point farthest from the selected set. Prediction conditions each new point on its nearest training observations and does not claim a joint prediction covariance. Fitted-parameter standard errors use local observed curvature when it is positive definite.

This initial route deliberately rejects non-Gaussian, grouped, random-slope and space-time covariance models. Use the ordinary fitters for those models.

Value

sp_fit_neighbor() returns a spmodels_neighbor_fit object. It retains the processing order, predecessor graph, local coefficients and conditional variances. Generic methods return the corresponding coefficients, covariance, likelihood, fitted values, residuals, summaries or local conditional predictions.

Examples

d <- data.frame(
  y = c(1.2, 0.8, 1.7, 1.1, 1.5, 0.9),
  z = c(0, 1, 0, 1, 0, 1),
  east = c(0, 1, 2, 0, 1, 2),
  north = c(0, 0, 0, 1, 1, 1)
)
fit <- sp_fit_neighbor(
  y ~ z, d, coords = ~ east + north, neighbors = 2,
  control = sp_control(
    estimate = FALSE, smoothness = 0.5, spatial_variance = 1,
    scale = 1, nugget_variance = 0.1, distance_units = "km"
  )
)
summary(fit)
predict(fit, d[1:2, ], se.fit = TRUE)

Description

Creates a presentation-only view over a stable SPmodels table. It never changes the machine-readable values from which the view was produced.

Usage

sp_format_table(
  object,
  digits = 3L,
  p_digits = 3L,
  missing = "—",
  detail = c("summary", "fold")
)

## S3 method for class 'spmodels_formatted_table'
print(x, ..., row.names = FALSE)

Arguments

Value

A character data frame of class spmodels_formatted_table. The exact unrounded source remains available in the raw_table attribute.

Description

Creates regular point centres within a projected polygon. If point data are supplied without a boundary, their convex hull defines the grid extent. Polygon data use their union. Geographic coordinates and zero-area boundaries fail explicitly.

Usage

sp_grid(data, cellsize, boundary = NULL)

Arguments

Value

A point sf object with stable top-to-bottom, left-to-right grid_id values.

Examples

if (requireNamespace("sf", quietly = TRUE)) {
  points <- sf::st_as_sf(data.frame(x = c(0, 2, 0), y = c(0, 0, 2)),
                         coords = c("x", "y"), crs = 3857)
  grid <- sp_grid(points, cellsize = 0.5)
  nrow(grid)
}

Description

Allocates whole observed groups to validation folds, preventing the same group from appearing in both training and held-out rows. Allocation greedily assigns each next group to the fold with the fewest rows.

Usage

sp_group_folds(
  object,
  group,
  folds = 5L,
  assignment = c("balanced", "random"),
  seed = NULL
)

## S3 method for class 'spmodels_group_folds'
print(x, ...)

Arguments

Value

An integer fold vector in fitted-row order. Group names, row counts and allocations are retained in the groups attribute.

Description

Defines a fixed intervention history. Every intervention strictly before a survey multiplies baseline prevalence by 1 - alpha * exp(-(survey_time - intervention_time) / decay). Same-time interventions are excluded, corresponding to a survey immediately before rollout.

Usage

sp_intervention(
  history,
  unit,
  time,
  alpha,
  decay,
  time_units,
  estimate = FALSE,
  alpha_penalty = NULL,
  treated = NULL
)

## S3 method for class 'spmodels_intervention'
print(x, ...)

Arguments

Value

An object of class spmodels_intervention.

Description

Calculates the remaining proportional reduction and one-intervention prevalence multiplier. Fitted models with usable intervention-parameter covariance receive delta-method pointwise intervals.

Usage

sp_intervention_curve(object, lag, level = 0.95)

## S3 method for class 'spmodels_intervention_curve'
print(x, ...)

## S3 method for class 'spmodels_intervention_curve'
plot(x, ...)

Arguments

Value

An object of class spmodels_intervention_curve containing an unrounded values table and metadata.

Description

Evaluates the intervention-history multiplier for survey or prediction rows.

Usage

sp_intervention_multiplier(intervention, data)

Arguments

Value

One multiplier in [0, 1] per row of data.

Description

Finds the posterior mode of a latent Gaussian vector for independent binomial-logit or Poisson-log observations. This is a deterministic building block for later Monte Carlo maximum-likelihood fitting and does not itself estimate model parameters.

Usage

sp_latent_mode(
  y,
  linear_predictor,
  covariance,
  family = stats::binomial(),
  trials = NULL,
  probability_multiplier = NULL,
  initial = NULL,
  maxit = 100L,
  tolerance = 1e-8
)

Arguments

Value

A spmodels_latent_mode list containing the mode, inverse local curvature, gradient, iteration information, conditional means and log posterior.

Description

Runs a preconditioned Metropolis-adjusted Langevin algorithm for the supplied latent posterior. This samples latent effects conditional on supplied parameters; it is not by itself a fitted parameter model.

Usage

sp_latent_sample(
  y,
  linear_predictor,
  covariance,
  family = stats::binomial(),
  trials = NULL,
  initial = NULL,
  control = sp_mcmc_control(),
  seed = NULL
)

Arguments

Value

A spmodels_latent_sample object containing pooled draws, a draw-by-component-by-chain array, chain identities, chain-specific acceptance information, initial states, the latent mode and resolved controls.

Description

Defines explicit iteration and proposal settings for the preconditioned Metropolis-adjusted Langevin sampler.

Usage

sp_mcmc_control(
  iterations = 4000L,
  burnin = 1000L,
  thin = 3L,
  step_size = 0.7,
  chains = 1L,
  initial_scale = 2
)

Arguments

Value

An object of class spmodels_mcmc_control.

Description

Replaces the Laplace fitting objective with an importance-sampling estimate of the binomial or Poisson marginal likelihood.

Usage

sp_mcml(object, control = sp_mcml_control(), seed = NULL, verbose = FALSE)

Arguments

Details

The importance distribution is either a scaled Gaussian approximation to the latent posterior at the supplied fit or a normalized same-centre mixture of declared scales. Mixture draws are balanced across components and divided by the complete mixture density. The proposal is normalized, so the returned Monte Carlo log likelihood is absolute rather than known only up to an omitted constant. Common random numbers make optimization deterministic within a call. A small effective sample size or dominant normalized weight indicates that the importance approximation is unreliable. Mixture likelihood MCSE uses its component-stratified variance. With adapt = TRUE, an independent pilot supplies importance-weighted moments that are shrunk toward the Laplace moments. The pilot is diagnosed, retained for audit and discarded before a new main sample is drawn. Conditional on the pilot, weighting by the complete normalized adapted density preserves the same marginal likelihood. If pilot ESS is below ess_warning, the original moments are retained and the recorded adaptation status explains the fallback. Adaptation is not guaranteed to improve overlap. Downstream latent prediction continues to use local Gaussian conditional calculations at the MCML parameter estimates. If intervention impact and decay were declared estimated, they are re-estimated on logit and log scales and their optional normalized beta penalty is included in the MCML criterion.

Value

An updated spmodels_fit. The mcml component contains the proposal, retained importance draws and weights, effective sample size, maximum normalized weight and an approximate Monte Carlo standard error. When adaptation is requested it also retains the original moments and complete pilot record.

Examples

d <- data.frame(y = c(0, 1, 0, 1), x = c(0, 1, 0, 1),
                east = c(0, 1, 0, 1), north = c(0, 0, 1, 1))
fit <- sp_fit(y ~ x, d, family = binomial(), coords = ~ east + north,
  control = sp_control(spatial_variance = 1, scale = 1,
    nugget_variance = 0.2, estimate = FALSE, distance_units = "km"))
corrected <- sp_mcml(fit,
  control = sp_mcml_control(nsim = 200, maxit = 20), seed = 1)
corrected$mcml$effective_sample_size

Description

Configures the normalized importance distribution, optional discarded-pilot adaptation and deterministic common-random-number optimization used by sp_mcml().

Usage

sp_mcml_control(
  nsim = 2000L,
  maxit = 200L,
  reltol = 1e-06,
  proposal_scale = 1,
  ess_warning = 0.1,
  adapt = FALSE,
  pilot_nsim = 500L,
  adapt_shrinkage = 0.5
)

Arguments

Value

An object of class spmodels_mcml_control.

Description

Refits using geometrically increasing independent importance-sample sizes until both declared diagnostic targets are met or max_nsim is reached.

Usage

sp_mcml_precision(
  object,
  control = sp_mcml_control(),
  target_relative_mcse = 0.02,
  min_ess_fraction = 0.1,
  max_nsim = 32000L,
  growth = 2,
  seed = NULL,
  refresh = TRUE,
  verbose = FALSE
)

Arguments

Value

The final spmodels_fit, with an mcml_precision component that records every attempted sample size, diagnostic and stopping reason. Adaptive attempts include pilot ESS, maximum weight, relative MCSE and the used/fallback decision.

Description

Runs sp_mcml() with independent importance samples. Replication diagnoses Monte Carlo sensitivity; it does not replace scientific sampling uncertainty or combine the fits into a new estimator. The empirical between-replicate covariance measures parameter-level Monte Carlo sensitivity. When every fitted Hessian covariance is usable, the object also reports their mean and its sum with the Monte Carlo covariance; otherwise those sampling and combined entries remain missing.

Usage

sp_mcml_replicates(
  object,
  nrep = 3L,
  control = sp_mcml_control(),
  seed = NULL,
  verbose = FALSE
)

## S3 method for class 'spmodels_mcml_replicates'
print(x, ...)

Arguments

Value

An object of class spmodels_mcml_replicates containing every fit, replicate estimates, between-replicate summaries and likelihood diagnostics. It also includes empirical Monte Carlo, mean fitted-Hessian sampling, and combined parameter covariance matrices on both optimizer and natural model scales. When adaptation is requested, diagnostics also contain pilot ESS, maximum weight, relative MCSE and the used/fallback decision.

Description

Converts an SPmodels fit into a machine-readable estimate table without requiring downstream code to inspect internal fit fields.

Usage

sp_model_table(object, include_smoothness = TRUE)

Arguments

Value

A stable data frame with one row per mean or covariance parameter.

Description

Reconstructs the complete covariance implied by the nearest-predecessor sequential conditionals for diagnostic comparison.

Usage

sp_neighbor_covariance(
  object,
  newdata = NULL,
  neighbors = 30L,
  ordering = c("input", "maximin"),
  prediction_order = NULL,
  target = c("latent", "observation"),
  unseen = c("error", "marginal"),
  reference = FALSE
)

## S3 method for class 'spmodels_neighbor_covariance'
print(x, ...)

Arguments

Details

This diagnostic deliberately allocates a complete prediction-site matrix and is intended for manageable validation subsets. It is not the bounded-memory production route. The covariance recursion uses each local conditional coefficient and variance; retaining every predecessor reproduces the ordinary fitted predictive covariance up to numerical precision.

Value

An object containing the implied covariance, predictive mean, local conditional coefficients/variances, graph and order. With reference = TRUE, it also contains the exact fitted predictive covariance and relative Frobenius, maximum absolute covariance and maximum marginal-variance errors.

Examples

d <- data.frame(y = c(1, 2, 1.5, 3), x = c(0, 1, 0, 1),
                east = c(0, 1, 0, 1), north = c(0, 0, 1, 1))
fit <- sp_fit(y ~ x, d, coords = ~ east + north,
  control = sp_control(spatial_variance = 1, scale = 1,
    nugget_variance = 0.2, estimate = FALSE, distance_units = "km"))
diagnostic <- sp_neighbor_covariance(fit, d, neighbors = 2,
                                     reference = TRUE)
diagnostic$errors

Description

Construct a valid non-stationary Matérn correlation matrix from a local positive-definite scale matrix at each location. The construction combines local Mahalanobis distances with a determinant adjustment, so locally varying anisotropy and range yield a valid covariance rather than an arbitrary pairwise-distance kernel.

Usage

sp_nonstationary_cor(coords, local_covariance, smoothness = 0.5)

Arguments

Details

Each local matrix has units of coordinate-distance squared. An isotropic local matrix 'rho^2 * diag(2)' therefore gives local range 'rho'.

Value

A symmetric 'n x n' correlation matrix with unit diagonal. The determinant construction is valid for any supplied positive-definite local matrices; this function does not estimate them or fit a regression.

References

Paciorek, C. J. and Schervish, M. J. (2006). Spatial modelling using a new class of nonstationary covariance functions. doi:10.1002/env.785.

Examples

locations <- cbind(east = c(0, 1, 2), north = c(0, 0.5, 1))
local <- array(0, dim = c(nrow(locations), 2, 2))
for (i in seq_len(nrow(locations))) {
  local[i, , ] <- diag(c(1 + i / 4, 0.8 + i / 5)^2, 2)
}
sp_nonstationary_cor(locations, local, smoothness = 1.5)

Description

Uses exact projected polygon intersections so a prediction cell can contribute proportionally to more than one target region.

Usage

sp_polygon_area_weights(
  cells,
  polygons,
  region,
  density = NULL,
  unmatched = c("error", "drop"),
  empty_regions = c("error", "drop")
)

Arguments

Value

An spmodels_polygon_weights object accepted by sp_predict_target(), retaining cell indices, region groups, raw weights, intersection areas, cell fractions and excluded cells/regions.

Description

Uses projected point-in-polygon membership to define regional weights for joint predictive draws. Points assigned to multiple distinct region identifiers fail explicitly. This is centre-point allocation, not an exact cell-area overlay.

Usage

sp_polygon_weights(
  points,
  polygons,
  region,
  weight = NULL,
  unmatched = c("error", "drop")
)

Arguments

Value

An object of class spmodels_polygon_weights containing retained point indices, raw weights, region identifiers, CRS and unmatched indices. It can be passed directly as weights to sp_predict_target().

Description

Applies ordinary point prediction to consecutive row chunks and combines results in original order. This is an exact computational reorganization, not a covariance approximation.

Usage

sp_predict_chunked(
  object,
  newdata,
  chunk_size = 1000L,
  se.fit = FALSE,
  target = c("latent", "observation"),
  type = c("response", "link"),
  unseen = c("error", "marginal")
)

Arguments

Details

The complete training-by-prediction cross-covariance matrix is never held in memory. Peak cross-covariance storage is proportional to the number of training rows times chunk_size. The function returns pointwise means and optional marginal standard errors; use sp_predict_draws() when a joint covariance or dependent draws across all prediction rows are required.

Value

The same numeric vector or pointwise list schema as predict(), with attributes chunk_size and chunks.

Examples

d <- data.frame(y = c(1, 2, 1.5, 3), x = c(0, 1, 0, 1),
                east = c(0, 1, 0, 1), north = c(0, 0, 1, 1))
fit <- sp_fit(y ~ x, d, coords = ~ east + north,
              control = sp_control(spatial_variance = 1, scale = 1,
                nugget_variance = .2, estimate = FALSE,
                distance_units = "km"))
sp_predict_chunked(fit, d, chunk_size = 2L)

Description

Draws jointly across prediction locations from the exact conditional Gaussian distribution or the local Gaussian predictive approximation for a binomial-logit or Poisson-log fit. Joint drawing preserves the spatial dependence needed for grid and regional targets.

Usage

sp_predict_draws(
  object,
  newdata = NULL,
  nsim = 1000L,
  target = c("latent", "observation"),
  type = c("response", "link"),
  seed = NULL,
  parameter_uncertainty = FALSE,
  unseen = c("error", "marginal")
)

## S3 method for class 'spmodels_prediction_draws'
print(x, ...)

Arguments

Details

For non-Gaussian models, response-scale latent draws transform the joint linear-predictor draw into probabilities or intensities. Observation draws additionally apply Bernoulli or Poisson response sampling. Regression- and covariance-parameter uncertainty is omitted by default. When requested, the returned parameter_draws record the regression coefficients, log covariance parameters and any logit-impact/log-decay values used for each predictive draw. Draw-specific intervention multipliers are also retained.

Value

An object of class spmodels_prediction_draws. Its draws component is an nsim by number-of-locations matrix. The object also contains the predictive link mean and covariance and target metadata.

Examples

d <- data.frame(y = c(1, 2, 1.5, 3), x = c(0, 1, 0, 1),
                east = c(0, 1, 0, 1), north = c(0, 0, 1, 1))
fit <- sp_fit(y ~ x, d, coords = ~ east + north,
              control = sp_control(spatial_variance = 1, scale = 1,
                                   nugget_variance = 0.2, estimate = FALSE,
                                   distance_units = "km"))
draws <- sp_predict_draws(fit, d[1:2, ], nsim = 10, seed = 1)
dim(draws$draws)

Description

Generates joint draws from a nearest-predecessor factorization of the fitted Gaussian predictive distribution without allocating the complete prediction-site covariance matrix.

Usage

sp_predict_draws_neighbor(
  object,
  newdata = NULL,
  nsim = 1000L,
  neighbors = 30L,
  ordering = c("input", "maximin"),
  prediction_order = NULL,
  target = c("latent", "observation"),
  type = c("response", "link"),
  seed = NULL,
  parameter_uncertainty = FALSE,
  unseen = c("error", "marginal")
)

Arguments

Details

For each prediction row, the function conditions on at most neighbors earlier rows selected by Euclidean coordinate distance. The model's exact Gaussian or local non-Gaussian predictive mean and covariance formula is used for that small subset. Retaining every predecessor reproduces the ordinary joint Gaussian factorization up to numerical precision. Smaller neighborhoods are an order-dependent approximation. Maximin ordering uses linear working storage but quadratic distance work. Optional parameter uncertainty uses the same fitted-Hessian approximation as sp_predict_draws() and can be computationally expensive because every parameter draw rebuilds the fitted state and all local conditionals. The training fit remains dense. Singular positive-semidefinite predecessor blocks, such as coincident latent prediction rows, use a checked eigen-based Moore–Penrose solve without artificial jitter.

Value

An object of class spmodels_prediction_draws. Its full predictive_covariance is NULL; the conditional variances, neighbor indices and processing order define the approximation.

Examples

d <- data.frame(y = c(1, 2, 1.5, 3), x = c(0, 1, 0, 1),
                east = c(0, 1, 0, 1), north = c(0, 0, 1, 1))
fit <- sp_fit(y ~ x, d, coords = ~ east + north,
  control = sp_control(spatial_variance = 1, scale = 1,
    nugget_variance = 0.2, estimate = FALSE, distance_units = "km"))
draws <- sp_predict_draws_neighbor(fit, d, nsim = 10, neighbors = 2,
                                   seed = 1)
dim(draws$draws)

Description

Calculates means, standard deviations, quantiles and optional exceedance probabilities from joint predictive draws. Optional grouped weighted means preserve uncertainty because aggregation is performed within every joint draw before summarisation.

Usage

sp_predict_target(
  object,
  weights = NULL,
  groups = NULL,
  threshold = NULL,
  probs = c(0.025, 0.5, 0.975)
)

## S3 method for class 'spmodels_prediction_target'
print(x, ...)

Arguments

Value

An object of class spmodels_prediction_target containing target-level draws, a summary table, normalised weights, groups, threshold and scale metadata.

Description

Generates nearest-predecessor joint prediction draws and immediately accumulates grouped weighted targets, avoiding storage of a complete location-level draw matrix when only aggregate targets are needed.

Usage

sp_predict_target_neighbor(
  object,
  newdata = NULL,
  weights,
  groups = NULL,
  nsim = 1000L,
  neighbors = 30L,
  ordering = c("input", "maximin"),
  prediction_order = NULL,
  target = c("latent", "observation"),
  type = c("response", "link"),
  threshold = NULL,
  probs = c(0.025, 0.5, 0.975),
  seed = NULL,
  unseen = c("error", "marginal")
)

Arguments

Details

A point-draw vector is discarded after its final use in the declared neighbor graph. Working draw storage is therefore proportional to the graph's active width rather than automatically to every prediction location, in addition to the returned number-of-draws by number-of-targets matrix. Numeric and polygon allocation weights are normalized within target. Parameter uncertainty is not included. Observation-scale binomial/Poisson sampling is generated during streaming, so its seeded draws need not equal a post-hoc call that consumes random numbers in a different order.

Value

An spmodels_prediction_target containing target-level draws and summaries, sparse normalized weights, the neighbor graph, conditional variances, processing order and peak number of point-draw vectors retained.

Examples

d <- data.frame(y = c(1, 2, 1.5, 3), x = c(0, 1, 0, 1),
                east = c(0, 1, 0, 1), north = c(0, 0, 1, 1))
fit <- sp_fit(y ~ x, d, coords = ~ east + north,
  control = sp_control(spatial_variance = 1, scale = 1,
    nugget_variance = 0.2, estimate = FALSE, distance_units = "km"))
target <- sp_predict_target_neighbor(
  fit, d, weights = rep(1, nrow(d)), nsim = 10,
  neighbors = 2, seed = 1
)
target$summary

Description

Summarises joint prediction draws at each location or returns an existing grouped-target summary using a stable downstream schema.

Usage

sp_prediction_table(object, threshold = NULL, probs = c(0.025, 0.5, 0.975))

Arguments

Value

A data frame of draw summaries and prediction metadata.

Description

Constructs an explicit prediction scenario without refitting or mutating the fitted model. Coordinates, geometry, row order and unmentioned columns remain unchanged. Formula transformations, factors and offset() expressions are rebuilt through the fitted model's terms and contrast definitions.

Usage

sp_prediction_update(
  object,
  newdata,
  changes,
  rows = NULL,
  se.fit = FALSE,
  target = c("latent", "observation"),
  type = c("response", "link")
)

## S3 method for class 'spmodels_prediction_update'
print(x, ...)

Arguments

Details

Coordinate variables cannot be changed. Offsets supplied separately to the original fitting call are rejected because they cannot be reconstructed safely from prediction data; write an offset in the model formula for scenario use. The returned differences compare point predictions conditional on the same fitted parameter values and fitted latent state.

Value

An object of class spmodels_prediction_update. It contains the updated data; baseline and updated design matrices and offsets; row-level baseline, updated and difference values; optional standard errors; changed rows and columns; and preservation checks.

Description

Evaluates Gaussian predictive normal scores or integrates a binomial/Poisson response probability over the approximate Gaussian predictive distribution on the link scale.

Usage

sp_predictive_log_score(
  object,
  newdata,
  observed,
  trials = NULL,
  unseen = c("error", "marginal")
)

Arguments

Details

The non-Gaussian integral is one-dimensional for each prediction row and conditional on fitted parameters. Binomial intervention multipliers are included. A failed or numerically underflowed integral produces an explicit error rather than a clipped score.

Value

A numeric vector of negative log predictive densities.

Description

Define a grouped Gaussian coefficient vector whose covariance is supplied explicitly or used as the starting value for constrained estimation. Each group receives an independent copy of that vector. With intercept = TRUE, the vector contains a random intercept and a random slope and covariance is therefore a 2 by 2 matrix. This explicit covariance interface keeps assumptions visible in teaching. Estimation is opt-in and retains positive definiteness at every optimizer evaluation.

Usage

sp_random_slope(
  group,
  slope,
  covariance,
  intercept = TRUE,
  label = NULL,
  estimate = FALSE
)

## S3 method for class 'spmodels_random_slope'
print(x, ...)

Arguments

Value

An object for the random_slope argument of sp_fit().

Examples

fixed <- sp_random_slope(
  "clinic", "age_centered", matrix(c(0.3, 0.05, 0.05, 0.08), 2L)
)
estimated <- sp_random_slope(
  "clinic", "age_centered", matrix(c(0.3, 0.05, 0.05, 0.08), 2L),
  estimate = TRUE
)

Description

Assembles model, optional prediction and optional validation sections while keeping presentation formatting separate from all unrounded statistical output.

Usage

sp_report(
  object,
  prediction = NULL,
  validation = NULL,
  title = "SPmodels analysis report",
  digits = 3L,
  p_digits = 3L,
  validation_detail = c("summary", "fold")
)

## S3 method for class 'spmodels_report'
print(x, ...)

Arguments

Value

An spmodels_report containing analysis metadata, unrounded stable tables and separate formatted views.

Description

Calculates autocorrelation-aware effective sample sizes and Monte Carlo standard errors. With multiple chains it also calculates the maximum of rank-normalized split and folded rank-normalized split R-hat.

Usage

sp_sampler_diagnostics(object, component = 1L, max_lag = NULL, chains = NULL)

## S3 method for class 'spmodels_sampler_diagnostics'
plot(x, ...)

## S3 method for class 'spmodels_sampler_diagnostics'
print(x, ...)

Arguments

Value

A spmodels_sampler_diagnostics object containing per-component means, standard deviations, multi-chain effective sample sizes, Monte Carlo standard errors and rank-normalized split R-hat values, plus chain acceptance rates and selected trace/autocorrelation values. Methods invisibly return the object.

Description

Assesses a joint predictive draw ensemble against known simulated truth or held-out observations. All interval and score definitions are calculated directly from the retained draws.

Usage

sp_simulation_assess(object, truth, interval = 0.95, threshold = NULL)

## S3 method for class 'spmodels_simulation_assessment'
print(x, ...)

Arguments

Value

An object of class spmodels_simulation_assessment containing location-level errors, intervals, coverage and empirical CRPS, plus overall bias, RMSE, MAE, coverage, interval width and mean CRPS.

Description

Builds a reproducible Cartesian parameter design for sp_simulation_scenarios(). Each object retains the fitted design and refitting specification while its generative mean and covariance state are rebuilt at the declared truth.

Usage

sp_simulation_grid(object, values, prefix = "scenario")

Arguments

Details

These are simulation scenario objects, not new analyses of the observed response. Parameters fixed by the model specification cannot be varied because they would not be recoverable on refitting. Variance, scale and decay values must be positive; an estimated intervention alpha must be strictly between zero and one. Every grouped slope covariance combination must remain positive definite.

Value

A named list of generative spmodels_fit scenario objects. Its grid attribute records the Cartesian product in scenario order.

Description

Repeats a complete fitted-model recovery experiment at geometrically increasing replicate counts until the Monte Carlo standard error of mean bias passes for every recovered parameter or the exact cap is evaluated.

Usage

sp_simulation_precision(
  object,
  initial_nsim = 20L,
  max_nsim = 1000L,
  growth = 2,
  target_mcse,
  min_success = 10L,
  seed = NULL,
  level = 0.95,
  on_error = c("record", "stop"),
  workers = 1L
)

## S3 method for class 'spmodels_simulation_precision'
print(x, ...)

Arguments

Details

For parameter $j$, the monitored quantity is the empirical standard deviation of successful replicate estimates divided by the square root of their count. Each attempt is a complete independently seeded experiment. Failure at the cap remains explicitly false; criteria are never relaxed to manufacture a pass.

Value

An object containing the final spmodels_simulation_recovery, every attempted replicate count and seed, parameter-wise achieved MCSE and success count, and the target status.

Description

Simulates response datasets from the supplied fitted model and refits the same declared estimation route to every replicate. The summary reports bias, RMSE, empirical standard deviation, mean reported standard error and Wald interval coverage. MCML is repeated when the supplied fit used MCML.

Usage

sp_simulation_recovery(
  object,
  nsim = 100L,
  seed = NULL,
  level = 0.95,
  on_error = c("record", "stop"),
  workers = 1L
)

## S3 method for class 'spmodels_simulation_recovery'
print(x, ...)

Arguments

Details

The fitted parameter values are treated as simulation truth. This is a conditional fitted-model assessment, not evidence of performance across a scientific parameter space. Named responses and two-column binomial responses are supported. External offset arguments must instead be written in the model formula so every refit is self-contained. The recovery vector includes every estimated mean, spatial/nugget covariance, grouped random-intercept variance, temporal-scale and intervention parameter; fixed quantities are not reported as recovered estimates.

Value

An object containing simulated responses, replicate estimates and standard errors, convergence codes, recorded failures, fitted truth and a parameter-level recovery summary.

Description

Runs the existing fitted-model simulation and refitting contract over multiple explicitly named fitted scenarios. Each result remains available for audit; the combined summary adds a scenario column without pooling unlike parameters or replacing individual failures.

Usage

sp_simulation_scenarios(
  objects,
  nsim = 100L,
  seed = NULL,
  level = 0.95,
  on_error = c("record", "stop"),
  workers = 1L
)

## S3 method for class 'spmodels_simulation_scenarios'
print(x, ...)

Arguments

Details

The scenario models define their own fitted simulation truths and designs. This function orchestrates separate conditional experiments; it does not claim that the supplied scenarios form a scientifically sufficient design. When a base seed is supplied, each scenario is reproducible and the caller's random-number state remains unchanged. Scenario seeds are fixed before dispatch, so sequential and parallel execution are identical.

Value

An object containing every named spmodels_simulation_recovery result, their row-bound parameter summary, and scenario-level family, replicate, seed and successful-refit metadata.

Description

Clusters unique fitted coordinates into spatially compact folds. Repeated coordinate locations always receive the same fold, preventing a physical location from appearing in both training and held-out data. Cluster labels are canonicalized from top to bottom and then left to right. The result can be supplied directly to sp_cross_validate().

Usage

sp_spatial_folds(object, folds = 5L, seed = NULL, nstart = 20L)

## S3 method for class 'spmodels_spatial_folds'
print(x, ...)

Arguments

Details

This is k-means blocking in the fitted projected or declared Euclidean coordinate system. It is not a guarantee of equal fold sizes or a universal design for every scientific dependence structure.

Value

An integer vector in fitted-row order, with class spmodels_spatial_folds and canonical cluster centres attached.

Description

Joins calculated point/grid or grouped polygon summaries to geometry using row order or explicit unique identifiers.

Usage

sp_target_geometry(object, geometry, id = NULL)

## S3 method for class 'spmodels_target_sf'
plot(x, value = "mean", ...)

Arguments

Value

An sf object containing unrounded prediction-target summaries and audit metadata. The plot method returns it invisibly.

Description

Declares survey times and the exponential temporal scale for a separable Matern-exponential space-time covariance.

Usage

sp_temporal(time, scale, time_units, estimate = FALSE)

## S3 method for class 'spmodels_temporal'
print(x, ...)

Arguments

Value

An object of class spmodels_temporal.

Description

Selects a WGS84 UTM CRS after checking latitude support, antimeridian crossing, standard Norway/Svalbard exceptions, zone boundaries and hemisphere boundaries.

Usage

sp_utm_crs(
  data,
  zone_policy = c("error", "centre"),
  hemisphere_policy = c("error", "centre")
)

## S3 method for class 'spmodels_crs_choice'
print(x, ...)

Arguments

Value

An object containing an sf::crs, EPSG code, UTM zone, hemisphere and audit metadata.

Description

Provides a common machine-readable metric schema for SPmodels validation and simulation-assessment results.

Usage

sp_validation_table(object, detail = c("summary", "fold"))

Arguments

Value

A long-form data frame with assessment, scope, identifier, metric and value columns.

Description

Calculates binned pairwise residual semivariances with pair counts. Before fitting, ordinary residuals from lm, glm, or a non-spatial SPmodels fit can be used to assess whether spatial structure motivates fitting a spatial process. After fitting, conditional residuals can be used to assess remaining spatial structure. These are distinct diagnostic questions. Gaussian spatial-fit results can include the fitted covariance-model variogram. Discrete-family residual variograms deliberately omit a fitted response-scale curve rather than treating link covariance as residual semivariance.

Usage

sp_variogram(
  object = NULL,
  bins = 10L,
  max_distance = NULL,
  residual_type = NULL,
  seed = NULL,
  coords = NULL,
  values = NULL,
  data = NULL,
  distance_units = NULL
)

## S3 method for class 'spmodels_variogram'
plot(x, ...)

Arguments

Value

sp_variogram() returns an object of class spmodels_variogram containing binned empirical semivariances and, for Gaussian fits, the fitted model semivariance. The plot method invisibly returns its input.

Description

Builds a pointwise residual-variogram envelope and a global curve-discrepancy test from residual permutations or fitted-model parametric simulations. Pre-fit permutation envelopes are supported for ordinary model residuals, supplied residuals and non-spatial SPmodels fits.

Usage

sp_variogram_envelope(
  object = NULL,
  nsim = 999L,
  method = c("permutation", "parametric"),
  level = 0.95,
  bins = 10L,
  max_distance = NULL,
  residual_type = NULL,
  seed = NULL,
  coords = NULL,
  values = NULL,
  data = NULL,
  distance_units = NULL
)

## S3 method for class 'spmodels_variogram_envelope'
print(x, ...)

## S3 method for class 'spmodels_variogram_envelope'
plot(x, ...)

Arguments

Details

For a pre-fit diagnostic, the permutation null is exchangeability of the selected ordinary-model residual values across fixed locations. This provides the week 7 teaching comparison before fitting a spatial process. Gaussian parametric curves keep fitted parameters fixed. Binomial and Poisson parametric curves simulate a response, repeat the declared Laplace or Monte Carlo ML fitting route, and calculate the selected residuals from that refit. This includes fitting variability but is more computationally expensive.

Value

An object containing observed and simulated variogram curves, pointwise limits, standardized global statistics and a Monte Carlo p-value. Discrete parametric envelopes additionally retain every refit's convergence code and captured warning messages.

Description

Multiplies stationary Matern spatial correlation by stationary exponential temporal correlation.

Usage

spacetime_cor(distance, time_lag, spatial_scale, smoothness, temporal_scale)

Arguments

Value

Correlations with dimensions and names inherited from distance.