Title:	Spatial Empirical Dynamic Modeling
Version:	1.9
Description:	Inferring causation from spatial cross-sectional data through empirical dynamic modeling (EDM), with methodological extensions including geographical convergent cross mapping from Gao et al. (2023) <doi:10.1038/s41467-023-41619-6>, as well as the spatial causality test following the approach of Herrera et al. (2016) <doi:10.1111/pirs.12144>, together with geographical pattern causality proposed in Zhang et al. (2025) <doi:10.1080/13658816.2025.2581207>.
License:	GPL-3
Encoding:	UTF-8
RoxygenNote:	7.3.3
URL:	https://stscl.github.io/spEDM/, https://github.com/stscl/spEDM
BugReports:	https://github.com/stscl/spEDM/issues
Depends:	R (≥ 4.1.0)
LinkingTo:	Rcpp, RcppThread, RcppArmadillo
Imports:	dplyr, ggplot2, methods, sdsfun (≥ 0.7.0), sf, terra
Suggests:	knitr, Rcpp, RcppThread, RcppArmadillo, rmarkdown, readr, plot3D
VignetteBuilder:	knitr
NeedsCompilation:	yes
Packaged:	2025-11-30 09:31:59 UTC; 31809
Author:	Wenbo Lv [aut, cre, cph]
Maintainer:	Wenbo Lv <lyu.geosocial@gmail.com>
Repository:	CRAN
Date/Publication:	2025-11-30 16:30:02 UTC

detect the number of available threads

Description

detect the number of available threads

Usage

detectThreads()

Value

An integer

Examples

detectThreads()

embedding spatial cross sectional data

Description

embedding spatial cross sectional data

Usage

## S4 method for signature 'sf'
embedded(
  data,
  target,
  E = 3,
  tau = 1,
  style = 1,
  stack = FALSE,
  detrend = FALSE,
  nb = NULL
)

## S4 method for signature 'SpatRaster'
embedded(
  data,
  target,
  E = 3,
  tau = 1,
  style = 1,
  stack = FALSE,
  detrend = FALSE,
  grid.coord = TRUE,
  embed.direction = 0
)

Arguments

Value

A matrix (when stack is FALSE) or list.

Examples

columbus = sf::read_sf(system.file("case/columbus.gpkg",package="spEDM"))
v = embedded(columbus,"crime")
v[1:5,]

npp = terra::rast(system.file("case/npp.tif",package="spEDM"))
r = embedded(npp,"npp")
r[which(!is.na(r),arr.ind = TRUE)[1:5],]

false nearest neighbours

Description

false nearest neighbours

Usage

## S4 method for signature 'sf'
fnn(
  data,
  target,
  E = 1:10,
  tau = 1,
  style = 1,
  stack = FALSE,
  lib = NULL,
  pred = NULL,
  dist.metric = "L1",
  rt = 10,
  eps = 2,
  threads = detectThreads(),
  detrend = TRUE,
  nb = NULL
)

## S4 method for signature 'SpatRaster'
fnn(
  data,
  target,
  E = 1:10,
  tau = 1,
  style = 1,
  stack = FALSE,
  lib = NULL,
  pred = NULL,
  dist.metric = "L1",
  rt = 10,
  eps = 2,
  threads = detectThreads(),
  detrend = TRUE,
  grid.coord = TRUE,
  embed.direction = 0
)

Arguments

Value

A vector

References

Kennel M. B., Brown R. and Abarbanel H. D. I., Determining embedding dimension for phase-space reconstruction using a geometrical construction, Phys. Rev. A, Volume 45, 3403 (1992).

Examples

columbus = sf::read_sf(system.file("case/columbus.gpkg",package="spEDM"))

fnn(columbus,"crime")

geographical convergent cross mapping

Description

geographical convergent cross mapping

Usage

## S4 method for signature 'sf'
gccm(
  data,
  cause,
  effect,
  libsizes = NULL,
  E = 3,
  k = E + 2,
  tau = 1,
  style = 1,
  stack = FALSE,
  lib = NULL,
  pred = NULL,
  dist.metric = "L2",
  dist.average = TRUE,
  theta = 1,
  algorithm = "simplex",
  threads = detectThreads(),
  detrend = TRUE,
  parallel.level = "low",
  bidirectional = TRUE,
  progressbar = TRUE,
  nb = NULL
)

## S4 method for signature 'SpatRaster'
gccm(
  data,
  cause,
  effect,
  libsizes = NULL,
  E = 3,
  k = E + 2,
  tau = 1,
  style = 1,
  stack = FALSE,
  lib = NULL,
  pred = NULL,
  dist.metric = "L2",
  dist.average = TRUE,
  theta = 1,
  algorithm = "simplex",
  threads = detectThreads(),
  detrend = TRUE,
  parallel.level = "low",
  bidirectional = TRUE,
  progressbar = TRUE,
  grid.coord = TRUE,
  embed.direction = 0,
  win.ratio = 0
)

Arguments

Value

A list

xmap

cross mapping results

varname

names of causal and effect variables

bidirectional

whether to examine bidirectional causality

References

Gao, B., Yang, J., Chen, Z. et al. Causal inference from cross-sectional earth system data with geographical convergent cross mapping. Nat Commun 14, 5875 (2023).

Examples

columbus = sf::read_sf(system.file("case/columbus.gpkg",package="spEDM"))

g = gccm(columbus,"hoval","crime",libsizes = seq(5,45,5),E = 6)
g
plot(g,ylimits = c(0,0.85))

geographical cross mapping cardinality

Description

geographical cross mapping cardinality

Usage

## S4 method for signature 'sf'
gcmc(
  data,
  cause,
  effect,
  libsizes = NULL,
  E = 3,
  k = pmin(E^2),
  tau = 1,
  style = 1,
  lib = NULL,
  pred = NULL,
  dist.metric = "L2",
  threads = detectThreads(),
  detrend = FALSE,
  parallel.level = "low",
  bidirectional = TRUE,
  progressbar = TRUE,
  nb = NULL
)

## S4 method for signature 'SpatRaster'
gcmc(
  data,
  cause,
  effect,
  libsizes = NULL,
  E = 3,
  k = pmin(E^2),
  tau = 1,
  style = 1,
  lib = NULL,
  pred = NULL,
  dist.metric = "L2",
  threads = detectThreads(),
  detrend = FALSE,
  parallel.level = "low",
  bidirectional = TRUE,
  progressbar = TRUE,
  grid.coord = TRUE
)

Arguments

Value

A list

xmap

cross mapping results

cs

causal strength

varname

names of causal and effect variables

bidirectional

whether to examine bidirectional causality

Examples

columbus = sf::read_sf(system.file("case/columbus.gpkg",package="spEDM"))

g = gcmc(columbus,"hoval","crime",E = 7,k = 18)
g

geographical pattern causality

Description

geographical pattern causality

Usage

## S4 method for signature 'sf'
gpc(
  data,
  cause,
  effect,
  libsizes = NULL,
  E = 3,
  k = E + 2,
  tau = 1,
  style = 1,
  lib = NULL,
  pred = NULL,
  boot = 99,
  random = TRUE,
  seed = 42,
  dist.metric = "L2",
  zero.tolerance = k,
  relative = TRUE,
  weighted = TRUE,
  threads = detectThreads(),
  detrend = FALSE,
  parallel.level = "low",
  bidirectional = TRUE,
  progressbar = TRUE,
  nb = NULL
)

## S4 method for signature 'SpatRaster'
gpc(
  data,
  cause,
  effect,
  libsizes = NULL,
  E = 3,
  k = E + 2,
  tau = 1,
  style = 1,
  lib = NULL,
  pred = NULL,
  boot = 99,
  random = TRUE,
  seed = 42,
  dist.metric = "L2",
  zero.tolerance = k,
  relative = TRUE,
  weighted = TRUE,
  threads = detectThreads(),
  detrend = FALSE,
  parallel.level = "low",
  bidirectional = TRUE,
  progressbar = TRUE,
  grid.coord = TRUE
)

Arguments

Value

A list

xmap

cross mapping results (only present if libsizes is not NULL)

causality

per-sample causality statistics (present if libsizes is NULL)

summary

overall causal strength (present if libsizes is NULL)

pattern

pairwise pattern relationships (present if libsizes is NULL)

varname

names of causal and effect variables

bidirectional

whether to examine bidirectional causality

References

Zhang, Z., Wang, J., 2025. A model to identify causality for geographic patterns. International Journal of Geographical Information Science 1–21.

Examples

columbus = sf::read_sf(system.file("case/columbus.gpkg",package="spEDM"))

gpc(columbus,"hoval","crime",E = 6,k = 9)

# convergence diagnostics
g = gpc(columbus,"hoval","crime",libsizes = seq(5,45,5),E = 6,k = 9)
plot(g)

optimal parameter search for intersection cardinality

Description

optimal parameter search for intersection cardinality

Usage

## S4 method for signature 'sf'
ic(
  data,
  column,
  target,
  E = 2:10,
  k = E + 2,
  tau = 1,
  style = 1,
  lib = NULL,
  pred = NULL,
  dist.metric = "L2",
  threads = detectThreads(),
  detrend = FALSE,
  nb = NULL
)

## S4 method for signature 'SpatRaster'
ic(
  data,
  column,
  target,
  E = 2:10,
  k = E + 2,
  tau = 1,
  style = 1,
  lib = NULL,
  pred = NULL,
  dist.metric = "L2",
  threads = detectThreads(),
  detrend = FALSE,
  grid.coord = TRUE
)

Arguments

Value

A list

xmap

cross mapping performance

varname

name of target variable

method

method of cross mapping

References

Tao, P., Wang, Q., Shi, J., Hao, X., Liu, X., Min, B., Zhang, Y., Li, C., Cui, H., Chen, L., 2023. Detecting dynamical causality by intersection cardinal concavity. Fundamental Research.

Examples

columbus = sf::read_sf(system.file("case/columbus.gpkg",package="spEDM"))

ic(columbus,"hoval","crime",E = 7,k = 15:25)

multiview embedding forecast

Description

multiview embedding forecast

Usage

## S4 method for signature 'sf'
multiview(
  data,
  column,
  target,
  nvar,
  E = 3,
  k = E + 2,
  tau = 1,
  style = 1,
  stack = FALSE,
  lib = NULL,
  pred = NULL,
  dist.metric = "L2",
  dist.average = TRUE,
  top = NULL,
  threads = detectThreads(),
  detrend = TRUE,
  nb = NULL
)

## S4 method for signature 'SpatRaster'
multiview(
  data,
  column,
  target,
  nvar,
  E = 3,
  k = E + 2,
  tau = 1,
  style = 1,
  stack = FALSE,
  lib = NULL,
  pred = NULL,
  dist.metric = "L2",
  dist.average = TRUE,
  top = NULL,
  threads = detectThreads(),
  detrend = TRUE,
  grid.coord = TRUE
)

Arguments

Value

A vector (when input is sf object) or matrix

References

Ye H., and G. Sugihara, 2016. Information leverage in interconnected ecosystems: Overcoming the curse of dimensionality. Science 353:922-925.

Examples

columbus = sf::read_sf(system.file("case/columbus.gpkg",package="spEDM"))

multiview(columbus,
          column = c("inc","crime","open","plumb","discbd"),
          target = "hoval", nvar = 3)

optimal parameter search for pattern causality

Description

optimal parameter search for pattern causality

Usage

## S4 method for signature 'sf'
pc(
  data,
  column,
  target,
  E = 2:10,
  k = E + 2,
  tau = 1,
  style = 1,
  lib = NULL,
  pred = NULL,
  dist.metric = "L2",
  zero.tolerance = max(k),
  relative = TRUE,
  weighted = TRUE,
  maximize = "positive",
  threads = detectThreads(),
  detrend = FALSE,
  nb = NULL
)

## S4 method for signature 'SpatRaster'
pc(
  data,
  column,
  target,
  E = 2:10,
  k = E + 2,
  tau = 1,
  style = 1,
  lib = NULL,
  pred = NULL,
  dist.metric = "L2",
  zero.tolerance = max(k),
  relative = TRUE,
  weighted = TRUE,
  maximize = "positive",
  threads = detectThreads(),
  detrend = FALSE,
  grid.coord = TRUE
)

Arguments

Value

A list

xmap

cross mapping performance

varname

name of target variable

method

method of cross mapping

maximize

maximized causality metric

References

Stavroglou, S.K., Pantelous, A.A., Stanley, H.E., Zuev, K.M., 2020. Unveiling causal interactions in complex systems. Proceedings of the National Academy of Sciences 117, 7599–7605.

Examples

columbus = sf::read_sf(system.file("case/columbus.gpkg",package="spEDM"))

pc(columbus,"hoval","crime",E = 5:10,maximize = "negative")

spatial causality test

Description

spatial causality test

Usage

## S4 method for signature 'sf'
sc.test(
  data,
  cause,
  effect,
  k,
  block = 3,
  boot = 399,
  seed = 42,
  base = 2,
  lib = NULL,
  pred = NULL,
  threads = detectThreads(),
  detrend = TRUE,
  normalize = FALSE,
  progressbar = FALSE,
  nb = NULL
)

## S4 method for signature 'SpatRaster'
sc.test(
  data,
  cause,
  effect,
  k,
  block = 3,
  boot = 399,
  seed = 42,
  base = 2,
  lib = NULL,
  pred = NULL,
  threads = detectThreads(),
  detrend = TRUE,
  normalize = FALSE,
  progressbar = FALSE,
  grid.coord = TRUE
)

Arguments

Value

A list

sc

statistic for spatial causality

varname

names of causal and effect variables

References

Herrera, M., Mur, J., & Ruiz, M. (2016). Detecting causal relationships between spatial processes. Papers in Regional Science, 95(3), 577–595.

Examples

columbus = sf::read_sf(system.file("case/columbus.gpkg",package="spEDM"))

sc.test(columbus,"hoval","crime",k = 15)

optimal parameter search for simplex forecasting

Description

optimal parameter search for simplex forecasting

Usage

## S4 method for signature 'sf'
simplex(
  data,
  column,
  target,
  E = 2:10,
  k = E + 2,
  tau = 1,
  style = 1,
  stack = FALSE,
  lib = NULL,
  pred = NULL,
  dist.metric = "L2",
  dist.average = TRUE,
  threads = detectThreads(),
  detrend = TRUE,
  nb = NULL
)

## S4 method for signature 'SpatRaster'
simplex(
  data,
  column,
  target,
  E = 2:10,
  k = E + 2,
  tau = 1,
  style = 1,
  stack = FALSE,
  lib = NULL,
  pred = NULL,
  dist.metric = "L2",
  dist.average = TRUE,
  threads = detectThreads(),
  detrend = TRUE,
  grid.coord = TRUE,
  embed.direction = 0
)

Arguments

Value

A list

xmap

forecast performance

varname

name of target variable

method

method of cross mapping

References

Sugihara G. and May R. 1990. Nonlinear forecasting as a way of distinguishing chaos from measurement error in time series. Nature, 344:734-741.

Examples

columbus = sf::read_sf(system.file("case/columbus.gpkg",package="spEDM"))

simplex(columbus,"inc","crime")

spatial logistic map

Description

spatial logistic map

Usage

## S4 method for signature 'sf'
slm(
  data,
  x = NULL,
  y = NULL,
  z = NULL,
  k = 4,
  step = 15,
  alpha_x = 0.28,
  alpha_y = 0.25,
  alpha_z = 0.22,
  beta_xy = 0.05,
  beta_xz = 0.05,
  beta_yx = 0.2,
  beta_yz = 0.2,
  beta_zx = 0.35,
  beta_zy = 0.35,
  threshold = Inf,
  transient = 1,
  interact = "local",
  aggregate_fn = NULL,
  nb = NULL
)

## S4 method for signature 'SpatRaster'
slm(
  data,
  x = NULL,
  y = NULL,
  z = NULL,
  k = 4,
  step = 15,
  alpha_x = 0.28,
  alpha_y = 0.25,
  alpha_z = 0.22,
  beta_xy = 0.05,
  beta_xz = 0.05,
  beta_yx = 0.2,
  beta_yz = 0.2,
  beta_zx = 0.35,
  beta_zy = 0.35,
  threshold = Inf,
  transient = 1,
  interact = "local",
  aggregate_fn = NULL
)

Arguments

Value

A list

References

Willeboordse, F.H., The spatial logistic map as a simple prototype for spatiotemporal chaos, Chaos, 533–540 (2003).

Examples

columbus = sf::read_sf(system.file("case/columbus.gpkg",package="spEDM"))
columbus$inc = sdsfun::normalize_vector(columbus$inc)
slm(columbus,"inc")

optimal parameter search for smap forecasting

Description

optimal parameter search for smap forecasting

Usage

## S4 method for signature 'sf'
smap(
  data,
  column,
  target,
  E = 3,
  k = E + 2,
  tau = 1,
  style = 1,
  stack = FALSE,
  lib = NULL,
  pred = NULL,
  dist.metric = "L2",
  dist.average = TRUE,
  theta = c(0, 1e-04, 3e-04, 0.001, 0.003, 0.01, 0.03, 0.1, 0.3, 0.5, 0.75, 1, 1.5, 2, 3,
    4, 6, 8),
  threads = detectThreads(),
  detrend = TRUE,
  nb = NULL
)

## S4 method for signature 'SpatRaster'
smap(
  data,
  column,
  target,
  E = 3,
  k = E + 2,
  tau = 1,
  style = 1,
  stack = FALSE,
  lib = NULL,
  pred = NULL,
  dist.metric = "L2",
  dist.average = TRUE,
  theta = c(0, 1e-04, 3e-04, 0.001, 0.003, 0.01, 0.03, 0.1, 0.3, 0.5, 0.75, 1, 1.5, 2, 3,
    4, 6, 8),
  threads = detectThreads(),
  detrend = TRUE,
  grid.coord = TRUE,
  embed.direction = 0
)

Arguments

Value

A list

xmap

forecast performance

varname

name of target variable

method

method of cross mapping

References

Sugihara G. 1994. Nonlinear forecasting for the classification of natural time series. Philosophical Transactions: Physical Sciences and Engineering, 348 (1688):477-495.

Examples

columbus = sf::read_sf(system.file("case/columbus.gpkg",package="spEDM"))

smap(columbus,"inc","crime",E = 5,k = 6)