Prepares a presence-absence matrix (PAM) in which all sites of interest (rows) will have a value for presence or absence of a species of interest (columns). Initial points of interest will be represented by an ID, and longitude and latitude coordinates. The PAM will be linked to a spatial grid.
Usage
prepare_base_PAM(data, format = NULL, master_matrix = NULL, region = NULL,
cell_size, complete_cover = TRUE, clip_grid = FALSE,
indices = "basic", parallel = FALSE, n_cores = NULL,
verbose = TRUE)Arguments
- data
species geographic ranges to be used to create a presence-absence matrix (PAM). This argument can be: character, data.frame, SpatRaster, list, or SpatVector. See details for a description of the characteristics of data for each option.
- format
(character) if
datais of class character, available options are: "shp", "gpkg", "GTiff", and "ascii".- master_matrix
object of class "master_matrix" or "master_selection". See details. Default = NULL. Either this argument or
regionmust be defined.- region
SpatVector of the region of interest; for instance, a country, another type of administrative are, or a protected area. Default = NULL. Either this argument or
master_matrixmust be defined. Ignored ifmaster_matrixis defined.- cell_size
(numeric) resolution for grid (single number or vector of two numbers) in kilometers (km).
- complete_cover
(logical) whether or not to include cells of grid partially overlapped with the geographic region of interest contained in
master_matrix. Default = TRUE.- clip_grid
(logical) whether to clip the spatial grid using the region of interest. Clipping improves visualization but depending on how complex the region of interest is it could take time to perform this task.
- indices
(character) code for indices to be calculated. Basic indices are calculated all the time, other indices need to be specified. Options are: "all", "basic, "AB", "BW", "BL", "SCSC", "SCSR", "DF", "DivF", "CC", "WRN", "SRC", "CMSC", and "CMSR". Default = "basic". See details.
- parallel
(logical) whether to perform analyses in parallel. Default = FALSE. Not used if data is of class data.frame, or SpatRaster.
- n_cores
(numeric) number of cores to be used when
parallel= TRUE. The default, NULL, uses available cores - 1.- verbose
(logical) whether or not to print messages about the process. Default = TRUE.
Value
A presence-absence matrix (PAM) of class base_PAM for the
region of interest associated with a SpatVector, as in a grid
of cell_size resolution. Each grid cell is related to a specific ID
and longitude and latitude coordinates. Presence (1) and absence (0) values
for each species in every cell of the PAM are included as apart of the
data.frame of the SpatVector. PAM indices is returned with the
basic indices of biodiversity as default, but can be changed using the
argument indices.
Details
Objects of class "master_matrix" or "master_selection" can be obtained from
functions prepare_master_matrix,
random_selection, uniformG_selection,
uniformE_selection, or uniformEG_selection. The element
region or mask if this last is not NULL is used to prepare the spatial grid.
Geographic projection of objects or coordinates involved must be WGS84 (EPSG:4326).
Description of objects to be used as data:
character.- name of directory containing raster, shapefiles or geopackage files representing species geographic ranges. Each file must be named as the species that it represents. All files must be in the same format. If files are in raster format, "GTiff" and "ascii" are acceptable extensions; values in each layer must be 1 (presence) and 0 (absence).
data.frame.- a table containing three columns. Columns must be in the following order: Longitude, Latitude, Species.
SpatRaster.- Each layer must be named as the species which range it represents, and values in each layer must be 1 (presence) and 0 (absence).
list.- a list of SpatRaster objects that cannot be stacked because of extent or resolution differences. Each element of the list must be named as the species which range it represents, and values in each SpatRaster must be 1 (presence, suitable) and 0 (absence, unsuitable).
SpatVector.- object representing species' geographic ranges. The data.frame associated with the object must contain a column named "Species" to distinguish among features representing each species range.
SpatVector.- object of spatial points where each record of a species must be a point. The associated data.frame must contain the following columns (in that order): Longitude, Latitude, Species.
A list of codes and indices that can be calculated is described below. For further details on the way calculations are performed and the meaning of the indices see Soberon and Cavner (2015) doi:10.17161/bi.v10i0.4801 .
| Code | Index | Calculation |
| RI | Richness | Basic |
| RA | Range | Basic |
| RIN | Richness normalized | Basic |
| RAN | Range normalized | Basic |
| AB | Additive Beta | Needs to be defined |
| BW | Beta Whittaker | Needs to be defined |
| BL | Beta Legendre | Needs to be defined and DF |
| SCSC | Schluter covariance sites-composition | Needs to be defined and CMSC |
| SCSR | Schluter covariance species-ranges | Needs to be defined and CMSR |
| DF | Dispersion field | Needs to be defined |
| DivF | Diversity field | Needs to be defined |
| SCC | Shared community composition | Needs to be defined |
| WRN | Wright-Reeves nestedness | Needs to be defined, BW, and DF |
| SRC | Stone-Roberts C-score | Needs to be defined and DF |
| CMSC | Covariance matrix sites-composition | Needs to be defined, DF, and BW |
| CMSR | Covariance matrix species-ranges | Needs to be defined, SCC, and BW |
| MCC | Mean composition covariance | Calculated with CMSC |
| MRC | Mean range covariance | Calculated with CMSR |
Examples
# Data
m_matrix <- read_master(system.file("extdata/m_matrix.rds",
package = "biosurvey"))
species_data <- terra::vect(system.file("extdata/species_data.gpkg",
package = "biosurvey"))
# Create base_PAM
b_pam <- prepare_base_PAM(data = species_data, master_matrix = m_matrix,
cell_size = 100)
#> Preparing spatial grid
#> Preprocessing 'data'
#>
|
| | 0%
|
|=== | 4%
|
|====== | 8%
|
|========= | 12%
|
|============ | 17%
|
|=============== | 21%
|
|================== | 25%
|
|==================== | 29%
|
|======================= | 33%
|
|========================== | 38%
|
|============================= | 42%
|
|================================ | 46%
|
|=================================== | 50%
|
|====================================== | 54%
|
|========================================= | 58%
|
|============================================ | 62%
|
|=============================================== | 67%
|
|================================================== | 71%
|
|==================================================== | 75%
|
|======================================================= | 79%
|
|========================================================== | 83%
|
|============================================================= | 88%
|
|================================================================ | 92%
|
|=================================================================== | 96%
|
|======================================================================| 100%
#>
#> Preparing PAM from information
#> Calculating PAM indices
terra::plot(b_pam$PAM)
summary(b_pam)
#>
#> Summary of a base_PAM object
#> ---------------------------------------------------------------------------
#>
#> Presence-absence matrix:
#> Number of cells: 266
#> Number of species: 25
#>
#> Spatial object representing the PAM:
#> class : SpatVector
#> geometry : polygons
#> dimensions : 266, 28 (geometries, attributes)
#> extent : -117.9082, -86.02088, 14.59585, 32.95524 (xmin, xmax, ymin, ymax)
#> coord. ref. : lon/lat WGS 84
#> names : ID Longitude Latitude Species_1 Species_2 Species_3 Species_4
#> type : <num> <num> <num> <num> <num> <num> <num>
#> values : 5 -114.5 32.47 0 0 0 0
#> 6 -113.6 32.47 0 0 0 0
#> 7 -112.6 32.47 0 0 0 0
#> Species_5 Species_6 Species_7 (and 18 more)
#> <num> <num> <num>
#> 0 0 0
#> 0 0 0
#> 0 0 0