Type: Package
Title: Coarse-to-Fine Spatial Modeling
Version: 0.1.0
Imports: FNN, fields, nloptr, dbscan, ranger, withr
Suggests: sp, sf, knitr, rmarkdown
Description: Provides functions for coarse-to-fine spatial modeling (CFSM), enabling fast spatial prediction, regression, and uncertainty quantification. For further details, see Murakami et al. (2025) <doi:10.48550/arXiv.2510.00968>.
License: GPL-2 | GPL-3 [expanded from: GPL (≥ 2)]
Encoding: UTF-8
RoxygenNote: 7.3.3
VignetteBuilder: knitr
NeedsCompilation: no
Packaged: 2026-01-14 14:44:11 UTC; dmuraka
Author: Daisuke Murakami [aut, cre], Alexis Comber [aut], Takahiro Yoshida [aut], Narumasa Tsutsumida [aut], Chris Brunsdon [aut], Tomoki Nakaya [aut]
Maintainer: Daisuke Murakami <dmuraka@ism.ac.jp>
Repository: CRAN
Date/Publication: 2026-01-19 18:50:02 UTC

Coarse-to-fine spatial linear modeling

Description

Prediction and regression via coarse-to-fine spatial linear modeling.

Usage

cf_lm(y, x, coords, x0 = NULL, coords0 = NULL, mod_hv)

Arguments

y

Vector of response variables (N x 1).

x

Matrix of covariates (N x K).

coords

Matrix of 2-dimensional point coordinates (N x 2).

x0

Optional. Matrix of covariates at prediction sites (N0 x K).

coords0

Optional. Matrix of 2-dimensional point coordinates at prediction sites (N0 x 2).

mod_hv

Output object of the cf_lm_hv function.

Value

A list with the following elements:

beta

Regression coefficients, their standard errors, and the lower and upper limits of the 95 percent confidence intervals.

sd_summary

Standard deviation of the regression term (xb), spatial process (spatial_scale1, spatial_scale2,...), additional learning, and residuals.

e_summary

R-squared and RMSE for validation samples, and residual standard deviation (residual_SD), and root mean squared error for the validation samples (validation_RMSE)

pred

Predictive means and standard deviations (sample sites).

pred0

Predictive means and standard deviations (prediction sites).

bands

Bandwidth values for each scale. The i-th bandwidth is used for the spatial process corresponding to the i-th column of the Z matrix).

Z

Predictive mean of the spatial process in each scale (sample sites; list).

Z_sd

Predictive standard deviation of the spatial process in each scale (sample sites; list).

Z0

Predictive mean of the spatial process in each scale (prediction sites; list).

Z0_sd

Predictive standard deviation of the spatial process in each scale (prediction sites; list).

Other

Other internal output objects.

Author(s)

Daisuke Murakami

References

Murakami, D., Comber, A., Yoshida, T., Tsutsumida, N., Brunsdon, C., & Nakaya, T. (2025). Coarse-to-fine spatial modeling: A scalable, machine-learning-compatible spatial model. *arXiv:2510.00968*.

See Also

cf_lm_hv, sp_scalewise

Examples

set.seed(123)
require(sp); require(sf)
data(meuse)
data(meuse.grid)

### Data
y        <- log(meuse[,"zinc"])
coords   <- meuse[,c("x","y")]
x        <- data.frame(dist   = meuse[,"dist"],
                       ffreq2 = as.integer(meuse$ffreq == 2),
                       ffreq3 = as.integer(meuse$ffreq == 3))

### Data at prediction sites
coords0  <- meuse.grid[,c("x","y")]
x0       <- data.frame(dist   = meuse.grid[,"dist"],
                       ffreq2 = as.integer(meuse.grid$ffreq == 2),
                       ffreq3 = as.integer(meuse.grid$ffreq == 3))

### Holdout validation optimizing the number of spatial scales
mod_hv   <- cf_lm_hv(y = y, x = x, coords = coords, add_learn = "none")

### Spatial modeling and prediction
mod      <- cf_lm(y = y, x = x, x0 = x0, coords = coords, coords0 = coords0,
                 mod_hv = mod_hv)
mod

### Mapping predictive mean and standard deviations (SD)
meuse.grid$pred   <- mod$pred0$pred
meuse.grid$pred_sd<- mod$pred0$pred_sd
meuse.grid_sf     <- st_as_sf(meuse.grid, coords = c("x","y"))
plot(meuse.grid_sf[,"pred"], pch = 15, cex = 0.5, nbreaks = 20)   # Predictive mean
plot(meuse.grid_sf[,"pred_sd"], pch = 15, cex = 0.5, nbreaks = 20)# Predictive SD

### Multiscale spatial pattern/feature extraction
mod_s1<- sp_scalewise(mod,bw_range=c(1000,Inf)) # Large scale (1000 <= bandwdith)
mod_s2<- sp_scalewise(mod,bw_range=c(500,1000)) # Middle scale (500 <= bandwdith <= 1000)
mod_s3<- sp_scalewise(mod,bw_range=c(0,500))    # Small scale (bandwdith <= 500)
z1    <- mod_s1$pred0$pred                      # Predictive mean
z2    <- mod_s2$pred0$pred
z3    <- mod_s3$pred0$pred
z1_sd <- mod_s1$pred0$pred_sd                   # Predictive SD
z2_sd <- mod_s2$pred0$pred_sd
z3_sd <- mod_s3$pred0$pred_sd
meuse.grid_sf3  <- cbind(meuse.grid_sf, z1, z2, z3, z1_sd, z2_sd, z3_sd)
plot(meuse.grid_sf3[,c("z1","z2","z3")], pch = 15,
     cex = 0.5, nbreaks = 20,key.pos=4,axes=TRUE) # Predictive means
plot(meuse.grid_sf3[,c("z1_sd","z2_sd","z3_sd")], pch = 15,
     cex = 0.5, nbreaks = 20,key.pos=4,axes=TRUE) # Predictive SD

Holdout validation for coarse-to-fine training of spatial linear models

Description

Trains a coarse-to-fine spatial linear model and optimizes the spatial scale (resolution) through progressive holdout validation.

Usage

cf_lm_hv(
  y,
  x = NULL,
  coords,
  train_rat = 0.75,
  id_train = NULL,
  alpha = 0.9,
  kernel = "exp",
  add_learn = "none"
)

Arguments

y

Vector of response variables (N x 1).

x

Matrix of covariates (N x K).

coords

Matrix of 2-dimensional point coordinates (N x 2).

train_rat

Training sample ratio (default: 0.75). When N >= 1000, training samples are randomly selected. Otherwise, samples closest to the k-mean centers are used to stabilize the training.

id_train

Optional. If specified, the corresponding samples are used as training samples. Otherwise, training samples are selected at random (default).

alpha

Decay ratio of the kernel bandwidth in the coarse-to-fine training (default: 0.9).

kernel

Kernel type for modeling spatial dependence. '"exp"' for the exponential kernel (default) and '"gau"' for the Gaussian kernel.

add_learn

If '"rf"', random forest is additionally trained to capture non-linear patterns and/or higher-order interactions. Default is '"none"', meaning no additional training.

Value

A list with the following elements:

sse_hv

Sum-of-squared error (SSE) for validation samples.

sse_hv_all

All the SSEs obtained in each learning step.

id_train

ID of training samples.

other

List of other outcomes, which are internally used.

Author(s)

Daisuke Murakami

References

Murakami, D., Comber, A., Yoshida, T., Tsutsumida, N., Brunsdon, C., & Nakaya, T. (2025). Coarse-to-fine spatial modeling: A scalable, machine-learning-compatible spatial model. *arXiv:2510.00968*.

See Also

cf_lm

Extract scale-wise spatial processes

Description

Evaluate mean and variance of the spatial process with bandwidth values within a pre-specified range

Usage

sp_scalewise(mod, bw_range = c(0, Inf))

Arguments

mod

Output object from the cf_lm function.

bw_range

Range of bandwidth values of the simulated spatial processes. For example, if bw_range = c(10, 20), spatial processes with bandwidths between 10 and 20 are synthesized and simulated. The default is c(0, Inf), which synthesizes all scales.

Value

A list with the following elements:

pred

Means and standard deviations of the spatial process (sample sites).

pred0

Means and standard deviations of the spatial process (prediction sites).

Author(s)

Daisuke Murakami

See Also

cf_lm