bin_table {nichevol}

Bin table of environmental conditions in M and for occurrences

Description

bin_table helps in creating a bin table of environmental conditions in accessible areas (M) and for species occurrence records (i.e., table of characters).

Usage

bin_table(Ms, occurrences, species, longitude, latitude, variable,
          percentage_out = 5, n_bins = 20, bin_size, verbose = TRUE)

Arguments

Ms

a list of SpatVector objects representing the accessible area (M) for all species to be analyzed. The order of species represented by each object here must coincide with the one in occurrences. See details.

occurrences

a list of data.frames of occurrence records for all species. The order of species represented by each data.frame must coincide with the one in Ms. See details.

species

(character) name of the column in occurrence data.frames that contains the name of the species.

longitude

(character) name of the column in occurrence files containing values of longitude.

latitude

(character) name of the column in occurrence files containing values of latitude.

variable

a single SpatRaster layer representing an environmental variable of interest. See details.

percentage_out

(numeric) percentage of extreme environmental data in M to be excluded in bin creation for further analyses. See details. Default = 5.

n_bins

(numeric) number of bins to be created from the range of environmental values considered when creating each character in bin tables. Default = 20. See details.

bin_size

(numeric) argument deprecated, use n_bins instead.

verbose

(logical) whether messages should be printed. Default = TRUE.

Details

Coordinates in occurrences, SpatVector objects in Ms, and SpatRaster in variable must coincide in the geographic projection in which they are represented. WGS84 with no planar projection is recommended.

Accessible area (M) is understood as the geographic area that has been accessible for a species for relevant periods of time. Defining M is usually a hard task, but also a very important one, because it allows identifying uncertainties about the ability of a species to maintain populations in certain environmental conditions. For further details on this topic, see Barve et al. (2011) doi:10.1016/j.ecolmodel.2011.02.011 and Machado-Stredel et al. (2021) doi:10.21425/F5FBG48814.

The percentage to be defined in percentage_out excludes a percentage of extreme environmental values to prevent from considering extremely rare environmental values in the accessible area for the species (M). Being too rare, these values may have never been explored by the species; therefore, including them in the process of preparation of the table of characters (bin table) is risky.

The argument n_bins helps to define how many characters (bins) will be considered for the range of values in each variable. This is, a value of 20 determines that a range of temperature (5-25) will be split approximately every 1 degree. The argument bin_size has been deprecated.

Value

A list containing a table of characters to represent ecological niches of the species of interest.

Potential values for characters are:

• "1" = the species is present in those environmental conditions.

• "0" = the species is not present in those environmental conditions. This is, those environmental conditions inside the accessible area (M) are more extreme than the ones used for the species.

• "?" = there is no certainty about the species presence in those environmental conditions. This happens in environmental combinations more extreme than the ones found in the accessible area (M), when environmental conditions in species records are as extreme as the most extreme ones in M.

Examples

# example data
## list of species records
data("occ_list", package = "nichevol")

## list of species accessible areas
m_files <- list.files(system.file("extdata", package = "nichevol"),
                      pattern = "m\\d.gpkg", full.names = TRUE)

m_list <- lapply(m_files, terra::vect)

## raster variable
temp <- terra::rast(system.file("extdata", "temp.tif", package = "nichevol"))


# preparing bins
char_table <- bin_table(Ms = m_list, occurrences = occ_list, species = "species",
                        longitude = "x", latitude = "y", variable = temp,
                        percentage_out = 5, n_bins = 20)