Package {SingRegKrig}

Type:	Package
Title:	Singularity Regression Kriging for Spatial Prediction
Version:	0.1.0
Description:	Implements the Singularity Regression Kriging ('SRK') model for spatial prediction by integrating covariate singularity feature construction, nonlinear trend estimation via random forest, and geostatistical interpolation of residuals using ordinary kriging. Singularity-based anomaly indices are computed from environmental covariates at multiple spatial scales to capture local multiscale heterogeneity and augment the random forest feature set for trend estimation. The resulting residuals are interpolated using ordinary kriging to generate final spatial predictions with uncertainty quantification. Tools for spatial block cross-validation, parameter sensitivity analysis, and diagnostic visualization are also provided. Methods are based on Ren, Song, Chen, and Yu (2026) <doi:10.1080/15481603.2026.2690341>, with singularity theory from Cheng (2012) <doi:10.1016/j.gexplo.2012.07.007> and Cheng (2017) <doi:10.1016/j.gr.2017.07.011>, random forest methodology from Breiman (2001) <doi:10.1023/A:1010933404324>, and regression kriging framework from Hengl, Heuvelink, and Rossiter (2007) <doi:10.1016/j.cageo.2007.05.001>.
License:	GPL (≥ 3)
Encoding:	UTF-8
RoxygenNote:	7.3.3
Depends:	R (≥ 4.0.0)
Imports:	stats, graphics, grDevices, randomForest, gstat, sp
Suggests:	testthat (≥ 3.0.0)
LazyData:	true
NeedsCompilation:	no
Packaged:	2026-08-03 14:47:19 UTC; shikhar tyagi
Author:	Shikhar Tyagi [aut, cre], Arvind Pandey [aut], Bhupendra Singh [aut], Vrijesh Tripathi [aut]
Maintainer:	Shikhar Tyagi <shikhar1093tyagi@gmail.com>
Repository:	CRAN
Date/Publication:	2026-08-08 12:30:18 UTC

Compute Singularity Indices for Spatial Covariates

Description

Computes singularity-based anomaly indices from environmental covariates at multiple spatial scales. For each location, the singularity index characterises how the local covariate intensity changes with spatial scale, following the singularity theory of Cheng (2012, 2017).

Usage

compute_singularity(
  coords,
  values,
  scales = NULL,
  min_neighbours = 3L,
  min_scales = 2L
)

Arguments

Details

The singularity index is computed following the method described in Ren et al. (2026) and based on the singularity theory of Cheng (2012, 2017, 2018). For each location s and spatial scale r, the local covariate intensity C(A(s, r)) is estimated as the mean of the absolute covariate values within a square window of half-width r centred at s. The singularity index \alpha(s) is then estimated as the slope of the ordinary least-squares regression of \log C on \log r, plus 2:

\alpha(s) = \hat{\beta}_1(s) + 2

where \hat{\beta}_1(s) is the OLS slope from regressing \log C(A(s, r)) on \log r across the selected scales. A value of \alpha = 2 corresponds to a spatially uniform field; \alpha < 2 indicates local enrichment; \alpha > 2 indicates local depletion.

Value

A numeric vector of singularity indices with the same length as the number of rows in coords. A value of 2 indicates a spatially uniform field (neutral reference); values less than 2 indicate local enrichment (positive anomaly); values greater than 2 indicate local depletion.

References

Cheng, Q. (2012). Singularity theory and methods for mapping geochemical anomalies caused by buried sources and for predicting undiscovered mineral deposits in covered areas. Journal of Geochemical Exploration, 122, 55–70. doi:10.1016/j.gexplo.2012.07.007

Cheng, Q. (2017). Singularity analysis of global zircon U-Pb age series and implication of continental crust evolution. Gondwana Research, 51, 51–63. doi:10.1016/j.gr.2017.07.011

Ren, K., Song, Y., Chen, M., and Yu, Q. (2026). A singularity regression kriging for spatial prediction. GIScience & Remote Sensing, 63(1), 2690341. doi:10.1080/15481603.2026.2690341

Examples

set.seed(42)
coords <- as.matrix(expand.grid(x = 1:10, y = 1:10))
values <- rnorm(100)
alpha <- compute_singularity(coords, values, scales = c(1, 2, 3, 4, 5))
summary(alpha)

# Uniform field returns singularity = 2
alpha_uniform <- compute_singularity(coords, rep(1, 100),
                                      scales = c(1, 2, 3, 4, 5))
all(abs(alpha_uniform - 2) < 1e-10)

Plot Diagnostics for an SRK Model

Description

Produces diagnostic plots for a fitted SRK model, including residual histogram, variable importance, observed vs fitted, and variogram plots.

Usage

## S3 method for class 'srk'
plot(x, which = c(1L, 2L, 3L, 4L), ...)

Arguments

Value

Invisibly returns NULL.

Examples

sim_data <- sim_srk_data(n_side = 10, scenario = "normal", seed = 42)
model <- srk(z ~ cov1, data = sim_data, coords = ~x + y,
             scales = c(1, 2, 3, 4, 5), ntree = 100)
plot(model, which = 3)

Plot Cross-Validation Results

Description

Produces an observed vs predicted scatter plot from spatial block cross-validation.

Usage

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

Arguments

Value

Invisibly returns NULL.

Plot Sensitivity Analysis Results

Description

Produces a heatmap of performance metrics across parameter combinations.

Usage

## S3 method for class 'srk_sensitivity'
plot(x, metric = "R2", ...)

Arguments

Value

Invisibly returns NULL.

Predict from a Singularity Regression Kriging Model

Description

Generates spatial predictions at new locations using a fitted SRK model. Computes singularity features at prediction locations, evaluates the random forest trend, and performs ordinary kriging of residuals.

Usage

## S3 method for class 'srk'
predict(object, newdata, ...)

Arguments

Details

The prediction process follows three steps:

1. Singularity features are computed at prediction locations using combined training and prediction covariate data for neighbourhood completeness.

2. The random forest trend model is evaluated at prediction locations using the augmented feature set.

3. Residuals from training locations are interpolated to prediction locations via ordinary kriging, providing both predictions and uncertainty estimates.

Value

A data frame with columns:

x

First coordinate of prediction location.

y

Second coordinate of prediction location.

prediction

Final SRK prediction (trend plus kriged residual).

trend

Random forest trend estimate.

kriged_residual

Ordinary kriging interpolation of residuals.

kriging_se

Kriging standard error (prediction uncertainty).

References

Ren, K., Song, Y., Chen, M., and Yu, Q. (2026). A singularity regression kriging for spatial prediction. GIScience & Remote Sensing, 63(1), 2690341. doi:10.1080/15481603.2026.2690341

Examples

set.seed(42)
train <- sim_srk_data(n_side = 10, scenario = "normal", seed = 42)
model <- srk(z ~ cov1, data = train, coords = ~x + y,
             scales = c(1, 2, 3, 4, 5), ntree = 100)

# Create prediction locations
pred_locs <- expand.grid(x = seq(2, 9, by = 1), y = seq(2, 9, by = 1))
pred_locs$cov1 <- rnorm(nrow(pred_locs), mean = mean(train$cov1))
preds <- predict(model, newdata = pred_locs)
head(preds)

Print an SRK Model Object

Description

Print an SRK Model Object

Usage

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

Arguments

Value

Invisibly returns x.

Examples

sim_data <- sim_srk_data(n_side = 10, scenario = "normal", seed = 42)
model <- srk(z ~ cov1, data = sim_data, coords = ~x + y,
             scales = c(1, 2, 3, 4, 5), ntree = 100)
print(model)

Print Cross-Validation Results

Description

Print Cross-Validation Results

Usage

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

Arguments

Value

Invisibly returns x.

Print Sensitivity Analysis Results

Description

Print Sensitivity Analysis Results

Usage

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

Arguments

Value

Invisibly returns x.

Print Summary of an SRK Model

Description

Print Summary of an SRK Model

Usage

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

Arguments

Value

Invisibly returns x.

Simulate Spatial Data for SRK Examples

Description

Generates simulated spatial datasets on a regular grid with spatially autocorrelated fields and an associated covariate, following the simulation design described in Ren et al. (2026, Section 2.3).

Usage

sim_srk_data(
  n_side = 20L,
  scenario = c("normal", "skewed", "longtail"),
  seed = 42L
)

Arguments

Details

The data generation process follows the simulation design in Section 2.3.1 of Ren et al. (2026):

1. A spatially autocorrelated base field is generated using a spherical covariance model on a regular grid.

2. A covariate field is constructed to maintain a strong but imperfect spatial association with the base field.

3. The response variable is derived from the base field under one of three distributional scenarios: "normal" (linear shift), "skewed" (exponential transformation), or "longtail" (stronger exponential transformation).

Value

A data frame with columns:

x

Horizontal grid coordinate.

y

Vertical grid coordinate.

z

Response variable.

cov1

Spatially autocorrelated covariate.

References

Ren, K., Song, Y., Chen, M., and Yu, Q. (2026). A singularity regression kriging for spatial prediction. GIScience & Remote Sensing, 63(1), 2690341. doi:10.1080/15481603.2026.2690341

Examples

# Normal distribution scenario
sim_normal <- sim_srk_data(n_side = 10, scenario = "normal", seed = 42)
head(sim_normal)

# Skewed distribution scenario
sim_skew <- sim_srk_data(n_side = 10, scenario = "skewed", seed = 42)
summary(sim_skew$z)

Fit a Singularity Regression Kriging Model

Description

Fits the Singularity Regression Kriging (SRK) model for spatial prediction. SRK integrates covariate singularity feature construction, nonlinear trend estimation via random forest, and geostatistical interpolation of residuals using ordinary kriging.

Usage

srk(
  formula,
  data,
  coords,
  pred_data = NULL,
  scales = NULL,
  ntree = 500L,
  sd_threshold = 0.5,
  min_neighbours = 3L,
  min_scales = 2L,
  variogram_model = "auto"
)

Arguments

Details

The SRK model follows three main steps as described in Ren et al. (2026):

1. Singularity feature construction: For each covariate, singularity indices are computed at multiple spatial scales using compute_singularity. Features with standard deviation below sd_threshold are discarded.

2. Trend estimation: A random forest (Breiman, 2001) is trained on the augmented feature set (original covariates plus retained singularity features) to estimate the spatial trend.

3. Residual kriging: The residuals from the random forest trend are interpolated using ordinary kriging with an automatically fitted variogram model to generate final predictions with uncertainty quantification.

Value

An object of class "srk" containing:

call

The matched function call.

formula

The model formula.

coord_names

Names of coordinate columns.

cov_names

Names of covariate columns.

train_coords

Matrix of training coordinates.

train_covariates

Data frame of training covariates.

observed

Numeric vector of observed response values.

fitted_values

Numeric vector of fitted values at training locations.

trend_fitted

Numeric vector of random forest trend estimates at training locations.

residuals

Numeric vector of residuals (observed minus trend).

trend_model

The fitted randomForest object.

variogram_empirical

The empirical variogram of residuals.

variogram_model

The fitted variogram model.

singularity_indices

A data frame of singularity indices at training locations.

retained_features

Character vector of retained singularity feature names.

feature_importance

Named numeric vector of variable importance scores from the random forest.

scales

The spatial scales used.

sd_threshold

The standard deviation threshold used.

n

Number of training observations.

metrics

A named list with training metrics: R2, RMSE, and MAE.

predictions

If pred_data was provided, a data frame with columns x, y, prediction, trend, kriged_residual, and kriging_se.

References

Ren, K., Song, Y., Chen, M., and Yu, Q. (2026). A singularity regression kriging for spatial prediction. GIScience & Remote Sensing, 63(1), 2690341. doi:10.1080/15481603.2026.2690341

Breiman, L. (2001). Random forests. Machine Learning, 45(1), 5–32. doi:10.1023/A:1010933404324

Hengl, T., Heuvelink, G. B., and Rossiter, D. G. (2007). About regression-kriging: from equations to case studies. Computers & Geosciences, 33(10), 1301–1315. doi:10.1016/j.cageo.2007.05.001

Examples

# Generate simulated data
sim_data <- sim_srk_data(n_side = 10, scenario = "normal", seed = 42)

# Fit SRK model
model <- srk(z ~ cov1, data = sim_data, coords = ~x + y,
             scales = c(1, 2, 3, 4, 5), ntree = 100)
print(model)
summary(model)

Spatial Block Cross-Validation for SRK Models

Description

Performs spatial block cross-validation to evaluate the predictive accuracy of the SRK model. The study area is divided into spatial blocks, which are then assigned to folds for cross-validation, following the evaluation framework described in Ren et al. (2026, Section 3.2.3).

Usage

srk_block_cv(
  formula,
  data,
  coords,
  nfold = 5L,
  block_size,
  scales = NULL,
  ntree = 500L,
  sd_threshold = 0.5,
  min_neighbours = 3L,
  min_scales = 2L,
  variogram_model = "auto"
)

Arguments

Details

The study area is divided into non-overlapping rectangular spatial blocks of the specified size. Each block is assigned to one of nfold folds. For each fold, the SRK model is fitted on all observations outside the fold, and predictions are generated for observations within the fold. Performance metrics (R-squared, RMSE, MAE) are computed per fold and overall.

Value

An object of class "srk_cv" containing:

observed

Numeric vector of observed values.

predicted

Numeric vector of cross-validated predictions.

fold_id

Integer vector of fold assignments.

fold_metrics

A data frame with per-fold R2, RMSE, and MAE.

overall_metrics

A named list with overall R2, RMSE, and MAE.

nfold

Number of folds used.

block_size

Block size used.

References

Ren, K., Song, Y., Chen, M., and Yu, Q. (2026). A singularity regression kriging for spatial prediction. GIScience & Remote Sensing, 63(1), 2690341. doi:10.1080/15481603.2026.2690341

Examples

set.seed(42)
sim_data <- sim_srk_data(n_side = 15, scenario = "normal", seed = 42)
cv_result <- srk_block_cv(z ~ cov1, data = sim_data, coords = ~x + y,
                           nfold = 3, block_size = 5,
                           scales = c(1, 2, 3, 4, 5), ntree = 100)
print(cv_result)

Parameter Sensitivity Analysis for SRK Models

Description

Evaluates the robustness of the SRK model under different combinations of maximum singularity scale and singularity feature selection threshold, following the sensitivity analysis framework described in Ren et al. (2026, Section 4.4).

Usage

srk_sensitivity(
  formula,
  data,
  coords,
  scale_range,
  threshold_range,
  nfold = 5L,
  block_size,
  ntree = 500L,
  min_neighbours = 3L,
  min_scales = 2L,
  variogram_model = "auto",
  scale_step = 1
)

Arguments

Details

For each combination of maximum singularity scale and feature selection threshold, the function performs spatial block cross-validation using srk_block_cv and records the resulting performance metrics. This allows assessment of model robustness to parameter choices as described in the paper.

Value

An object of class "srk_sensitivity" containing:

results

A data frame with columns max_scale, threshold, R2, RMSE, and MAE for each parameter combination.

scale_range

The scale range tested.

threshold_range

The threshold range tested.

References

Ren, K., Song, Y., Chen, M., and Yu, Q. (2026). A singularity regression kriging for spatial prediction. GIScience & Remote Sensing, 63(1), 2690341. doi:10.1080/15481603.2026.2690341

Examples

set.seed(42)
sim_data <- sim_srk_data(n_side = 10, scenario = "normal", seed = 42)
sens <- srk_sensitivity(z ~ cov1, data = sim_data, coords = ~x + y,
                         scale_range = c(3, 5),
                         threshold_range = c(0.3, 0.5),
                         nfold = 3, block_size = 3, ntree = 50)
print(sens)

Simulated Spatial Data for SRK Examples

Description

A simulated spatial dataset on a 20 by 20 regular grid with a spatially autocorrelated response variable and covariate, generated following the simulation design described in Ren et al. (2026, Section 2.3.1).

Usage

srk_sim

Format

A data frame with 400 rows and 4 variables:

x

Horizontal grid coordinate (integer, 1 to 20).

y

Vertical grid coordinate (integer, 1 to 20).

z

Response variable (spatially autocorrelated, normal scenario).

cov1

Spatially autocorrelated covariate.

Source

Generated using sim_srk_data with n_side = 20, scenario = "normal", and seed = 42.

References

Ren, K., Song, Y., Chen, M., and Yu, Q. (2026). A singularity regression kriging for spatial prediction. GIScience & Remote Sensing, 63(1), 2690341. doi:10.1080/15481603.2026.2690341

Examples

data(srk_sim)
head(srk_sim)
summary(srk_sim)

Summary of an SRK Model

Description

Provides a detailed summary of a fitted SRK model including variable importance, variogram parameters, and accuracy metrics.

Usage

## S3 method for class 'srk'
summary(object, ...)

Arguments

Value

An object of class "summary.srk".

Examples

sim_data <- sim_srk_data(n_side = 10, scenario = "normal", seed = 42)
model <- srk(z ~ cov1, data = sim_data, coords = ~x + y,
             scales = c(1, 2, 3, 4, 5), ntree = 100)
summary(model)