Title:	Spatial Dependence for Simple Features
Version:	0.2.5
Description:	An interface to 'spdep' to integrate with 'sf' objects and the 'tidyverse'.
License:	GPL-3
URL:	https://sfdep.josiahparry.com, https://github.com/josiahparry/sfdep
Suggests:	broom, dbscan, dplyr, ggplot2, knitr, magrittr, patchwork, purrr, pracma, rmarkdown, sfnetworks, stringr, testthat (≥ 3.0.0), tibble, tidyr, vctrs, yaml, zoo, Kendall, igraph, tidygraph
Config/testthat/edition:	3
Encoding:	UTF-8
RoxygenNote:	7.3.2
Imports:	sf, cli, spdep, stats, rlang
Depends:	R (≥ 3.5.0)
LazyData:	true
NeedsCompilation:	no
Packaged:	2024-09-12 21:29:43 UTC; dlocke
Author:	Josiah Parry [aut], Dexter Locke [aut, cre]
Maintainer:	Dexter Locke <dexter.locke@gmail.com>
Repository:	CRAN
Date/Publication:	2024-09-13 12:00:05 UTC

Activate spacetime context

Description

From a spacetime object, activate either the data or geometry contexts. The active object will then become available for manipulation.

Usage

active(.data)

activate(.data, what)

Arguments

Details

A spacetime object contains both a data frame and an sf object. The data frame represents geographies over one or more time periods and the sf object contains the geographic information for those locations.

Value

For activate() an object of class spacetime with the specified context activated. active() returns a scalar character with the active context can be either "goemetry" or "data".

Examples

df_fp <- system.file("extdata", "bos-ecometric.csv", package = "sfdep")
geo_fp <- system.file("extdata", "bos-ecometric.geojson", package = "sfdep")

# read in data
df <- read.csv(
  df_fp, colClasses = c("character", "character", "integer", "double", "Date")
)
geo <- sf::st_read(geo_fp)

# Create spacetime object called `bos`
bos <- spacetime(df, geo,
                 .loc_col = ".region_id",
                 .time_col = "time_period")

active(bos)
activate(bos, "geometry")

Cast between spacetime and sf classes

Description

Cast between spacetime and sf classes

Convert sf object to spacetime

Usage

as_sf(x, ...)

as_spacetime(x, .loc_col, .time_col, ...)

## S3 method for class 'sf'
as_spacetime(x, .loc_col, .time_col, ...)

Arguments

Value

For as_spacetime() returns a spacetime object. For as_sf(), an sf object.

Examples

if (require(dplyr, quietly = TRUE)) {
  df_fp <- system.file("extdata", "bos-ecometric.csv", package = "sfdep")
  geo_fp <- system.file("extdata", "bos-ecometric.geojson", package = "sfdep")

  # read in data
  df <- read.csv(
    df_fp, colClasses = c("character", "character", "integer", "double", "Date")
  )
  geo <- sf::st_read(geo_fp)

  # Create spacetime object called `bos`
  bos <- spacetime(df, geo,
                   .loc_col = ".region_id",
                   .time_col = "time_period")

  as_sf(bos)
  if (require("dplyr", quietly=TRUE)) {
    as_spacetime(as_sf(bos) , ".region_id", "year")
  }
}

Calculate Center Mean Point

Description

Given an sfc object containing points, calculate a measure of central tendency.

Usage

center_mean(geometry, weights = NULL)

center_median(geometry)

euclidean_median(geometry, tolerance = 1e-09)

Arguments

Details

• center_mean() calculates the mean center of a point pattern

• euclidean_median() calculates the euclidean median center of a point pattern using the pracma package

• center_median() calculates the median center it is recommended to use the euclidean median over the this function.

Value

an sfc POINT object

See Also

Other point-pattern: std_distance()

Other point-pattern: std_distance()

Examples

if (requireNamespace("pracma")) {

# Make a grid to sample from
grd <- sf::st_make_grid(n = c(1, 1), cellsize = c(100, 100), offset = c(0,0))

# sample 100 points
pnts <- sf::st_sample(grd, 100)

cm <- center_mean(pnts)
em <- euclidean_median(pnts)
cmed <- center_median(pnts)

plot(pnts)
plot(cm, col = "red", add = TRUE)
plot(em, col = "blue", add = TRUE)
plot(cmed, col = "green", add = TRUE)
}

Check if a vector of packages are available

Description

Check if a vector of packages are available

Usage

check_pkg_suggests(x)

Arguments

Checks geometry for polygons.

Description

If the provided geometry is a polygon, a point will be generated using sf::st_point_on_surface(). If a centroid is preferred, a new column can be created that contains the output of sf::st_centroid().

Usage

check_polygon(geometry)

Arguments

Value

Point geometry

Modify object classes

Description

Appends classes to exist object classes. This is utilized to aid in adding a list class to objects created by spdep. This enables to use of the returned objects within data frames and tibbles.

Usage

class_modify(x, class = "list")

Arguments

Classify Hot Spot results

Description

Given the Gi* time-series and Mann Kendall scores classify the hotspot values

Usage

classify_hotspot(.x, threshold)

Convert spacetime object to spacetime cube

Description

Given a spacetime object, convert it to a spacetime cube. A spacetime cube ensures that there is a regular time-series for each geometry present.

Usage

complete_spacetime_cube(x, ...)

Arguments

Details

If observations are missing for a time period and location combination, columns will be populated with NAs.

See is_spacetime_cube() for more details on spacetime cubes.

Value

A spacetime object that meets the criteria of spacetime cube.

Examples

df_fp <- system.file("extdata", "bos-ecometric.csv", package = "sfdep")
geo_fp <- system.file("extdata", "bos-ecometric.geojson", package = "sfdep")

# read in data
df <- read.csv(df_fp, colClasses = c("character", "character", "integer", "double", "Date"))
geo <- sf::st_read(geo_fp)

# Create spacetime object called `bos`
bos <- spacetime(df, geo,
                 .loc_col = ".region_id",
                 .time_col = "time_period")

# create a sample of data
set.seed(0)
sample_index <- sample(1:nrow(bos), nrow(bos) * 0.95)
incomplete_spt <- bos[sample_index,]

# check to see if is spacetime cube
is_spacetime_cube(incomplete_spt)

# complete it again
complete_spacetime_cube(incomplete_spt)

Conditional permutation of neighbors

Description

Creates a conditional permutation of neighbors list holding i fixed and shuffling it's neighbors.

Usage

cond_permute_nb(nb, seed = NULL)

Arguments

Value

A list of class nb where each element contains a random sample of neighbors excluding the observed region.

Examples

nb <- st_contiguity(guerry)
nb[1:5]
# conditionally permute neighbors
perm_nb <- cond_permute_nb(nb)
perm_nb[1:5]

Identify critical threshold

Description

Identifies the minimum distance in which each observation will have at least one neighbor.

Usage

critical_threshold(geometry, k = 1)

Arguments

Value

a numeric scalar value.

Examples

critical_threshold(sf::st_geometry(guerry))

Create an Ellipse

Description

Generate an ellipse from center coordinates, major and minor axis radii, and angle rotation.

Usage

ellipse(x = 0, y = 0, sx = 2, sy = 1, rotation = 0, n = 100)

st_ellipse(geometry, sx, sy, rotation = 0, n = 100)

Arguments

Details

ellipse() returns a matrix of point locations defining the ellipse. st_ellipse() returns an sf object with LINE geography of the ellipse. Increasing n increases the number of points generated to define the ellipse shape.

ellipse() function is adapted from ggVennDiagram.

Value

an sf object

Examples

ellipse(n = 10)
st_ellipse(sf::st_point(c(0, 0)), sx = 10, sy = 10)

Emerging Hot Spot Analysis

Description

Emerging Hot Spot Analysis identifies trends in spatial clustering over a period of time. Emerging hot spot analysis combines the Getis-Ord Gi* statistic with the Mann-Kendall trend test to determine if there is a temporal trend associated with local clustering of hot and cold spots.

Usage

emerging_hotspot_analysis(
  x,
  .var,
  k = 1,
  include_gi = FALSE,
  nb_col = NULL,
  wt_col = NULL,
  nsim = 199,
  threshold = 0.01,
  ...
)

Arguments

Details

How Emerging Hot Spot Analysis Works

Emerging Hot Spot Analysis is a somewhat simple process. It works by first calculating the Gi* statistic for each location in each time period (time-slice). Next, for each location across all time-periods, the Mann-Kendall trend test is done to identify any temporal trend in Gi* values over all time periods. Additionally, each location is classified into one of seventeen categories based on ESRI's emerging hot spot classification criteria.

The Mann-Kendall trend test is done using Kendall::MannKendall(). Kendall is not installed with sfdep and should be installed prior to use.

Using your own neighbors and weights

If you would like to use your own neighbors and weights, they must be created in the geometry context of a spacetime object. The arguments nb_col and wt_col must both be populated in order to use your own neighbor and weights definitions.

Time lagged neighbors

In addition to identifying neighbors in space, emerging hotspot analysis also incorporates the same observations from k periods ago-called a time lag. If the time lag k is 1 and the unit of time is month, the neighbors for the calculation of Gi* would include the spatial neighbors' values at time t and the same spatial neighbors' values at time t-1. If k = 2, it would include t, t-1, and t-2.

Missing values

Presently, there is no method of missing value handling. If there are missing values, the emerging hot spot analysis will fail. Be sure to fill or omit time-slices with missing values prior to using emerging hot spot analysis.

Value

Returns a data.frame.

See Also

How Emerging Hot Spot Analysis works, Emerging Hot Spot Analysis (Space Time Pattern Mining), and the video Spatial Data Mining II: A Deep Dive into Space-Time Analysis by ESRI.

Examples

if (requireNamespace("Kendall")) {
df_fp <- system.file("extdata", "bos-ecometric.csv", package = "sfdep")
geo_fp <- system.file("extdata", "bos-ecometric.geojson", package = "sfdep")

# read in data
df <- read.csv(df_fp, colClasses = c("character", "character", "integer", "double", "Date"))
geo <- sf::st_read(geo_fp)

# Create spacetime object called `bos`
bos <- spacetime(df, geo,
                 .loc_col = ".region_id",
                 .time_col = "time_period")


# conduct EHSA
ehsa <- emerging_hotspot_analysis(
  x = bos,
  .var = "value",
  k = 1,
  nsim = 9
)

ehsa
}

Identify xj values

Description

Find xj values given a numeric vector, x, and neighbors list, nb.

Usage

find_xj(x, nb)

Arguments

Value

A list of length x where each element is a numeric vector with the same length as the corresponding element in nb.

Examples

nb <- st_contiguity(sf::st_geometry(guerry))
xj <- find_xj(guerry$crime_prop, nb)
xj[1:3]

Compute Geary's C

Description

Compute Geary's C

Usage

global_c(x, nb, wt, allow_zero = NULL)

Arguments

Value

a list with two names elements C and K returning the value of Geary's C and sample kurtosis respectively.

See Also

Other global_c: global_c_perm(), global_c_test()

Examples

nb <- guerry_nb$nb
wt <- guerry_nb$wt
x <- guerry_nb$crime_pers
global_c(x, nb, wt)

Global C Permutation Test

Description

Global C Permutation Test

Usage

global_c_perm(
  x,
  nb,
  wt,
  nsim = 499,
  alternative = "greater",
  allow_zero = NULL,
  ...
)

Arguments

Value

an object of classes htest and mc.sim

See Also

Other global_c: global_c(), global_c_test()

Examples

geo <- sf::st_geometry(guerry)
nb <- st_contiguity(geo)
wt <- st_weights(nb)
x <- guerry$crime_pers
global_c_perm(x, nb, wt)

Global C Test

Description

Global C Test

Usage

global_c_test(x, nb, wt, randomization = TRUE, allow_zero = NULL, ...)

Arguments

Value

an htest object

See Also

Other global_c: global_c(), global_c_perm()

Examples

geo <- sf::st_geometry(guerry)
nb <- st_contiguity(geo)
wt <- st_weights(nb)
x <- guerry$crime_pers
global_c_test(x, nb, wt)

Global Colocation Quotient

Description

Calculate the Global Colocation Quotient (CLQ) for a categorical variable using simulation based significance testing.

Usage

global_colocation(A, nb, nsim = 99)

Arguments

Details

Definition

The CLQ is defined as CLQ_{Global} = \frac{\sum_{A \in X} C_{A \to A}}{\sum_{A \in X} N_A ({\frac{N_A - 1}{N-1})}}. The numerator identifies the observed proportion of same-category neighbors while the denominator contains the expected proportion of same-category neighbors under the assumption of no spatial association. Thus the CLQ is just a ratio of observed to expected.

Inference

Inference is done using conditional permutation as suggested by Anselin 1995 where a number of replicates are created. The observed values are compared to the replicates and a the simulated p-value is the proportion of cases where the observed is more extreme as compared to replicate. The simulated p-value returns the lower p-value of either tail.

Interpretation

Given that the CLQ is a ratio of the observed to expected, we interpret values larger than one to mean that there is more colocation than to be expected under the null hypothesis of no spatial association. When the value is smaller than 0, we interpret it to mean that there is less colocation than expected under the null.

Value

A list of two elements CLQ and p_sim containing the observed colocation quotient and the simulated p-value respectively.

References

Leslie, T.F. and Kronenfeld, B.J. (2011), The Colocation Quotient: A New Measure of Spatial Association Between Categorical Subsets of Points. Geographical Analysis, 43: 306-326. doi:10.1111/j.1538-4632.2011.00821.x

Examples

A <- guerry$main_city
nb <- st_contiguity(sf::st_geometry(guerry))
global_colocation(A, nb, 49)

Calculate the Global Colocation Quotient

Description

Given a categorical variable A, calculate the global colocation quotient (CLQ).

Usage

global_colocation_calc(A, nb)

Global Colocation Quotient Conditional Permutation Implementation

Description

This function will repeat calculation of the global colocation quotient (CLQ) a specified number of times and return a simulated p-value.

Usage

global_colocation_perm_impl(A, nb, nsim = 99)

Getis-Ord Global G

Description

Getis-Ord Global G

Usage

global_g_test(x, nb, wt, alternative = "greater", allow_zero = NULL, ...)

Arguments

Value

an htest object

Examples

geo <- sf::st_geometry(guerry)
nb <- st_contiguity(geo)
wt <- st_weights(nb, style = "B")
x <- guerry$crime_pers
global_g_test(x, nb, wt)

Global Join Counts

Description

Calculate global join count measure for a categorical variable.

Usage

global_jc_perm(
  fx,
  nb,
  wt,
  alternative = "greater",
  nsim = 499,
  allow_zero = FALSE,
  ...
)

global_jc_test(fx, nb, wt, alternative = "greater", allow_zero = NULL, ...)

tally_jc(fx, nb, wt, allow_zero = TRUE, ...)

Arguments

Details

• global_jc_perm() implements the monte-carlo based join count using spdep::joincount.mc()

• global_jc_test() implements the traditional BB join count statistic using spdep::joincount.test()

• tally_jc() calculated join counts for a variable fx and returns a data.frame using spdep::joincount.multi()

Value

an object of class jclist which is a list where each element is of class htest and mc.sim.

Examples

geo <- sf::st_geometry(guerry)
nb <- st_contiguity(geo)
wt <- st_weights(nb, style = "B")
fx <- guerry$region
global_jc_perm(fx, nb, wt)

global_jc_test(fx, nb, wt)

tally_jc(fx, nb, wt)

Calculate Global Moran's I

Description

Calculate Global Moran's I

Usage

global_moran(x, nb, wt, na_ok = FALSE, ...)

Arguments

Value

an htest object

See Also

Other global_moran: global_moran_bv(), global_moran_perm(), global_moran_test(), local_moran_bv()

Examples

nb <- guerry_nb$nb
wt <- guerry_nb$wt
x <- guerry_nb$crime_pers
moran <- global_moran(x, nb, wt)

Compute the Global Bivariate Moran's I

Description

Given two continuous numeric variables, calculate the bivariate Moran's I. See details for more.

Usage

global_moran_bv(x, y, nb, wt, nsim = 99, scale = TRUE)

Arguments

Details

The Global Bivariate Moran is defined as

I_B = \frac{\Sigma_i(\Sigma_j{w_{ij}y_j\times x_i})}{\Sigma_i{x_i^2}}

It is important to note that this is a measure of autocorrelation of X with the spatial lag of Y. As such, the resultant measure may overestimate the amount of spatial autocorrelation which may be a product of the inherent correlation of X and Y.

Value

an object of class boot

References

Global Spatial Autocorrelation (2): Bivariate, Differential and EB Rate Moran Scatter Plot, Luc Anselin

See Also

Other global_moran: global_moran(), global_moran_perm(), global_moran_test(), local_moran_bv()

Examples

x <- guerry_nb$crime_pers
y <- guerry_nb$wealth
nb <- guerry_nb$nb
wt <- guerry_nb$wt
global_moran_bv(x, y, nb, wt)

Global Moran Permutation Test

Description

Global Moran Permutation Test

Usage

global_moran_perm(x, nb, wt, alternative = "two.sided", nsim = 499, ...)

Arguments

Value

an object of classes htest, and mc.sim.

See Also

Other global_moran: global_moran(), global_moran_bv(), global_moran_test(), local_moran_bv()

Examples

nb <- guerry_nb$nb
wt <- guerry_nb$wt
x <- guerry_nb$crime_pers
moran <- global_moran_perm(x, nb, wt)
moran

Global Moran Test

Description

Global Moran Test

Usage

global_moran_test(
  x,
  nb,
  wt,
  alternative = "greater",
  randomization = TRUE,
  ...
)

Arguments

Value

an object of class htest

See Also

Other global_moran: global_moran(), global_moran_bv(), global_moran_perm(), local_moran_bv()

Examples

nb <- guerry_nb$nb
wt <- guerry_nb$wt
x <- guerry_nb$crime_pers
global_moran_test(x, nb, wt)

"Essay on the Moral Statistics of France" data set.

Description

This dataset has been widely used to demonstrate geospatial methods and techniques. As such it is useful for inclusion to this R package for the purposes of example. The dataset in this package is modified from Guerry by Michael Friendly.

Usage

guerry

guerry_nb

Format

An object of class sf (inherits from tbl_df, tbl, data.frame) with 85 rows and 27 columns.

guerry an sf object with 85 observations and 27 variables. guerry_nb has 2 additional variables created by sfdep.

Details

guerry and guerry_nb objects are sf class objects. These are polygons of the boundaries of France (excluding Corsica) as they were in 1830.

Source

Guerry::gfrance85

Includes self in neighbor list

Description

Includes observed region in list of own neighbors. For some neighbor lists, it is important to include the ith observation (or self) in the neighbors list, particularly for kernel weights.

Usage

include_self(nb)

remove_self(nb)

Arguments

Value

An object of class nb.

Examples

nb <- st_contiguity(guerry)
self_included <- include_self(nb)
self_included
remove_self(self_included)

Calculate inverse distance weights

Description

Calculate inverse distance weights

Usage

inverse_dist_calc(.x, scale, alpha)

Test if a spacetime object is a spacetime cube

Description

Given an object with class spacetime, determine if it is a spacetime cube. If the time-series is is irregular a warning is emitted (see validate_spacetime() for more on the restrictions on the time column.

Usage

is_spacetime_cube(x, ...)

Arguments

Details

A spacetime object is a spacetime cube when it contains a regular time-series representation of each geometry. That is, only one observation for at each time period per geography is present.

The number of rows in a spacetime cube is the number of geographies multiplied by the number of time periods. For example if there are 10 locations and 20 time periods, the number of rows must be 200.

Value

A logical scalar.

Validation

is_spacetime_cube() runs a number of checks that to ensure that the provided object is in fact a spacetime cube. It checks that:

• the number of rows is equal to the number of locations multiplied by the number of time periods

• each time period has an equal number of observations

• each location has an equal number of observations

• each combination of time period and location has only one observation

• that the time-series is regular

Examples

if (requireNamespace("zoo", quietly = TRUE)) {
df_fp <- system.file("extdata", "bos-ecometric.csv", package = "sfdep")
geo_fp <- system.file("extdata", "bos-ecometric.geojson", package = "sfdep")

# read in data
df <- read.csv(
  df_fp, colClasses = c("character", "character", "integer", "double", "Date")
)
geo <- sf::st_read(geo_fp)

# Create spacetime object called `bos`
bos <- spacetime(df, geo,
                .loc_col = ".region_id",
                .time_col = "time_period")

is_spacetime_cube(bos)
is_spacetime_cube(bos[round(runif(1000, 0, nrow(bos))),])
is_spacetime_cube(guerry)
}

Calculate BJC Bivariate Case

Description

Assumes no colocation

Usage

jc_bjc_calc(x, xj, z, zj, wt)

Calculate BJC BV for conditional permutations

Description

Calculate BJC BV for conditional permutations

Usage

jc_bjc_perm_impl(x, z, listw, index)

Calculate CLC BV for conditional permutations

Description

Calculate CLC BV for conditional permutations

Usage

jc_clc_perm_impl(x, z, listw, index)

Arguments

Kernel functions

Description

Kernel functions for creating kernel based weights with st_kernel_weights()

Usage

kernels

Format

An object of class list of length 5.

Details

Supported kernels are below.

Formulas come from Anselin & Morrison's notes.

• uniform: K(z) = 1/2 for |z|<1

• triangular: K(z) = (1-|z|) for |z| < 1

• epanechnikov: K(z) = (3/4)(1-z^2) for |z| < 1

• quartic: K(z) = (15/16)*(1-(z/threshold)^2^)2 for |z| < 1

• gaussian: K(z) = (2pi)^{1/2} * exp(-z^2/2)

Value

a list of length 5 where each element is a kernel function.

Compute Local Geary statistic

Description

The Local Geary is a local adaptation of Geary's C statistic of spatial autocorrelation. The Local Geary uses squared differences to measure dissimilarity unlike the Local Moran. Low values of the Local Geary indicate positive spatial autocorrelation and large refers to negative spatial autocorrelation. Inference for the Local Geary is based on a permutation approach which compares the observed value to the reference distribution under spatial randomness. The Local Geary creates a pseudo p-value. This is not an analytical p-value and is based on the number of permutations and as such should be used with care.

Usage

local_c(x, nb, wt, ...)

local_c_perm(x, nb, wt, nsim = 499, alternative = "two.sided", ...)

Arguments

Details

Overview

The Local Geary can be extended to a multivariate context. When x is a numeric vector, the univariate Local Geary will be calculated. To calculate the multivariate Local Moran provide either a list or a matrix. When x is a list, each element must be a numeric vector of the same length and of the same length as the neighbours in listw. In the case that x is a matrix the number of rows must be the same as the length of the neighbours in listw.

While not required in the univariate context, the standardized Local Geary is calculated. The multivariate Local Geary is always standardized.

The univariate Local Geary is calculated as c_i = \sum_j w_{ij}(x_i - x_j)^2 and the multivariate Local Geary is calculated as c_{k,i} = \sum_{v=1}^{k} c_{v,i} as described in Anselin (2019).

Implementation

These functions are based on the implementations of the local Geary statistic in the development version of spdep. They are based on spdep::localC and spdep::localC_perm.

spdep::localC_perm and thus local_c_perm utilize a conditional permutation approach to approximate a reference distribution where each observation i is held fixed, randomly samples neighbors, and calculated the local C statistic for that tuple (ci). This is repeated nsim times. From the simulations 3 different types of p-values are calculated—all of which have their potential flaws. So be extra judicious with using p-values to make conclusions.

• p_ci: utilizes the sample mean and standard deviation. The p-value is then calculated using pnorm()–assuming a normal distribution which isn't always true.

• p_ci_sim: uses the rank of the observed statistic.

• p_folded_sim: follows the pysal implementation where p-values are in the range of [0, 0.5]. This excludes 1/2 of all p-values and should be used with caution.

Value

a data.frame with columns

• ci: Local Geary statistic

• e_ci: expected value of the Local Geary based on permutations

• z_ci: standard deviation based on permutations

• var_ci: variance based on permutations

• p_ci: p-value based on permutation sample standard deviation and means

• p_ci_sim: p-value based on rank of observed statistic

• p_folded_sim: p-value based on the implementation of Pysal which always assumes a two-sided test taking the minimum possible p-value

• skewness: sample skewness

• kurtosis: sample kurtosis

Author(s)

Josiah Parry, josiah.parry@gmail.com

References

Anselin, L. (1995), Local Indicators of Spatial Association—LISA. Geographical Analysis, 27: 93-115. doi:10.1111/j.1538-4632.1995.tb00338.x

Anselin, L. (2019), A Local Indicator of Multivariate Spatial Association: Extending Geary's c. Geogr Anal, 51: 133-150. doi:10.1111/gean.12164

Examples

local_c_perm(guerry_nb$crime_pers, guerry_nb$nb, guerry_nb$wt)

Local indicator of Colocation Quotient

Description

The local indicator of the colocation quotient (LCLQ) is a Local Indicator of Spatial Association (LISA) that evaluates if a given observation's subcategory in A is colocated with subcategories in B. Like the CLQ, the LCLQ provides insight into the asymmetric relationships between subcategories of A and B (where B can also equal A) but at the local level.

The LCLQ is defined using Gaussian kernel weights and an adaptive bandwidth (see st_kernel_weights()). However, any type of weights list can be used. Kernel weights are used to introduce a decay into the calculation of the CLQ. This ensures that points nearer to the focal point have more influence than those that are more distant.

Usage

local_colocation(A, B, nb, wt, nsim)

Arguments

Details

The LCLQ is defined as LCLQ_{A_i \to B} = \frac{N_{A_i \to B}}{N_B / (N - 1)} where N_{A_i \to B} = \sum_{j = 1(j \ne i)}^{N}(\frac{w_{ij}f_{ij}}{\sum_{j = 1(j \ne i)}^{N}w_{ij}}). And the weights matrix, wij, uses adaptive bandwidth Gaussian kernel weights.

LCLQ is only calculated for those subcategories which are present in the neighbor list. If a subcategory is not present, then the resultant LCLQ and simulated p-value will be NA.

Value

a data frame with as many rows as observations in A and two times as many columns as unique values in B. Columns contain each unique value of B as well as the simulated p-value for each value of B.

References

Fahui Wang, Yujie Hu, Shuai Wang & Xiaojuan Li (2017) Local Indicator of Colocation Quotient with a Statistical Significance Test: Examining Spatial Association of Crime and Facilities, The Professional Geographer, 69:1, 22-31, doi:10.1080/00330124.2016.1157498

Examples

A <- guerry$main_city
B <- guerry$region
geo <- sf::st_centroid(sf::st_geometry(guerry))
nb <- include_self(st_knn(geo, 5))
wt <- st_kernel_weights(nb, geo, "gaussian", adaptive = TRUE)
res <- local_colocation(A, B, nb, wt, 9)
tail(res)

Calculate the local colocation quotient

Description

Calculate the local colocation quotient

Usage

local_colocation_calc(A, B, listw)

Value

a matrix

spdep implementation of local colocation quotient

Description

Internal implementation of the local CLQ that is compatible with spdep.

Usage

local_colocation_impl(A, B, listw, nsim = 99)

Value

a data frame where the number of rows is the same length as A and the number of columns is the same as unique values in B.

Local G

Description

Calculate the local Geary statistic for a given variable.

Usage

local_g(x, nb, wt, alternative = "two.sided", ...)

local_g_perm(x, nb, wt, nsim = 499, alternative = "two.sided", ...)

Arguments

Value

a data.frame with columns:

• gi: the observed statistic

• cluster: factor variable with two levels classification high or low

• e_gi: the permutation sample mean

• var_gi: the permutation sample variance

• std_dev: standard deviation of the Gi statistic

• p_value: the p-value using sample mean and standard deviation

• p_folded_sim: p-value based on the implementation of Pysal which always assumes a two-sided test taking the minimum possible p-value

• skewness: sample skewness

• kurtosis: sample kurtosis

Examples

x <- guerry$crime_pers
nb <- st_contiguity(guerry)
wt <- st_weights(nb)

res <- local_g_perm(x, nb, wt)

head(res)

Calculate the Local Gi* for a spacetime cube

Description

An alternative implementation to spdep::localG intended for use with a spacetime cube.

Usage

local_g_spt(x, times, nb, wt, n_locs, nsim)

Arguments

Local G*

Description

Calculate the local Gi* statistic.

Usage

local_gstar(x, nb, wt, alternative = "two.sided", ...)

local_gstar_perm(x, nb, wt, nsim = 499, alternative = "two.sided", ...)

Arguments

Value

a data.frame with columns:

• gi: the observed statistic

• e_gi: the permutation sample mean

• var_gi: the permutation sample variance

• p_value: the p-value using sample mean and standard deviation

• p_folded_sim: p-value based on the implementation of Pysal which always assumes a two-sided test taking the minimum possible p-value

• skewness: sample skewness

• kurtosis: sample kurtosis

Examples

nb <- st_contiguity(guerry)
wt <- st_weights(nb)
x <- guerry$crime_pers

res <- local_gstar_perm(x, nb, wt)
head(res)

res <- local_gstar(x, nb, wt)
head(res)

Bivariate local join count

Description

Bivariate local join count

Usage

local_jc_bv(x, z, nb, wt, nsim = 499)

Arguments

Value

a data.frame with two columns join_count and p_sim and number of rows equal to the length of arguments x, z, nb, and wt.

Examples

x <- as.integer(guerry$infants > 23574)
z <- as.integer(guerry$donations > 10973)
nb <- st_contiguity(guerry)
wt <- st_weights(nb, style = "B")
local_jc_bv(x, z, nb, wt)

Compute local univariate join count

Description

The univariate local join count statistic is used to identify clusters of rarely occurring binary variables. The binary variable of interest should occur less than half of the time.

Usage

local_jc_uni(
  fx,
  chosen,
  nb,
  wt = st_weights(nb, style = "B"),
  nsim = 499,
  alternative = "two.sided",
  iseed = NULL
)

Arguments

Details

The local join count statistic requires a binary weights list which can be generated with st_weights(nb, style = "B"). Additionally, ensure that the binary variable of interest is rarely occurring in no more than half of observations.

P-values are estimated using a conditional permutation approach. This creates a reference distribution from which the observed statistic is compared. For more see Geoda Glossary. Calls spdep::local_joincount_uni().

Value

a data.frame with two columns join_count and p_sim and number of rows equal to the length of arguments x, nb, and wt.

Examples

if (requireNamespace("dplyr", quietly = TRUE)) {

res <- dplyr::transmute(
  guerry,
  top_crime = as.factor(crime_prop > 9000),
  nb = st_contiguity(geometry),
  wt = st_weights(nb, style = "B"),
  jc = local_jc_uni(top_crime, "TRUE", nb, wt))
tidyr::unnest(res, jc)

}

Calculate the Local Moran's I Statistic

Description

Moran's I is calculated for each polygon based on the neighbor and weight lists.

Usage

local_moran(x, nb, wt, alternative = "two.sided", nsim = 499, ...)

Arguments

Details

local_moran() calls spdep::localmoran_perm() and calculates the Moran I for each polygon. As well as provide simulated p-values.

Value

a data.frame containing the columns ii, eii, var_ii, z_ii, p_ii, p_ii_sim, and p_folded_sim. For more details please see spdep::localmoran_perm().

See Also

Other stats: st_lag()

Examples

local_moran(guerry_nb$crime_pers, guerry_nb$nb, guerry_nb$wt)

Compute the Local Bivariate Moran's I Statistic

Description

Given two continuous numeric variables, calculate the bivariate Local Moran's I.

Usage

local_moran_bv(x, y, nb, wt, nsim = 499)

Arguments

Details

The Bivariate Local Moran, like its global counterpart, evaluates the value of x at observation i with its spatial neighbors' value of y. The value of

I_i^B

is just xi * Wyi. Or, in simpler words the local bivariate Moran is the result of multiplying x by the spatial lag of y. Formally it is defined as

I_i^B= cx_i\Sigma_j{w_{ij}y_j}

Value

a data.frame containing two columns Ib and p_sim containing the local bivariate Moran's I and simulated p-values respectively.

References

Local Spatial Autocorrelation (3): Multivariate Local Spatial Autocorrelation, Luc Anselin

See Also

Other global_moran: global_moran(), global_moran_bv(), global_moran_perm(), global_moran_test()

Examples

x <- guerry_nb$crime_pers
y <- guerry_nb$wealth
nb <- guerry_nb$nb
wt <- guerry_nb$wt
local_moran_bv(x, y, nb, wt)

Calculate the Local Bivariate Moran Statistic

Description

Calculate the Local Bivariate Moran Statistic

Usage

local_moran_bv_calc(x, y, nb, wt)

Arguments

Local Bivariate Moran's I spdep implementation

Description

Local Bivariate Moran's I spdep implementation

Usage

local_moran_bv_impl(x, y, listw, nsim)

Arguments

Local Bivariate Moran's I conditional permutation implementation

Description

Local Bivariate Moran's I conditional permutation implementation

Usage

local_moran_bv_perm_impl(x, y, listw)

Arguments

Local spatial heteroscedacity

Description

Local spatial heteroscedacity

Usage

losh(x, nb, wt, a = 2, ...)

losh_perm(x, nb, wt, a = 2, nsim = 499, ...)

Arguments

Value

a data.frame with columns

• hi: the observed statistic

• e_hi: the sample average

• var_hi: the sample variance

• z_hi the approximately Chi-square distributed test statistic

• x_bar_i: the local spatially weight mean for observation i

• ei: residuals

Examples

nb <- st_contiguity(guerry)
wt <- st_weights(nb)
x <- guerry$crime_pers
losh(x, nb, wt)
losh(x, nb, wt, var_hi = FALSE)
losh_perm(x, nb, wt, nsim = 49)

Local Neighbor Match Test

Description

Implements the Local Neighbor Match Test as described in Tobler's Law in a Multivariate World (Anselin and Li, 2020).

Usage

nb_match_test(
  x,
  nb,
  wt = st_weights(nb),
  k = 10,
  nsim = 499,
  scale = TRUE,
  .method = "euclidian",
  .p = 2
)

Arguments

Value

a data.frame with columns

• n_shared (integer): the number of shared neighbors between geographic and attribute space

• nb_matches (list): matched neighbor indexes. Each element is an integer vector of same length as the ith observation of n_shared

• knn_nb (list): the neighbors in attribute space

• probability (numeric): the geometric probability of observing the number of matches

• p_sim (numeric): a folded simulated p-value

Examples

if (requireNamespace("dplyr", quietly = TRUE)) {
library(magrittr)
guerry %>%
  dplyr::transmute(nb = st_knn(geometry, k = 10),
         nmt = nb_match_test(list(crime_pers, literacy, suicides),
                             nb, nsim = 999)) %>%
  tidyr::unnest(nmt)
 }

Set Operations

Description

Perform set operations element-wise on two lists of equal length.

Usage

nb_union(x, y)

nb_intersect(x, y)

nb_setdiff(x, y)

Arguments

Details

• nb_union() returns the union of elements in each element of x and y

• nb_intersect() returns the intersection of elements in each element of x and y

• nb_setdiff() returns the difference of elements in each element of x and y

Value

A list of class nb

Examples

nb <- st_contiguity(guerry$geometry)
nb_knn <- st_knn(guerry$geometry, k = 3)
nb_setdiff(nb, nb_knn)
nb_union(nb, nb_knn)
nb_intersect(nb, nb_knn)

Identify matches between two neighbor lists

Description

Identify matches between two neighbor lists

Usage

nmt_calc(knn_nb, nb)

Arguments

Value

an integer vector

Implementation of Neighbor Match Test

Description

Implementation of Neighbor Match Test

Usage

nmt_impl(x, k, listw, nsim = 199, scale = TRUE, .method = "euclidian", .p = 2)

Arguments

Value

a data frame containing columns:

• n_shared

• nb_matches

• knn_nb

• probability

• p_sim

Find conditionally permuted neighbor matches Given a kNN attribute neighbor list and a listw object, find the number of matches given a conditional permutation.

Description

Find conditionally permuted neighbor matches Given a kNN attribute neighbor list and a listw object, find the number of matches given a conditional permutation.

Usage

nmt_perm_impl(knn_nb, listw)

Arguments

Value

an integer vector

Create node features from edges

Description

Given a tidygraph object, create a list column of edge data for each node in the node context.

Usage

node_get_nbs()

node_get_edge_list()

node_get_edge_col(edges, .var)

Arguments

Details

• node_get_nbs(): creates a neighbor list in the nodes context based on the adjacency list. This returns a nb class object with the neighboring nodes.

  • Uses igraph::get.adjlist()

• node_get_edge_list(): creates an edge list. The edge list contains the row index of the edge relationships in the edge context for each node.

  • Uses igraph::get.adjedgelist().

• node_get_edge_col(): creates a list column containing edge attributes as a list column in the node context (much like find_xj()).

  • Uses igraph::get.edge.attribute()

Value

A list column

Examples

if (interactive()) {
  net <- sfnetworks::as_sfnetwork(
    sfnetworks::roxel
  )

  dplyr::mutate(
    net,
    nb = node_get_nbs(),
    edges = node_get_edge_list(),
    types = node_get_edge_col(edges, "type")
  )
}

Pairwise Colocation Quotient

Description

Calculate the pairwise colocation quotient (CLQ) for two categorical variables using conditional permutation.

Usage

pairwise_colocation(A, B, nb, nsim = 99)

Arguments

Details

Intuition

The pairwise CLQ is used to test if there is a spatial directional association between subcategories of two vectors A and B. Compared to the cross-K metric and the join count statistic, the pairwise CLQ can elucidate the presence of an asymmetric relationship between subcategories of A and B. A and B can either be separate categorical vectors or the same categorical vector.

"The null hypothesis for a CLQ-based analysis is 'given the clustering of the joint population, there is no spatial association between pairs of categorical subsets.'"

Definition

The pairwise colocation quotient is defined as "the ratio of observed to expected proportions of B among A's nearest neighbors. Formally this is given by CLQ_{A \to B} = \frac{{C_{A \to B} / N_A}}{N^{'}_{B} / (N - 1)}" where C_{A \to B} = \sum_{i = 1}^{N_A}\sum_{j = 1}^{v}\frac{B_{ij}(1,0)}{v}.

Inference

Inference is done using conditional permutation as suggested by Anselin 1995 where a number of replicates are created. The observed values are compared to the replicates and a the simulated p-value is the proportion of cases where the observed is more extreme as compared to replicate. The simulated p-value returns the lower p-value of either tail.

Interpretation

Given that the CLQ is a ratio of the observed to expected, we interpret values larger than one to mean that there is more colocation than to be expected under the null hypothesis of no spatial association. When the value is smaller than 0, we interpret it to mean that there is less colocation than expected under the null.

Value

A matrix where the rownames are the unique values of A and the column names are the unique values of B and their simulated p-values in the form of ⁠p_sim_{B}⁠.

Examples

A <- guerry$main_city
B <- guerry$region
nb <- st_knn(sf::st_geometry(guerry), 5)
pairwise_colocation(B, A, nb)
pairwise_colocation(B, B, nb, 199)

Pairwise CLQ calculation

Description

Internal function to calculate the pairwise CQL.

Usage

pairwise_colocation_calc(A, B, nb)

Arguments

Value

a matrix where rownames are A values colnames are B values

Pairwise CLQ conditional permutation implementation

Description

Internal implementation of the pairwise CQL using conditional permutation. Functionally the same as pairwise_colocation().

Usage

pairwise_colocation_perm_impl(A, B, nb, nsim = 199)

Arguments

Value

a matrix used by pairwise_colocation

Percent Non-zero Neighbors

Description

Calculate the percentage of non-zero neighbors in a neighbor list.

Usage

pct_nonzero(nb)

Arguments

Value

a scalar double

Examples

nb <- st_contiguity(guerry)
pct_nonzero(nb)

Conditionally permutes a listw object

Description

Conditionally permutes a listw object

Usage

permute_listw(listw)

Arguments

Value

a listw object

Create a listw object from a neighbors and weight list

Description

Given a neighbor and weight list, create a listw object.

Usage

recreate_listw(nb, wt)

Arguments

Value

a listw object

Examples

recreate_listw(guerry_nb$nb, guerry_nb$wt)

Set columns from geometry to data

Description

Set a column from the geometry context of a spacetime object to the data context.

Usage

set_col(x, .from_geo, .to_data = .from_geo)

set_wts(x, .wt_col = "wt")

set_nbs(x, .nb_col = "nb")

Arguments

Details

These functions will reorder the spacetime object to ensure that it is ordered correctly based on the location time columns in the geometry context defined by the loc_col and time_col attributes respectively.

set_wts() and set_nbs() create a new column in the data context with the same name as the column in the geometry context. If a different name is desired use set_col()

Value

A spacetime object with an active data context and a new column from the geometry context.

Examples

if (interactive()) {
df_fp <- system.file("extdata", "bos-ecometric.csv", package = "sfdep")
geo_fp <- system.file("extdata", "bos-ecometric.geojson", package = "sfdep")

# read in data
df <- read.csv(
  df_fp, colClasses = c("character", "character", "integer", "double", "Date")
)
geo <- sf::st_read(geo_fp)

# Create spacetime object called `bos`
bos <- spacetime(df, geo,
                .loc_col = ".region_id",
                .time_col = "time_period")
bos <- activate(bos, "geometry")
bos$nb <- st_contiguity(bos)
bos$wt <- st_weights(bos$nb)
bos$card <- st_cardinalties(bos$nb)

set_nbs(bos)
set_wts(bos)
set_col(bos, "card")
set_col(bos, "card", "cardinalities")
}

Internal function to shuffle neighbors

Description

Used in conditional permutation and the function permute_listw().

Usage

shuffle_nbs(i, n, card)

Arguments

Value

a nb class object

Trigonometric functions

Description

These functions are wrappers around the base trigonometric functions. However these return degree values rather than radians.

Usage

sin_d(theta = 0)

Details

These functions were adopted from the now archived CRAN package {aspace}.

Value

numeric

Construct a spacetime object

Description

A spacetime object is a collection of a linked data frame and an sf objects. It can be thought of as geography linked to a table that represents those geographies over one or more time periods.

Usage

spacetime(.data, .geometry, .loc_col, .time_col, active = "data")

new_spacetime(.data, .geometry, .loc_col, .time_col, active = "data")

validate_spacetime(.data, .geometry, .loc_col, .time_col)

is_spacetime(x, ...)

is.spacetime(x, ...)

Arguments

Details

Create a spacetime representation of vector data from a data.frame and an sf object with spacetime()

.time_col must be able to be sorted. As such, .time_col cannot be a character vector. It must have a base type of (typeof()) either double or integer—the case in dates or factors respectively. An edge case exists with POSIXlt class objects as these can be sorted appropriately but have a base type of list.

spacetime() is a wrapper around new_spacetime(). Spacetimes are validated before creation with validate_spacetime().

Check if an object is a spacetime object with is_spacetime() or is.spacetime().

Value

• spacetime() and new_spacetime() construct spacetime clss objects

• validate_spacetime() returns nothing but will elicit a warning or error if the spacetime object is not validly constructed

• is_spacetime() and is.spacetime() return a logical scalar indicating if an object inherits the spacetime class

Validation

validate_spacetime() checks both .data and .geometry to ensure that the constructed spacetime object meets minimum requirements.:

• .data inherits the data.frame class

• .geometry is an sf object

• ensures that .time_col is of the proper class

• ensures there are no missing geometries in .geometry

• checks for duplicate geometries

• ensures .loc_col are the same type in .data and .geometry

• lastly informs of missing values in additional columns in .data

Examples

df_fp <- system.file("extdata", "bos-ecometric.csv", package = "sfdep")
geo_fp <- system.file("extdata", "bos-ecometric.geojson", package = "sfdep")

# read in data
df <- read.csv(
  df_fp, colClasses = c("character", "character", "integer", "double", "Date")
)

geo <- sf::st_read(geo_fp)

bos <- spacetime(df, geo, ".region_id", "year")
is_spacetime(bos)
bos

Spatial Gini Index

Description

Calculates the spatial Gini index for a given numeric vector and neighbor list. Based on the formula provided Rey and Smith (2013).

Usage

spatial_gini(x, nb)

Arguments

Details

The Gini index is a global measure of inequality based on the Lorenz curve. It ranges between 0 and 1 where 0 is perfect equality and 1 is perfect inequality.

The spatial Gini index decomposes the Gini coefficient based on spatial neighbors.

Value

A data frame with columns:

• G: the Gini index

• NBG: the neighbor composition of the Gini coefficient

• NG: the non-neighbor composition of the Gini coefficient

• SG: the Spatial Gini which is equal to NG * \frac{1}{G}

References

doi:10.1007/s12076-012-0086-z

Examples

nb <- st_contiguity(guerry)
x <- guerry$wealth
spatial_gini(x, nb)

Create time lagged spatial neighbors

Description

Given a an spdep neighbor list (or any other list indicating row position) of neighbors in a spacetime object's geometry context, create a neighbor list across space and time in the data context.

Usage

spt_nb(nb, n_times, n_locs, k = 1)

Arguments

Details

Note that this should only be used for spacetime cubes.

This function is only available for internal development and should be used with extreme caution.

The number of bins is equal to n_times * n_locs where each location has a bin time-series with n_times observations. This is what makes it a spacetime cube function.

Value

a nb list

References

https://pro.arcgis.com/en/pro-app/2.8/tool-reference/space-time-pattern-mining/create-space-time-cube.htm

See Also

spt_wt() for converting spacetime neighbors to spacetime weights.

Order a spacetime cube

Description

When performing analysis on a spacetime cube, the order is of the utmost importance. This function ensures that a spacetime cube is ordered appropriately.

Usage

spt_order(x)

Arguments

Value

a spacetime object that orders based on time and location

Update spacetime attributes

Description

Update's a spacetime object's number of locations and time periods. A spacetime object's attributes are sticky and will not change if subsetted for example by using dplyr::filter() or dplyr::slice(). Update the locations and times of a spacetime object.

Usage

spt_update(x, ...)

Arguments

Value

an object of class spacetime with updated attributes

Create time lagged spatial weights

Description

Given a space-time-lagged neighbor list and a weights lists, e.g. made by st_dist_band() or st_contiguity(), create a corresponding weights list.

Usage

spt_wt(wt, nbt, n_times, n_locs, k)

Arguments

Details

It is intended that spt_wt() is used following the use of spt_nb() using the same input arguments. This ensures that the time-lagged spatial weights are correctly associated with the time-lagged spatial neighbors.

Value

a weight list with same cardinality as nbt

See Also

spt_nb() for creating spacetime neighbors which are inputs into spacetime weights

Convert to an edge lines object

Description

Given geometry and neighbor and weights lists, create an edge list sf object.

Usage

st_as_edges(x, nb, wt)

## S3 method for class 'sf'
st_as_edges(x, nb, wt)

## S3 method for class 'sfc'
st_as_edges(x, nb, wt)

Arguments

Details

Creating an edge list creates a column for each i position and j between an observation and their neighbors. You can recreate these values by expanding the nb and wt list columns.

library(magrittr)
guerry_nb %>%
  tibble::as_tibble() %>%
  dplyr::select(nb, wt) %>%
  dplyr::mutate(i = dplyr::row_number(), .before = 1) %>%
  tidyr::unnest(c(nb, wt))
#> # A tibble: 420 x 3
#>        i    nb    wt
#>    <int> <int> <dbl>
#>  1     1    36 0.25 
#>  2     1    37 0.25 
#>  3     1    67 0.25 
#>  4     1    69 0.25 
#>  5     2     7 0.167
#>  6     2    49 0.167
#>  7     2    57 0.167
#>  8     2    58 0.167
#>  9     2    73 0.167
#> 10     2    76 0.167
#> # i 410 more rows

Value

Returns an sf object with edges represented as a LINESTRING.

• from: node index. This is the row position of x.

• to: node index. This is the neighbor value stored in nb.

• i: node index. This is the row position of x.

• j: node index. This is the neighbor value stored in nb.

• wt: the weight value of j stored in wt.

Examples

if (requireNamespace("dplyr", quietly = TRUE)) {

library(magrittr)
guerry %>%
  dplyr::mutate(nb = st_contiguity(geometry),
         wt = st_weights(nb)) %>%
  st_as_edges(nb, wt)

}

Create an sfnetwork

Description

Given an sf or sfc object and neighbor and weights lists, create an sfnetwork object.

Usage

st_as_graph(x, nb, wt)

## S3 method for class 'sf'
st_as_graph(x, nb, wt)

## S3 method for class 'sfc'
st_as_graph(x, nb, wt)

Arguments

Value

an sfnetwork object

See Also

st_as_nodes() and st_as_edges()

Examples

if (requireNamespace("dplyr", quietly = TRUE)) {
library(magrittr)

guerry_nb %>%
  st_as_graph(nb, wt)
}

Convert to a node point object

Description

Given geometry and a neighbor list, creates an sf object to be used as nodes in an sfnetworks::sfnetwork(). If the provided geometry is a polygon, sf::st_point_on_surface() will be used to create the node point.

Usage

st_as_nodes(x, nb)

## S3 method for class 'sf'
st_as_nodes(x, nb)

## S3 method for class 'sfc'
st_as_nodes(x, nb)

Arguments

Details

st_as_node() adds a row i based on the attribute "region.id" in the nb object. If the nb object is created with sfdep, then the values will always be row indexes.

Value

An object of class sf with POINT geometry.

Examples

if (requireNamespace("dplyr", quitly = TRUE)) {
library(magrittr)
guerry %>%
  dplyr::transmute(nb = st_contiguity(geometry)) %>%
  st_as_nodes(nb)
 }

Create Block Contiguity for Spatial Regimes

Description

libpysal write that "block contiguity structures are relevant when defining neighbor relations based on membership in a regime. For example, all counties belonging to the same state could be defined as neighbors, in an analysis of all counties in the US."

Source: libpysal

Usage

st_block_nb(regime, id = 1:length(regime), diag = FALSE)

Arguments

Value

An object of class nb. When diag = TRUE the attribute self.included = TRUE.

Examples

id <- guerry$code_dept
regime <- guerry$region
st_block_nb(regime, id)

Calculate neighbor cardinalities

Description

Identify the cardinality of a neighbor object. Utilizes spdep::card() for objects with class nb, otherwise returns lengths(nb).

Usage

st_cardinalties(nb)

Arguments

Value

an integer vector with the same length as nb.

See Also

Other other: st_nb_lag(), st_nb_lag_cumul()

Examples

nb <- st_contiguity(sf::st_geometry(guerry))
st_cardinalties(nb)

Create Neighbors as Complete Graph

Description

Create a neighbors list where every element is related to every other element. This creates a complete graph.

Usage

st_complete_nb(n_elements, diag = FALSE)

Arguments

Value

A neighbors list representing a complete graph.

Examples

st_complete_nb(5)

Identify polygon neighbors

Description

Given an sf geometry of type POLYGON or MULTIPOLYGON identify contiguity based neighbors.

Usage

st_contiguity(geometry, queen = TRUE, ...)

Arguments

Details

Utilizes spdep::poly2nb()

Value

a list of class nb

See Also

Other neighbors: st_dist_band(), st_knn()

Examples

# on basic polygons
geo <- sf::st_geometry(guerry)
st_contiguity(geo)
if (requireNamespace("dplyr", quietyl = TRUE)) {
# in a pipe
library(magrittr)
guerry %>%
  dplyr::mutate(nb = st_contiguity(geometry), .before = 1)
 }

Neighbors from a distance band

Description

Creates neighbors based on a distance band. By default, creates a distance band with the maximum distance of k-nearest neighbors where k = 1 (the critical threshold) to ensure that there are no regions that are missing neighbors.

Usage

st_dist_band(geometry, lower = 0, upper = critical_threshold(geometry), ...)

Arguments

Value

a list of class nb

See Also

Other neighbors: st_contiguity(), st_knn()

Examples

geo <- sf::st_geometry(guerry)
st_dist_band(geo, upper = critical_threshold(geo))

Calculate inverse distance weights

Description

From a neighbor list and sf geometry column, calculate inverse distance weight.

Usage

st_inverse_distance(nb, geometry, scale = 100, alpha = 1)

Arguments

Details

The inverse distance formula is w_{ij} = 1 / d_{ij}^\alpha

Value

a list where each element is a numeric vector

See Also

Other weights: st_kernel_weights(), st_nb_dists(), st_weights()

Examples

geo <- sf::st_geometry(guerry)
nb <- st_contiguity(geo)
wts <- st_inverse_distance(nb, geo)
head(wts, 3)
wts <- st_inverse_distance(nb, geo, scale = 10000)
head(wts, 3)

Calculate Kernel Weights

Description

Create a weights list using a kernel function.

Usage

st_kernel_weights(
  nb,
  geometry,
  kernel = "uniform",
  threshold = critical_threshold(geometry),
  adaptive = FALSE,
  self_kernel = FALSE
)

Arguments

Details

By default st_kernel_weight() utilizes a critical threshold of the maximum neighbor distance using critical_threshold(). If desired, the critical threshold can be specified manually. The threshold will be passed to the underlying kernel.

Value

a list where each element is a numeric vector.

See Also

Other weights: st_inverse_distance(), st_nb_dists(), st_weights()

Examples

geometry <- sf::st_geometry(guerry)
nb <- st_contiguity(geometry)
nb <- include_self(nb)
res <- st_kernel_weights(nb, geometry)
head(res, 3)

Calculate K-Nearest Neighbors

Description

Identifies the k nearest neighbors for given point geometry. If polygon geometry is provided, the centroids of the polygon will be used and a warning will be emitted.

Usage

st_knn(geometry, k = 1, symmetric = FALSE, ...)

Arguments

Details

This function utilizes spdep::knearneigh() and spdep::knn2nb().

Value

a list of class nb

See Also

Other neighbors: st_contiguity(), st_dist_band()

Examples

st_knn(sf::st_geometry(guerry), k = 8)

Calculate spatial lag

Description

Calculates the spatial lag of a numeric variable given a neighbor and weights list.

Usage

st_lag(x, nb, wt, na_ok = FALSE, allow_zero = NULL, ...)

Arguments

Value

a numeric vector with same length as x

See Also

Other stats: local_moran()

Examples

geo <- sf::st_geometry(guerry)
nb <- st_contiguity(geo)
wt <- st_weights(nb)

st_lag(guerry$crime_pers, nb, wt)

Apply a function to neighbors

Description

Sometimes one may want to create custom lag variables or create some other neighborhood level metric that may not be defined yet. This st_nb_apply() enables you to apply a function to each observation's (xi) neighbors (xij).

Usage

st_nb_apply(x, nb, wt, .f, suffix = "dbl", ...)

Arguments

Details

The below example calculates the spatial lag using st_nb_apply() and st_lag() to illustrate how we can apply functions to neighbors.

Currently questioning the use case. find_xj() is now exported and may negate the need for this function.

Value

a vector or list of with same length as x.

Examples

if (requireNamespace("dplyr", quietly = TRUE)) {
library(magrittr)
guerry %>%
  dplyr::transmute(
    nb = st_contiguity(geometry),
    wt = st_weights(nb),
    lag_apply = st_nb_apply(
      crime_pers, nb, wt,
      .f = function(.xij, .wt, ...) sum(.xij *.wt)
    ),
    lag = st_lag(crime_pers, nb, wt)
  )
}

Graph based neighbors

Description

Create graph based neighbors on a set of points.

Usage

st_nb_delaunay(geometry, .id = NULL)

st_nb_gabriel(geometry, .nnmult = 3)

st_nb_relative(geometry, .nnmult = 3)

Arguments

Details

• st_nb_delaunay() uses spdep::tri2nb()

• st_nb_gabriel() uses spdep::gabrielneigh() and spdep::graph2nb()

• st_nb_relative() uses spdep::relativeneigh() and spdep::graph2nb()

st_nb_delaunay() implements Delaunay triangulation via spdep and thus via deldir. Delaunay triangulation creates a mesh of triangles that connects all points in a set. It ensures that no point is in in the circumcircle of an triangle in the triangulation. As a result, Delaunay triangulation maximizes the minimum angle in each triangle consequently avoiding skinny triangles.

The Gabriel graph is a subgraph of the Delaunay triangulation. Edges are created when the closed disc between two points p, and q, contain no other points besides themselves.

The relative neighborhood graph (RNG) is based on the Delaunay triangulation. It connects two points when there are no other closer points to each of them. The RNG is a subgraph of the Delaunay triangulation.

Note that Delaunay triangulation assumes a plane and thus uses Euclidean distances.

See spdep::gabrielneigh() for further descriptions of the graph neighbor implementations.

Value

an object of class nb

Examples

geometry <- sf::st_centroid(sf::st_geometry(guerry))
st_nb_delaunay(geometry)
st_nb_gabriel(geometry)
st_nb_relative(geometry)

Calculate neighbor distances

Description

From an nb list and point geometry, return a list of distances for each observation's neighbors list.

Usage

st_nb_dists(x, nb, longlat = NULL)

Arguments

Details

Utilizes spdep::nbdists() for distance calculation.

Value

a list where each element is a numeric vector.

See Also

Other weights: st_inverse_distance(), st_kernel_weights(), st_weights()

Examples

geo <- sf::st_geometry(guerry)
nb <- st_contiguity(geo)
dists <- st_nb_dists(geo, nb)

head(dists)

Pure Higher Order Neighbors

Description

Identify higher order neighbors from a neighbor list. order must be greater than 1. When order equals 2 then the neighbors of the neighbors list is returned and so forth. See Anselin's book was: "https://spatial.uchicago.edu" "/sites/spatial.uchicago.edu/files/1_introandreview_reducedsize.pdf" for an example.

Usage

st_nb_lag(nb, order)

Arguments

Details

Utilizes spdep::nblag()

Value

a list of class nb

See Also

Other other: st_cardinalties(), st_nb_lag_cumul()

Examples

nb <- st_contiguity(sf::st_geometry(guerry))
st_nb_lag(nb, 3)

Encompassing Higher Order Neighbors

Description

Creates an encompassing neighbor list of the order specified. For example, if the order is 2 the result contains both 1st and 2nd order neighbors.

Usage

st_nb_lag_cumul(nb, order)

Arguments

Details

Utilizes spdep::nblag_cumul()

Value

a list of class nb

See Also

Other other: st_cardinalties(), st_nb_lag()

Examples

nb <- st_contiguity(sf::st_geometry(guerry))
st_nb_lag_cumul(nb, 3)

Calculate spatial weights

Description

Calculate polygon spatial weights from a nb list. See spdep::nb2listw() for further details.

Usage

st_weights(nb, style = "W", allow_zero = NULL, ...)

Arguments

Details

Under the hood, st_weights() creates a listw object and then extracts the weights elements from it as the neighbours element is already–presumably–already existent in the neighbors list you've already created. listw objects are recreated using recreate_listw() when calculating other statistics.

Value

a list where each element is a numeric vector

See Also

Other weights: st_inverse_distance(), st_kernel_weights(), st_nb_dists()

Examples

if (requireNamespace("dplyr", quietly = TRUE)) {
library(magrittr)
guerry %>%
 dplyr::mutate(nb = st_contiguity(geometry),
               wt = st_weights(nb),
               .before = 1)

}
# using geometry column directly
nb <- st_contiguity(guerry$geometry)
wt <- st_weights(nb)
wt[1:3]

Calculation Standard Deviational Ellipse

Description

From an sf object containing points, calculate the standard deviational ellipse.

Usage

std_dev_ellipse(geometry)

Arguments

Details

The bulk of this function is derived from the archived CRAN package aspace version 3.2.0.

Value

An sf object with three columns

• sx: major axis radius in CRS units,

• sy: minor axis radius in CRS units,

• theta: degree rotation of the ellipse.

sf object's geometry is the center mean point.

Examples

#' # Make a grid to sample from
grd <- sf::st_make_grid(n = c(1, 1), cellsize = c(100, 100), offset = c(0,0))

# sample 100 points
pnts <- sf::st_sample(grd, 100)
std_dev_ellipse(pnts)

Calculate standard distance

Description

The standard distance of a point pattern is a measure of central tendency. Standard distance measures distance away from the mean center of the point pattern similar to standard deviations.

Usage

std_distance(geometry)

Arguments

Value

A numeric scalar.

See Also

Other point-pattern: center_mean()

Examples

# Make a grid to sample from
grd <- sf::st_make_grid(n = c(1, 1), cellsize = c(100, 100), offset = c(0,0))

# sample 100 points
pnts <- sf::st_sample(grd, 100)

# plot points
plot(pnts)

# calculate standard distance
std_distance(pnts)

Global sum of weights

Description

Calculate the global sum of weights

Usage

szero(wt)

Arguments

Value

a scalar numeric

Examples

nb <- st_contiguity(guerry)
wt <- st_weights(nb)
szero(wt)

tidyverse methods for spacetime objects

Description

dplyr methods for spacetime objects.

Usage

group_by.spacetime(.data, ...)

mutate.spacetime(.data, ...)

ungroup.spacetime(.data, ...)

Arguments

Value

a spacetime object

Convert neighbor or weights list to matrix

Description

Given a nb list or weights list, convert them to a matrix.

Usage

wt_as_matrix(nb, wt)

nb_as_matrix(nb)

Arguments

Value

Returns a n x n matrix

Examples

# make a grid
g <- sf::st_make_grid(
  cellsize = c(10, 10),
  offset = c(0, 0),
  n = c(2, 2)
)

# create neighbors
nb <- st_contiguity(g)

# cast to matrix
nb_as_matrix(nb)

# create weights
wt <- st_weights(nb)

# cast as matrix
wt_as_matrix(nb, wt)