Package 'spatgeom'

CSR Hypothesis Testing for a spatgeom object

Description

Performs a global envelope test for Complete Spatial Randomness (CSR) on a spatgeom object that was computed with envelope = TRUE. Two test statistics are supported: Maximum Absolute Deviation (MAD) and Diggle-Cressie-Loosmore-Ford (DCLF).

Usage

csr_test(
  spatgeom_obj,
  significance_level = 0.05,
  r = 0.5,
  method = c("MAD", "DCLF")
)

Arguments

spatgeom_obj	an object of class spatgeom computed with envelope = TRUE.
significance_level	a numeric value for the significance level of the test. Default 0.05. Currently used for documentation purposes; the p-value is computed from the Monte Carlo rank.
r	a numeric scaling parameter used in the theoretical CSR curve $\exp(-\lambda \pi (\alpha r)^2)$. Should match the value used when calling spatgeom. Default 0.5.
method	a character string, one of "MAD" (Maximum Absolute Deviation) or "DCLF" (Diggle-Cressie-Loosmore-Ford), specifying the global envelope test statistic. Default "MAD".

Value

A named list with two elements:

hypothesis_testing_df

A data frame (one row per alpha value per variable) with columns x (alpha grid), mean (mean of simulated CSR curves), alpha, geom_survival (observed), theor (theoretical CSR curve), upper_mean, lower_mean (confidence band around the mean curve), upper_theor, lower_theor (confidence band around the theoretical curve), and variable.

details

A named list, one entry per variable, each a data frame summarising the test: null hypothesis, variable name, test type, number of Monte Carlo simulations, observed and maximum test statistics, and p-values against both the mean and theoretical reference curves.

Examples

xy <- donut_data(n = 30, a = -1, b = 1, theta = 2 * pi)

# Compute a spatgeom object with the Monte Carlo envelope:
est <- spatgeom(y = xy[, 1], x = xy[, -1], envelope = TRUE)

# Test with the MAD (Maximum Absolute Deviation) statistic:
result_mad <- csr_test(est, method = "MAD")
result_mad$details

# Test with the DCLF statistic:
result_dclf <- csr_test(est, method = "DCLF")
result_dclf$details

---

Donut example

Description

Generate data points with the shape of a donut.

Usage

donut_data(n, a, b, theta)

Arguments

n	Number of data points.
a	Lower bound of the second variable.
b	Upper bound of the second variable.
theta	Angle of the donut.

Value

A data frame with three variables. Variable 'y' is the response, variable 'x1' makes the donut shape with 'y', and 'x2' is a uniform random variable between a and b. '

Examples

xy <- donut_data(n = 30, a = -1, b = 1, theta = 2 * pi)

---

Linear example

Description

Generate data points with a linear relationship.

Usage

linear_data(n = 100, a = -3, b = 3)

Arguments

n	Number of data points.
a, b	Lower and upper bound of the uniform distribution.

Value

A data frame with four variables. Variable y = 0.6 * x1 + 0.3 * x2 + 0.1 * x3 is the response, and x1, x2 and x3 are independent uniform random variables between a and b.

Examples

xy <- linear_data(n = 30, a = -1, b = 1)

---

Plot alpha-shape for spatgeom objects

Description

Plot alpha-shape for spatgeom objects.

Usage

plot_alpha_shape(x, alpha, font_size = 12)

Arguments

x	an object of class spatgeom.
alpha	value of alpha determining the maximum length between points to build the alpha-shape.
font_size	a integer that increases the font size in the plot.

Value

a ggplot object with the raw alpha-shape for the original data at resolution alpha

Examples

xy <- donut_data(n = 30, a = -1, b = 1, theta = 2 * pi)

estimation <- spatgeom(y = xy[, 1], x = xy[, -1])

plot_alpha_shape(estimation, alpha = c(0.9, 1.2))

---

plot spatgeom objects with hypothesis testing results and confidence intervals

Description

S3 generic for plotting spatial geometry analysis results. Dispatches to plot_curve.spatgeom for spatgeom objects (producing a ggplot of survival curves or their derivatives), and to plot_curve.spatgeom_group for spatgeom_group objects (producing a side-by-side cowplot grid, one panel per group).

Usage

plot_curve(x, ...)

## S3 method for class 'spatgeom'
plot_curve(x, type = "curve", font_size = 12, ...)

Arguments

x	an object of class spatgeom or spatgeom_group.
...	further arguments passed to the appropriate method.
type	a string: either "curve" (the default) or "deriv". The option "curve" plots the survival curve (with envelopes and, if available, confidence intervals). The option "deriv" plots its numerical derivative.
font_size	an integer controlling the font size in the plot.

Value

a ggplot object for spatgeom inputs, or a cowplot grid for spatgeom_group inputs.

Examples

xy <- donut_data(n = 30, a = -1, b = 1, theta = 2 * pi)

# Basic plots — no envelope, no hypothesis testing:
estimation <- spatgeom(y = xy[, 1], x = xy[, -1])
plot_curve(estimation, type = "curve")
plot_curve(estimation, type = "deriv")


# Curve with Monte Carlo envelope ribbon (grey) and theoretical CSR curve
# (red dashed):
est_env <- spatgeom(y = xy[, 1], x = xy[, -1], envelope = TRUE)
plot_curve(est_env, type = "curve")

# Curve with hypothesis testing results: additionally shows the CSR mean
# (blue dotted) and its confidence band (blue ribbon):
est_ht <- spatgeom(
  y = xy[, 1], x = xy[, -1],
  hypothesis_testing = TRUE, method = "MAD"
)
plot_curve(est_ht, type = "curve")

---

Plot a spatgeom_group object

Description

Plot method for objects of class spatgeom_group. Produces a side-by-side grid of survival curve (or derivative) panels, one column per group.

Usage

## S3 method for class 'spatgeom_group'
plot_curve(x, type = "curve", font_size = 12, ...)

Arguments

x	an object of class spatgeom_group.
type	a string: either "curve" (default) or "deriv". Passed to plot_curve.spatgeom for each group.
font_size	an integer controlling the font size. Default 12.
...	further arguments passed to plot_curve.spatgeom.

Value

A cowplot grid object (produced by cowplot::plot_grid).

See Also

spatgeom_group, plot_curve

Examples

set.seed(1)
xy <- donut_data(n = 60, a = -1, b = 1, theta = 2 * pi)
grp <- sample(c("A", "B", "C"), nrow(xy), replace = TRUE)
sg <- spatgeom_group(x = xy[, -1], by = grp, y = xy[, 1])
plot_curve(sg)
plot_curve(sg, type = "deriv")

---

print a spatgeom object

Description

Print method for objects of class spatgeom.

Usage

## S3 method for class 'spatgeom'
print(x, return_table = FALSE, ...)

Arguments

x	an object of class spatgeom
return_table	if TRUE, returns a data frame with the estimated values. Otherwise, print the data frame in console. Defaults to FALSE
...	further arguments passed to the plot function

Value

Print the estimate given by spatgeom.

Examples

xy <- donut_data(n = 30, a = -1, b = 1, theta = 2 * pi)

# Basic print — shows alpha and geom_survival ranges per variable:
estimation <- spatgeom(y = xy[, 1], x = xy[, -1])
print(estimation)


# Print a spatgeom object that includes hypothesis testing results:
est_ht <- spatgeom(
  y = xy[, 1], x = xy[, -1],
  hypothesis_testing = TRUE, method = "MAD"
)
print(est_ht)

# Return the underlying data frame instead of printing:
tbl <- print(est_ht, return_table = TRUE)
head(tbl)

---

Print a spatgeom_group object

Description

Print method for objects of class spatgeom_group. Displays a summary for each group in turn.

Usage

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

Arguments

x	an object of class spatgeom_group.
...	further arguments passed to print.spatgeom.

Value

x invisibly.

See Also

spatgeom_group, print.spatgeom

Examples

set.seed(1)
xy <- donut_data(n = 60, a = -1, b = 1, theta = 2 * pi)
grp <- sample(c("A", "B", "C"), nrow(xy), replace = TRUE)
sg <- spatgeom_group(x = xy[, -1], by = grp, y = xy[, 1])
print(sg)

---

Dimensionality Reduction for Spatial Geometry Analysis

Description

Reduce an $n \times p$ matrix to $n \times d$ (d = n_components, typically 2) using a choice of static embedding methods. The result can be passed directly to spatgeom or spatgeom_group when the original feature matrix has more than 2 columns.

Usage

reduce_dim(x, method = c("pca", "umap", "tsne"), n_components = 2L, ...)

Arguments

x	a numeric matrix or data frame with $n$ rows and $p$ columns. For method = "pca", $p \ge d$ is required; for "umap" and "tsne", n_components may exceed ncol(x).
method	character; the reduction method. One of: "pca" Principal Component Analysis via prcomp. No extra package required. "umap" Uniform Manifold Approximation and Projection via uwot::umap. Requires the uwot package. "tsne" t-distributed Stochastic Neighbour Embedding via Rtsne::Rtsne. Requires the Rtsne package.
n_components	integer; number of output dimensions. Default 2L.
...	additional arguments forwarded to the underlying reduction function (prcomp, uwot::umap, or Rtsne::Rtsne).

Value

A numeric matrix with nrow(x) rows and n_components columns. Column names are Dim_1, Dim_2, etc.

See Also

spatgeom, spatgeom_group

Examples

set.seed(1)
xy <- donut_data(n = 50, a = -1, b = 1, theta = 2 * pi)

# PCA — no extra packages needed
emb <- reduce_dim(xy[, -1], method = "pca")
dim(emb) # 50 x 2


# UMAP — requires uwot
if (requireNamespace("uwot", quietly = TRUE)) {
  emb_umap <- reduce_dim(xy[, -1], method = "umap")
  dim(emb_umap)
}

# t-SNE — requires Rtsne; perplexity must be < n/3
if (requireNamespace("Rtsne", quietly = TRUE)) {
  emb_tsne <- reduce_dim(xy[, -1], method = "tsne", perplexity = 10)
  dim(emb_tsne)
}

---

Geometric Spatial Point Pattern Analysis

Description

Function to estimate the geometric correlation between variables.

Usage

spatgeom(
  x,
  y,
  scale_pts = FALSE,
  nalphas = 100,
  envelope = FALSE,
  domain_type = c("bounding-box", "convex-hull"),
  hypothesis_testing = FALSE,
  significance_level = 0.05,
  mc_cores = 1,
  r = 0.5,
  method = c("MAD", "DCLF"),
  reduce = c("none", "pca", "umap", "tsne"),
  reduce_args = list()
)

Arguments

x	numeric matrix or data.frame. Either a matrix of covariables (paired with y), or a single $n \times p$ matrix when y is omitted. In the latter case x must have at least 2 columns: if exactly 2, they are used directly as 2D coordinates; if more than 2, set reduce = "pca", "umap", or "tsne" to project to 2D first.
y	numeric vector of responses. Optional: when omitted, x is treated as a single point cloud (see reduce).
scale_pts	boolean to make the estimations with scaled variables. Default FALSE.
nalphas	number of alphas generated for creating the geometric measure of fit index. Default 100.
envelope	boolean to determine if the Monte-Carlo should be estimated. Default FALSE.
domain_type	character with the type of domain to use. It can be either "bounding-box" or "convex-hull". Default "bounding-box".
hypothesis_testing	logical. If TRUE, performs a CSR hypothesis test using a global envelope approach after estimating the geometric survival curves. Automatically sets envelope = TRUE. Default FALSE.
significance_level	a numeric significance level passed to csr_test. Default 0.05.
mc_cores	integer with the number of parallel process to run (if available). Default 1.
r	numeric scaling parameter for the theoretical CSR curve used in csr_test: $\exp(-\lambda \pi (\alpha r)^2)$. Default 0.5.
method	character, one of "MAD" (Maximum Absolute Deviation) or "DCLF" (Diggle-Cressie-Loosmore-Ford). Specifies the global envelope test statistic passed to csr_test. Default "MAD".
reduce	character; dimensionality reduction method to apply when x has more than 2 columns. One of "none" (default, keeps all columns and pairs each with y as separate variables), "pca" (Principal Component Analysis, no extra package required), "umap" (requires uwot), or "tsne" (requires Rtsne). When reduce != "none", x is projected to 2 dimensions via reduce_dim before the analysis.
reduce_args	a named list of additional arguments forwarded to reduce_dim (and in turn to the underlying method). For example, list(n_neighbors = 30) when reduce = "umap". Default list().

Value

A list of class spatgeom with the following elements:

call

The function call.

x

x input.

y

y output.

results

A list of size ncol(x) corresponding to each column of x. Each element of the list has:

triangles

a data frame of class sfc (see sf::st_sf())with columns geometry, segments, max_length and alpha. The data.frame contains the whole Delanauy triangulation for the corresponding column of x and y. The segments column are the segments of each individual triangle and max_length is the maximum length of them.

geom_indices

a data frame with columns alpha and geom_survival. The alpha column is a numeric vector of size nalphas from the minimum to the maximum distance between points estimated in the data. The geom_survival column is the value 1 - (alpha shape Area)/(containing box Area).

intensity

the intensity estimated for the corresponding column of x and y.

mean_n

the mean number of points in the point process.

envelope_data

a data frame in tidy format with 40 runs of a CSR process, if envelope=TRUE, The CSR is created by generating n uniform points in the plane, where n is drawn from Poisson distribution with parameter mean_n.

hypothesis_testing_results

Only present when hypothesis_testing = TRUE. A list returned by csr_test with elements hypothesis_testing_df (a data frame of test statistics and confidence bands for all variables) and details (per-variable summary tables of the test results).

reduce_embedding

Only present when reduce != "none" and x had more than 2 columns. The $n \times 2$ numeric matrix produced by reduce_dim, whose columns were used as the 2D point cloud.

References

Hernández, A.J., Solís, M. Geometric goodness of fit measure to detect patterns in data point clouds. Comput Stat (2022). https://doi.org/10.1007/s00180-022-01244-1

Examples

xy <- donut_data(n = 30, a = -1, b = 1, theta = 2 * pi)

# Basic usage: estimate the geometric survival curves only.
estimation <- spatgeom(y = xy[, 1], x = xy[, -1])
print(estimation)


# With Monte Carlo envelope (takes a few seconds):
est_env <- spatgeom(y = xy[, 1], x = xy[, -1], envelope = TRUE)
plot_curve(est_env, type = "curve")

# With integrated CSR hypothesis testing using the MAD statistic:
est_ht <- spatgeom(
  y = xy[, 1], x = xy[, -1],
  hypothesis_testing = TRUE,
  method = "MAD"
)
print(est_ht)
plot_curve(est_ht, type = "curve")

# Inspect the per-variable test results:
est_ht$hypothesis_testing_results$details

# Wide matrix: reduce to 2D with PCA before running the analysis:
est_pca <- spatgeom(y = xy[, 1], x = xy[, -1], reduce = "pca")
plot_curve(est_pca, type = "curve")

# Wide matrix: reduce with UMAP (requires the 'uwot' package):
if (requireNamespace("uwot", quietly = TRUE)) {
  est_umap <- spatgeom(y = xy[, 1], x = xy[, -1], reduce = "umap")
  plot_curve(est_umap, type = "curve")
}

---

Geometric Spatial Point Pattern Analysis by Group

Description

Apply spatgeom independently to each level of a grouping variable. The result is an object of class spatgeom_group that bundles the per-group spatgeom objects and supports print and plot_curve methods for side-by-side comparison.

Usage

spatgeom_group(x, by, ...)

Arguments

x	a numeric matrix or data frame of covariates (passed as the x argument of spatgeom). Rows correspond to observations.
by	a vector of group labels with the same length as nrow(x). Can be a character vector, factor, or any vector that can be coerced to character. Each unique value defines one group.
...	additional arguments forwarded verbatim to spatgeom for every group. This includes y, nalphas, domain_type, envelope, hypothesis_testing, method, reduce, reduce_args, mc_cores, etc. The subset of x rows belonging to each group is passed automatically; do not pass x again inside ....

Details

When y is supplied via ..., the corresponding rows of y are subsetted to match each group. When y is absent, each group's subset of x is treated as a 2-D point cloud (or reduced according to reduce with options supplied via reduce_args).

Groups are processed in the order returned by unique(by), which preserves the order of first appearance in by.

Value

An object of class spatgeom_group, which is a list with:

call

The matched function call.

groups

Character vector of unique group labels in appearance order.

results

Named list of spatgeom objects, one per group. Names match groups.

See Also

spatgeom, plot_curve, print.spatgeom_group

Examples

set.seed(1)
xy <- donut_data(n = 60, a = -1, b = 1, theta = 2 * pi)
grp <- sample(c("A", "B", "C"), nrow(xy), replace = TRUE)

sg <- spatgeom_group(x = xy[, -1], by = grp, y = xy[, 1])
print(sg)
plot_curve(sg)


# With hypothesis testing per group (slow — runs Monte Carlo per group):
sg_ht <- spatgeom_group(
  x = xy[, -1], by = grp, y = xy[, 1],
  hypothesis_testing = TRUE, method = "MAD"
)
plot_curve(sg_ht, type = "curve")

---