histograms_env {nichevol}

Histograms of environmental conditions in M and for occurrences

Description

histograms_env creates PDF files with histogram plots of environmental conditions in M, lines for the confidence limits of values in M, and the location of values in occurrence records. This is done using data read directly from a local directory, and can be applied to various species and multiple variables.

Usage

histograms_env(M_folder, M_format, occ_folder, longitude, latitude,
               var_folder, var_format, CL_lines = c(95, 99), col = NULL,
               round = FALSE, round_names = NULL, multiplication_factor = 1,
               save_ranges = FALSE, output_directory, overwrite = FALSE,
               verbose = TRUE)

Arguments

M_folder

(character) name of the folder containing files representing the accessible area (M) for all species to be analyzed. See details.

M_format

format of files representing the accessible area (M) for the species. Names of M files must match the ones for occurrence files in occ_folder. Format options are: "shp", "gpkg", or any of the options supported by rast (e.g., "tif" or "asc").

occ_folder

(character) name of the folder containing csv files of occurrence data for all species. Names of csv files must match the ones of M files in M_folder.

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.

var_folder

(character) name of the folder containing layers to represent environmental variables.

var_format

format of layers to represent environmental variables. Format options are all the ones supported by rast (e.g., "tif" or "asc").

CL_lines

(numeric) confidence limits of environmental values in M to be plotted as lines in the histograms. See details. Default = c(95, 99).

col

colors for lines representing confidence limits. If NULL, colors are selected from a gray palette. Default = NULL.

round

(logical) whether or not to round values of one or more variables after multiplying them times the value in multiplication_factor. Default = FALSE. See details.

round_names

(character) names of the variables to be rounded. Default = NULL. If round = TRUE, names must be defined.

multiplication_factor

(numeric) value to be used to multiply the variables defined in round_names. Default = 1.

save_ranges

(logical) whether or not to save the values identified as ranges considering the whole set of values and confidence limits defined in CL_lines. Default = FALSE.

output_directory

(character) name of the folder in which results will be written.

overwrite

(logical) whether or not to overwrite existing results in output_directory. Default = FALSE.

verbose

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

Details

Coordinates in csv files in occ_folder, SpatVector-like files in M_folder, and raster layers in var_folder 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 under 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.

Rounding variables may be useful when multiple variables are considered and the values of some or all of them are too small (e.g., when using principal components). To round specific variables arguments round, round_names, and multiplication_factor, must be used accordingly.

Value

A list of data.frames containing intervals of environmental values in species occurrences and accessible areas (M), as well as values corresponding to the confidence limits defined in CL_lines. A folder named as in output_directory containing all resulting PDF files (one per variable) with histograms for all species. Files (csv) of ranges found during the analyses will be also written in output_directory if save_ranges is set as TRUE.

Examples

# preparing data and directories for examples
## directories
tempdir <- file.path(tempdir(), "nevol_test")
dir.create(tempdir)

cvariables <- paste0(tempdir, "/variables")
dir.create(cvariables)

records <- paste0(tempdir, "/records")
dir.create(records)

m_areas <- paste0(tempdir, "/M_areas")
dir.create(m_areas)

histdir <- paste0(tempdir, "/Hists")

## data
data("occ_list", package = "nichevol")

temp <- system.file("extdata", "temp.tif", package = "nichevol")

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

## writing data in temporal directories
spnames <- sapply(occ_list, function (x) as.character(x[1, 1]))
ocnames <-  paste0(records, "/", spnames, ".csv")

occs <- lapply(1:length(spnames), function (x) {
  write.csv(occ_list[[x]], ocnames[x], row.names = FALSE)
})

to_replace <- paste0(system.file("extdata", package = "nichevol"), "/")

otemp <- gsub(to_replace, "", temp)
file.copy(from = temp, to = paste0(cvariables, "/", otemp))

file.copy(from = m_files, to = paste0(m_areas, "/", spnames, ".gpkg"))

# running analysis to produce plots
hists <- histograms_env(M_folder = m_areas, M_format = "gpkg",
                        occ_folder = records, longitude = "x",
                        latitude = "y", var_folder = cvariables,
                        var_format = "tif", output_directory = histdir)