map_nichevol {nichevol}

Maps of niche reconstructions and changes detected

Description

map_nichevol produces a SpatRaster layer representing geographic areas corresponding to environmental bins of niche or events of niche evolution detected in reconstructions.

Usage

map_nichevol(whole_rec_table, variable, return = "niche", from, to = NULL,
             id_unknown = TRUE, verbose = TRUE)

Arguments

whole_rec_table

matrix of environmental bins for all tips and nodes derived from functions bin_par_rec or bin_ml_rec.

variable

a SpatRaster layer corresponding to the variable for which the reconstruction was performed (represented in whole_rec_table).

return

(character) type of result to return. Options are: "niche", "evolution", or "nichevol" (a combination of both). Default = "niche". If "niche", values correspond to that defined in from. See Value.

from

(character) if return = "niche" tip or node for which layer will be prepared, otherwise, initial node from which niche comparison will be performed. See example.

to

(character) valid if return = "evolution" or "nichevol". Tip or node to compare against from to detected changes. Default = NULL. See example.

id_unknown

(logical) whether to identify areas of unknown or uncertain change. Default = TRUE. See details.

verbose

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

Details

Mapping is done following Cobos et al. (2021) doi:10.1111/jav.02868. This allows to represent geographic areas with environments where niche expanded, retracted, or stayed stable (evolution). Niche is represented as presence, absence, or unknown.

Defining id_unknown = TRUE allows to map areas where niche or niche change are uncertain. id_unknown = FALSE returns NA in areas with these characteristics, hence they will not be visible when plotting the resulting map.

Value

A SpatRaster object classified according to values of niche in whole_rec_table, and/or according to niche changes detected in comparisons between an ancestor and a tip, or another more recent ancestor.

Options of values resulting from classifications are as follow:

If return = "niche":

ID	category
0	Absent
10	Unknown
100	Present

If return = "evolution":

ID	category
0	Stable
1	Expansion low
3	Expansion high
2	Retraction high
4	Retraction low
10	Unknown

If return = "nichevol":

ID	category
0	Stable
1	Expansion low
3	Expansion high
10	Unknown
100	Present
102	Retraction high
104	Retraction low

Examples

# a tree
data("tree", package = "nichevol")

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

# results from reconstruction
data("par_rec_table", package = "nichevol")

# rename tree tips
tree$tip.label <- rownames(par_rec_table)[1:6]

# check in plot
plot.phylo(tree, label.offset = 0.02)
nodelabels()
nichevol_labels(tree, par_rec_table)

# mapping nichevol
nevol_map <- map_nichevol(whole_rec_table = par_rec_table, variable = temp,
                          return = "nichevol", from = "9", to = "RD 6933")

terra::plot(nevol_map)