| Type: | Package |
| Title: | Boundary Overlap Statistics |
| Version: | 2.2.0 |
| 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>. |
| License: | GPL (≥ 3) |
| Encoding: | UTF-8 |
| LazyData: | true |
| Imports: | sf, terra, pdqr, methods, ggplot2, tibble, dplyr, magrittr, igraph, fields, scales |
| Depends: | R (≥ 4.1.0) |
| Suggests: | knitr, rmarkdown |
| VignetteBuilder: | knitr |
| RoxygenNote: | 7.2.3 |
| NeedsCompilation: | no |
| Packaged: | 2024-10-20 02:05:47 UTC; AmyLuo |
| Author: | Amy Luo  [aut,
cre, cph],
Elizabeth Derryberry
[ths] |
| Maintainer: | Amy Luo <aluo@vols.utk.edu> |
| Repository: | CRAN |
| Date/Publication: | 2024-10-20 04:00:02 UTC |
Afrixalus delicatus genetic groups projection
Description
Projection for A.delicatus_matrix
Usage
data(A.delicatus)
Format
Projection crs object
Source
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
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
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
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
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
References
Barratt et al. (2013) Molecular Ecology 27:4289–4308
Leptopelis concolor genetic groups projection
Description
Projection
Usage
data(L.concolor)
Format
Projection crs object
Source
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
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
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
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
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
References
Barratt et al. (2013) Molecular Ecology 27:4289–4308
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)
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)
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
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
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
References
Cox et al. (2023) Conservation Genetics
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
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
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
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
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
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
References
Cox et al. (2023) Conservation Genetics Radoux et al. (2019) Remote Sens 11:354.
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)
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')
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)