Package 'BoundaryStats'

Title: Boundary Overlap Statistics
Description: Analysis workflow for finding geographic boundaries of ecological or landscape traits and comparing the placement of geographic boundaries of two traits. If data are trait values, trait data are transformed to boundary intensities based on approximate first derivatives across latitude and longitude. The package includes functions to create custom null models based on the input data. The boundary statistics are described in: Fortin, Drapeau, and Jacquez (1996) <doi:10.2307/3545584>.
Authors: Amy Luo [aut, cre, cph] , Elizabeth Derryberry [ths]
Maintainer: Amy Luo <[email protected]>
License: GPL (>= 3)
Version: 2.2.0
Built: 2024-11-24 06:29:52 UTC
Source: CRAN

Help Index


Afrixalus delicatus genetic groups projection

Description

Projection for A.delicatus_matrix

Usage

data(A.delicatus)

Format

Projection crs object

Source

doi:10.5061/dryad.315km76

References

Barratt et al. (2013) Molecular Ecology 27:4289–4308


Afrixalus delicatus genetic groups extent

Description

Extent for A.delicatus_matrix

Usage

data(A.delicatus)

Format

Numeric vector of length length 4

Source

doi:10.5061/dryad.315km76

References

Barratt et al. (2013) Molecular Ecology 27:4289–4308


Afrixalus delicatus genetic groups

Description

Raster data representing interpolated genetic group assignments for Afrixalus delicatus based on analyses in Barratt et al. 2018.

Usage

data(A.delicatus)

Format

A matrix to be converted into a SpatRaster object with a EPSG:4210 projection.

Source

doi:10.5061/dryad.315km76

References

Barratt et al. (2013) Molecular Ecology 27:4289–4308


Afrixalus sylvaticus genetic groups projection

Description

Projection for A.sylvaticus_matrix

Usage

data(A.sylvaticus)

Format

Projection crs object

Source

doi:10.5061/dryad.315km76

References

Barratt et al. (2013) Molecular Ecology 27:4289–4308


Afrixalus sylvaticus genetic groups extent

Description

Extent for A.sylvaticus_matrix

Usage

data(A.sylvaticus)

Format

Numeric vector of length length 4

Source

doi:10.5061/dryad.315km76

References

Barratt et al. (2013) Molecular Ecology 27:4289–4308


Afrixalus sylvaticus genetic groups

Description

Raster data representing interpolated genetic group assignments for Afrixalus sylvaticus based on analyses in Barratt et al. 2018.

Usage

data(A.sylvaticus)

Format

A matrix to be converted into a SpatRaster object with a EPSG:4210 projection.

Source

doi:10.5061/dryad.315km76

References

Barratt et al. (2013) Molecular Ecology 27:4289–4308


Null distribution for overlap statistics

Description

Creates custom probability distributions for two boundary statistics (number of subgraphs and length of the longest subgraph). Given a SpatRaster object, simulates n iterations of random raster surfaces from a neutral model.

Usage

boundary_null_distrib(
  x,
  convert = FALSE,
  cat = FALSE,
  threshold = 0.2,
  n_iterations = 10,
  model = "random",
  p = 0.5,
  progress = TRUE
)

Arguments

x

A SpatRaster object.

convert

TRUE if x contains numeric trait data that needs to be converted to boundary intensities. default = FALSE.

cat

TRUE if the input SpatRaster contains a categorical variable. default = FALSE.

threshold

A value between 0 and 1. The proportion of cells to keep as boundary elements. default = 0.2.

n_iterations

An integer indicating the number of iterations for the function. A value of 100 or 1000 is recommended to produce sufficient resolution for downstream statistical tests. default = 10.

model

Neutral model to use. Options: 'random' (stochastic), 'gaussian' (Gaussian random field), and 'random_cluster' (modified random clusters method)

p

If using modified random clusters, proportion of cells to be marked in percolated raster.Higher values of p produce larger clusters. Default: p = 0.5

progress

If progress = TRUE (default) a progress bar will be displayed.

Value

A list of two probability distribution functions for boundary statistics.

Author(s)

Amy Luo

References

Saura, S. & Martínez-Millán, J. (2000). Landscape patterns simulation with a modified random clusters method. Landscape Ecology, 15:661-678.

Examples

data(T.cristatus)
T.cristatus <- terra::rast(T.cristatus_matrix, crs = T.cristatus_crs)
terra::ext(T.cristatus) <- T.cristatus_ext

T.crist_bound_null <- boundary_null_distrib(T.cristatus, cat = TRUE, n_iterations = 100,
model = 'random_cluster')

Define the boundary elements of a SpatRaster with categorical data

Description

Creates boundary element cells where patches of two categories meet.

Usage

categorical_boundary(x)

Arguments

x

A SpatRaster object.

Value

A SpatRaster object with cell values 1 for boundary elements and 0 for other cells

Author(s)

Amy Luo

Examples

data(grassland)
grassland <- terra::rast(grassland_matrix, crs = grassland_crs)
terra::ext(grassland) <- grassland_ext

grassland_boundaries <- categorical_boundary(grassland)

Define the boundary elements of a SpatRaster with numeric data or boundary intensities

Description

Defines boundaries in a SpatRaster object by keeping a proportion of the cells with the highest boundary intensity values. If the SpatRaster contains trait values, the values can be converted to boundary/edge values (convert = T) using a Sobel-Feldman operator.

Usage

define_boundary(x, threshold = 0.2, convert = FALSE)

Arguments

x

A SpatRaster object.

threshold

A value between 0 and 1. The proportion of cells to keep as boundary elements. default = 0.2.

convert

logical. If TRUE, convert values of each cell from trait values to boundary intensities. default = FALSE.

Value

A SpatRaster object with cell values 1 for boundary elements and 0 for other cells

Author(s)

Amy Luo

References

Fortin, M.J. et al. (2000) Issues related to the detection of boundaries. Landscape Ecology, 15, 453-466. Jacquez, G.M., Maruca,I S. & Fortin M.-J. (2000) From fields to objects: A review of geographic boundary analysis. Journal of Geographical Systems, 3, 221, 241.

Examples

data(grassland)
grassland <- terra::rast(grassland_matrix, crs = grassland_crs)
terra::ext(grassland) <- grassland_ext

grassland_boundaries <- define_boundary(grassland, 0.1)

Ecoregion data for East Africa projection

Description

Projection for ecoregions_matrix

Usage

data(ecoregions)

Format

Projection crs object

Source

doi:10.5061/dryad.315km76

References

Barratt et al. (2013) Molecular Ecology 27:4289–4308


Ecoregion data for East Africa extent

Description

Extent for ecoregions_matrix

Usage

data(ecoregions)

Format

Numeric vector of length length 4

Source

doi:10.5061/dryad.315km76

References

Barratt et al. (2013) Molecular Ecology 27:4289–4308


Ecoregion data for East Africa

Description

Raster data of ecoregions in East Africa

Usage

data(ecoregions)

Format

A matrix to be converted into a SpatRaster object with a EPSG:4210 projection.

Source

doi:10.5061/dryad.315km76

References

Barratt et al. (2013) Molecular Ecology 27:4289–4308


Gaussian random field neutral model

Description

Simulates a gaussian random field as a neutral landscape of the same extent and resolution as the input raster, using the same spatial autocorrelation range as the input

Usage

gauss_random_field_sim(x, corr_range)

Arguments

x

A SpatRaster object.

corr_range

The range of spatial autocorrelation to simulate. Can be estimated using the lisa_clusters function.

Value

A SpatRaster object with boundary elements.

Author(s)

Amy Luo

References

James, P. M. A., Fleming, R.A., & Fortin, M.-J. (2010) Identifying significant scale-specific spatial boundaries using wavelets and null models: Spruce budworm defoliation in Ontario, Canada as a case study. Landscape Ecology, 6, 873-887.

Examples

#' data(grassland)
grassland <- terra::rast(grassland_matrix, crs = grassland_crs)
terra::ext(grassland) <- grassland_ext

corr <- lisa_clusters(grassland)
simulation <- gauss_random_field_sim(grassland, corr)
terra::plot(simulation)

Grassland land cover projection

Description

Projection for grassland_matrix

Usage

data(grassland)

Format

Projection crs object

Source

doi:10.5061/dryad.bk3j9kdhz

References

Cox et al. (2023) Conservation Genetics Radoux et al. (2019) Remote Sens 11:354.


Grassland land cover extent

Description

Extent for grassland_matrix

Usage

data(grassland)

Format

Numeric vector of length length 4

Source

doi:10.5061/dryad.bk3j9kdhz

References

Cox et al. (2023) Conservation Genetics Radoux et al. (2019) Remote Sens 11:354.


Grassland land cover

Description

Raster land cover data from the LifeWatch Wallonia-Brussels ecotope database and used in Cox et al. 2023. Downsampled to match T. cristatus raster

Usage

data(grassland)

Format

A matrix to be converted into a SpatRaster object with a EPSG:4326 projection.

Source

doi:10.5061/dryad.bk3j9kdhz

References

Cox et al. (2023) Conservation Genetics Radoux et al. (2019) Remote Sens 11:354.


Leptopelis concolor genetic groups projection

Description

Projection

Usage

data(L.concolor)

Format

Projection crs object

Source

doi:10.5061/dryad.315km76

References

Barratt et al. (2013) Molecular Ecology 27:4289–4308


Leptopelis concolor genetic groups extent

Description

Extent for L.concolor_matrix

Usage

data(L.concolor)

Format

Numeric vector of length length 4

Source

doi:10.5061/dryad.315km76

References

Barratt et al. (2013) Molecular Ecology 27:4289–4308


Leptopelis concolor genetic groups

Description

Raster data representing interpolated genetic group assignments for Leptopelis concolor based on analyses in Barratt et al. 2018.

Usage

data(L.concolor)

Format

A matrix to be converted into a SpatRaster object with a EPSG:4210 projection.

Source

doi:10.5061/dryad.315km76

References

Barratt et al. (2013) Molecular Ecology 27:4289–4308


Leptopelis flavomaculatus genetic groups projection

Description

Projection for L.flavomaculatus_matrix

Usage

data(L.flavomaculatus)

Format

Projection crs object

Source

doi:10.5061/dryad.315km76

References

Barratt et al. (2013) Molecular Ecology 27:4289–4308


Leptopelis flavomaculatus genetic groups extent

Description

Extent for L.flavomaculatus_ext

Usage

data(L.flavomaculatus)

Format

Numeric vector of length length 4

Source

doi:10.5061/dryad.315km76

References

Barratt et al. (2013) Molecular Ecology 27:4289–4308


Leptopelis flavomaculatus genetic groups

Description

Raster data representing interpolated genetic group assignments for Leptopelis flavomaculatus based on analyses in Barratt et al. 2018.

Usage

data(L.flavomaculatus)

Format

A matrix to be converted into a SpatRaster object with a EPSG:4210 projection.

Source

doi:10.5061/dryad.315km76

References

Barratt et al. (2013) Molecular Ecology 27:4289–4308


Identify LISA clusters

Description

Uses local Moran's I and Monte Carlo simulations to identify LISA clusters

Usage

lisa_clusters(x)

Arguments

x

A SpatRaster object.

Value

An sf polygons object with LISA clusters

Author(s)

Amy Luo

References

Anselin, L. (1995). Local Indicators of Spatial Association—LISA. Geographical Analysis, 27(2), 93–115.


Length of the longest subgraph

Description

Statistical test for the length of the longest subgraph, or set of contiguous boundary elements.

Usage

max_subgraph(x, null_distrib)

Arguments

x

A SpatRaster object with boundary elements.

null_distrib

A list of probability functions output from boundary_null_distrib().

Value

The length of the longest subgraph and a p-value.

Author(s)

Amy Luo

References

Jacquez, G.M., Maruca,I S. & Fortin M.-J. (2000) From fields to objects: A review of geographic boundary analysis. Journal of Geographical Systems, 3, 221, 241.

Examples

data(T.cristatus)
T.cristatus <- terra::rast(T.cristatus_matrix, crs = T.cristatus_crs)
terra::ext(T.cristatus) <- T.cristatus_ext

Tcrist_boundaries <- categorical_boundary(T.cristatus)
T.crist_bound_null <- boundary_null_distrib(T.cristatus, cat = TRUE, n_iterations = 100,
model = 'random_cluster')

max_subgraph(Tcrist_boundaries, T.crist_bound_null)

Modified random cluster neutral landscape model

Description

Simulates a neutral landscape of the same extent and resolution as the input raster, with the same distribution of values.

Usage

mod_random_clust_sim(x, p)

Arguments

x

A SpatRaster object.

p

The proportion of cells to be marked in percolated raster. Higher values of p produce larger clusters.

Value

A SpatRaster object with boundary elements.

Author(s)

Amy Luo

References

Saura, S. & Martínez-Millán, J. (2000) Landscape patterns simulation with a modified random clusters method. Landscape Ecology, 15, 661 – 678.

Examples

data(grassland)
grassland <- terra::rast(grassland_matrix, crs = grassland_crs)
terra::ext(grassland) <- grassland_ext

simulation <- mod_random_clust_sim(grassland, p = 0.6)
terra::plot(simulation)

Number of subgraphs

Description

Statistical test the for number of subgraphs, or sets of contiguous boundary elements, in the data.

Usage

n_subgraph(x, null_distrib)

Arguments

x

A SpatRaster object with boundary elements.

null_distrib

A list of probability functions output from boundary_null_distrib().

Value

The number of subgraphs in the raster and a p-value.

Author(s)

Amy Luo

References

Jacquez, G.M., Maruca,I S. & Fortin M.-J. (2000) From fields to objects: A review of geographic boundary analysis. Journal of Geographical Systems, 3, 221, 241.

Examples

data(T.cristatus)
T.cristatus <- terra::rast(T.cristatus_matrix, crs = T.cristatus_crs)
terra::ext(T.cristatus) <- T.cristatus_ext

T.crist_boundaries <- categorical_boundary(T.cristatus)
T.crist_bound_null <- boundary_null_distrib(T.cristatus, cat = TRUE, n_iterations = 100,
model = 'random_cluster')

n_subgraph(T.crist_boundaries, T.crist_bound_null)

Direct overlap between boundary elements.

Description

Statistical test for the number of directly overlapping boundary elements of two traits.

Usage

Odirect(x, y, null_distrib)

Arguments

x

A SpatRaster object with boundary elements.

y

A SpatRaster object with boundary elements.

null_distrib

A list of probability functions output from overlap_null_distrib().

Value

The number of directly overlapping boundary elements and a p-value.

Author(s)

Amy Luo

References

Jacquez, G.M., Maruca,I S. & Fortin, M.-J. (2000) From fields to objects: A review of geographic boundary analysis. Journal of Geographical Systems, 3, 221, 241. Fortin, M.-J., Drapeau, P. & Jacquez, G.M. (1996) Quantification of the Spatial Co-Occurrences of Ecological Boundaries. Oikos, 77, 51-60.

Examples

data(T.cristatus)
T.cristatus <- terra::rast(T.cristatus_matrix, crs = T.cristatus_crs)
terra::ext(T.cristatus) <- T.cristatus_ext

data(grassland)
grassland <- terra::rast(grassland_matrix, crs = grassland_crs)
terra::ext(grassland) <- grassland_ext

Tcrist_ovlp_null <- overlap_null_distrib(T.cristatus, grassland, rand_both = FALSE,
  x_cat = TRUE, n_iterations = 100, x_model = 'random_cluster')
Tcrist_boundaries <- categorical_boundary(T.cristatus)
grassland_boundaries <- define_boundary(grassland, 0.1)

Odirect(Tcrist_boundaries, grassland_boundaries, Tcrist_ovlp_null)

Null distribution for boundary overlap statistics

Description

Creates custom probability distributions for three boundary overlap statistics (directly overlapping boundary elements, minimum distance between boundary elements in x to y, and minimum distance between elements in x and y). Given two SpatRaster objects with the same extent, projection, and resolution, simulates n iterations of random raster surfaces from neutral model(s).

Usage

overlap_null_distrib(
  x,
  y,
  rand_both,
  x_convert = FALSE,
  y_convert = FALSE,
  x_cat = FALSE,
  y_cat = FALSE,
  threshold = 0.2,
  n_iterations = 10,
  x_model = "random",
  y_model = "random",
  px = 0.5,
  py = 0.5,
  progress = TRUE
)

Arguments

x

A SpatRaster object. If rand_both = FALSE, only this raster will be modeled.

y

A SpatRaster object. If rand_both = FALSE, this raster does not change.

rand_both

TRUE if distribution of traits in x and y should be modeled.

x_convert

TRUE if x contains numeric trait data that needs to be converted to boundary intensities. default = FALSE.

y_convert

TRUE if y contains numeric trait data that needs to be converted to boundary intensities. default = FALSE.

x_cat

TRUE if x contains a categorical variable. default = FALSE.

y_cat

TRUE if y contains a categorical variable. default = FALSE.

threshold

A value between 0 and 1. The proportion of cells to keep as boundary elements. Default = 0.2.

n_iterations

An integer indicating the number of iterations for the function. A value of 100 or 1000 is recommended to produce sufficient resolution for downstream statistical tests. default = 10.

x_model

Neutral model to use. Options: 'random' (stochastic), 'gaussian' (Gaussian random field), and 'random_cluster' (modified random clusters method)

y_model

Neutral model to use for y.

px

If using modified random clusters for x, proportion of cells to be marked in percolated raster. Higher values of p produce larger clusters. Default = 0.5

py

If using modified random clusters for y, proportion of cells to be marked in percolated raster. Higher values of p produce larger clusters. Default = 0.5

progress

If progress = TRUE (default) a progress bar will be displayed.

Value

A list of probability distribution functions for boundary overlap statistics.

Author(s)

Amy Luo

References

Saura, S. & Martínez-Millán, J. (2000). Landscape patterns simulation with a modified random clusters method. Landscape Ecology, 15:661-678.

Examples

data(T.cristatus)
T.cristatus <- terra::rast(T.cristatus_matrix, crs = T.cristatus_crs)
terra::ext(T.cristatus) <- T.cristatus_ext

data(grassland)
grassland <- terra::rast(grassland_matrix, crs = grassland_crs)
terra::ext(grassland) <- grassland_ext

Tcrist_ovlp_null <- overlap_null_distrib(T.cristatus, grassland, rand_both = FALSE,
  x_cat = TRUE, n_iterations = 100, x_model = 'random_cluster')

Average minimum distance from x boundary elements to nearest y boundary element.

Description

Statistical test for the average minimum distance between each boundary element in raster x and the nearest boundary element in raster y. Uses Euclidean distance. The boundaries of trait x depend on the boundaries of trait y.

Usage

Ox(x, y, null_distrib)

Arguments

x

A SpatRaster object with boundary elements.

y

A SpatRaster object with boundary elements.

null_distrib

A list of probability functions output from overlap_null_distrib().

Value

The average minimum distance and a p-value.

Author(s)

Amy Luo

References

Jacquez, G.M., Maruca,I S. & Fortin,M.-J. (2000) From fields to objects: A review of geographic boundary analysis. Journal of Geographical Systems, 3, 221, 241. Fortin, M.-J., Drapeau, P. & Jacquez, G.M. (1996) Quantification of the Spatial Co-Occurrences of Ecological Boundaries. Oikos, 77, 51-60.

Examples

data(T.cristatus)
T.cristatus <- terra::rast(T.cristatus_matrix, crs = T.cristatus_crs)
terra::ext(T.cristatus) <- T.cristatus_ext

data(grassland)
grassland <- terra::rast(grassland_matrix, crs = grassland_crs)
terra::ext(grassland) <- grassland_ext

Tcrist_ovlp_null <- overlap_null_distrib(T.cristatus, grassland, rand_both = FALSE,
  x_cat = TRUE, n_iterations = 100, x_model = 'random_cluster')
Tcrist_boundaries <- categorical_boundary(T.cristatus)
grassland_boundaries <- define_boundary(grassland, 0.1)

Ox(Tcrist_boundaries, grassland_boundaries, Tcrist_ovlp_null)

Average minimum distance between boundary elements of two variables

Description

Statistical test for the average minimum distance between boundary elements in two raster layers. Uses Euclidean distance. Boundaries for each trait affect one another reciprocally (x affects y and y affects x).

Usage

Oxy(x, y, null_distrib)

Arguments

x

A SpatRaster object with boundary elements.

y

A SpatRaster object with boundary elements.

null_distrib

A list of probability functions output from overlap_null_distrib().

Value

p-value

Author(s)

Amy Luo

References

Jacquez, G.M., Maruca,I S. & Fortin, M.-J. (2000) From fields to objects: A review of geographic boundary analysis. Journal of Geographical Systems, 3, 221, 241. Fortin, M.-J., Drapeau, P. & Jacquez, G.M. (1996) Quantification of the Spatial Co-Occurrences of Ecological Boundaries. Oikos, 77, 51-60.

Examples

data(T.cristatus)
T.cristatus <- terra::rast(T.cristatus_matrix, crs = T.cristatus_crs)
terra::ext(T.cristatus) <- T.cristatus_ext

data(grassland)
grassland <- terra::rast(grassland_matrix, crs = grassland_crs)
terra::ext(grassland) <- grassland_ext

Tcrist_ovlp_null <- overlap_null_distrib(T.cristatus, grassland, rand_both = FALSE,
  x_cat = TRUE, n_iterations = 100, x_model = 'random_cluster')
Tcrist_boundaries <- categorical_boundary(T.cristatus)
grassland_boundaries <- define_boundary(grassland, 0.1)

Oxy(Tcrist_boundaries, grassland_boundaries, Tcrist_ovlp_null)

Map the boundary elements of two raster layers

Description

This is a wrapper function for ggplot2 that will produce a map of boundary elements for two traits and show where boundary elements intersect.

Usage

plot_boundary(x, y, color = NA, trait_names = NA)

Arguments

x

A SpatRaster object with boundary elements.

y

A SpatRaster object with boundary elements.

color

Optional. A character vector of up to three colors (x boundary, y boundary, and overlapping elements).

trait_names

Optional. A character vector with up to two elements (legend name for x and legend name for y).

Value

A ggplot2 object.

Author(s)

Amy Luo

Examples

data(T.cristatus)
T.cristatus <- terra::rast(T.cristatus_matrix, crs = T.cristatus_crs)
terra::ext(T.cristatus) <- T.cristatus_ext

data(grassland)
grassland <- terra::rast(grassland_matrix, crs = grassland_crs)
terra::ext(grassland) <- grassland_ext

Tcrist_boundaries <- categorical_boundary(T.cristatus)
grassland_boundaries <- define_boundary(grassland, 0.1)

plot_boundary(Tcrist_boundaries, grassland_boundaries)

Stochastic neutral landscape model

Description

Simulates a spatially stochastic neutral landscape of the same extent and resolution as the input raster, with the same distribution of values.

Usage

random_raster_sim(x)

Arguments

x

A SpatRaster object.

Value

A SpatRaster object with boundary elements.

Author(s)

Amy Luo

References

James, P. M. A., Fleming, R.A., & Fortin, M.-J. (2010) Identifying significant scale-specific spatial boundaries using wavelets and null models: Spruce budworm defoliation in Ontario, Canada as a case study. Landscape Ecology, 6, 873-887.

Examples

data(grassland)
grassland <- terra::rast(grassland_matrix, crs = grassland_crs)
terra::ext(grassland) <- grassland_ext

simulation <- random_raster_sim(grassland)
terra::plot(simulation)

Sobel-Feldman operator for edge detection

Description

Uses a Sobel-Feldman operator (3x3 kernel) to detect internal edges in a SpatRaster object.

Usage

sobel_operator(x)

Arguments

x

A SpatRaster object.

Value

A SpatRaster object with boundary values.

Author(s)

Amy Luo

Examples

data(T.cristatus)
T.cristatus <- terra::rast(T.cristatus_matrix, crs = T.cristatus_crs)
terra::ext(T.cristatus) <- T.cristatus_ext

edges <- sobel_operator(T.cristatus)
terra::plot(edges)

Triturus cristatus genetic groups projection

Description

Projection for T.cristatus_matrix

Usage

data(T.cristatus)

Format

ces Barratt et al. (2013) Molecular Ecology 27:4289–4308

Projection crs object

Source

doi:10.5061/dryad.bk3j9kdhz

References

Cox et al. (2023) Conservation Genetics


Triturus cristatus genetic groups extent

Description

Extent for T.cristatus_matrix

Usage

data(T.cristatus)

Format

Numeric vector of length length 4

Source

doi:10.5061/dryad.bk3j9kdhz

References

Cox et al. (2023) Conservation Genetics


Triturus cristatus genetic groups

Description

Raster data representing interpolated genetic group assignments for Triturus cristatus based on analyses in Cox et al. 2023

Usage

data(T.cristatus)

Format

A matrix to be converted into a SpatRaster object with a EPSG:4326 projection.

Source

doi:10.5061/dryad.bk3j9kdhz

References

Cox et al. (2023) Conservation Genetics