nichevol_bars: PNG bar figures for representing niche evolution

In nichevol: Tools for Ecological Niche Evolution Assessment Considering Uncertainty

PNG bar figures for representing niche evolution

Description

nichevol_bars produces bar plots that represent how species' niches (considering one environmental variable at a time) have evolved. Bars are exported as png figures to an output directory for posterior use.

Usage

nichevol_bars(tree, whole_rec_table, ancestor_line = FALSE,
              present = "1", absent = "0", unknown = "?",
              present_col = "#252525", unknown_col = "#d9d9d9",
              no_change_col = "#b2df8a", retraction_col = "#984ea3",
              expansion_col = "#4daf4a", width = 50, height = 5,
              res = 300, output_directory, overwrite = FALSE)

Arguments

tree	an object of class "phylo".
whole_rec_table	matrix of reconstructed bins for nodes and species derived from a process of maximum parsimony reconstruction.
ancestor_line	controls whether ancestor line is plotted. Default = FALSE.
present	(character) code indicating environmental bins in which the species is present. Default = "1".
absent	(character) code indicating environmental bins in which the species is absent. Default = "0".
unknown	(character) code indicating environmental bins in which the species presence is unknown (uncertain). Default = "?".
present_col	color for line representing environments where the species is present. Default = "#252525".
unknown_col	color for line representing environments where the species presence is unknown (uncertain). Default = "#d9d9d9".
no_change_col	color for area of the bar representing environments where no change has been detected. Default = "#b2df8a".
retraction_col	color for area of the bar representing environments where niche retraction has been detected. Default = "#984ea3".
expansion_col	color for area of the bar representing environments where niche expansion has been detected. Default = "#4daf4a".
width	(numeric) width of the device in mm to be passed to the png function. Default = 50.
height	(numeric) height of the device in mm to be passed to the png function. Default = 5.
res	(numeric) nominal resolution in ppi to be passed to the png function. Default = 300.
output_directory	(character) name of the folder in which results will be written. The directory will be created as part of the process.
overwrite	(logical) whether or not to overwrite existing results in output_directory. Default = FALSE.

Details

Evolution of ecological niches is represented in one environmental dimension with horizontal bars indicating if the niche of the descendant has expanded, retracted, or has not changed compared to its ancestor. Lower values of environmental variables are represented in the left part of the bar, higher values at the right.

Changes in niches (evolution) are defined as follows:

• if (ancestor == present & descendant == absent) change <- "retraction"

• if (ancestor == present & descendant == present) change <- "no_change"

• if (ancestor == present & descendant == unknown) change <- "no_change"

• if (ancestor == absent & descendant == present) change <- "expansion"

• if (ancestor == absent & descendant == absent) change <- "no_change"

• if (ancestor == absent & descendant == unknown) change <- "no_change"

• if (ancestor == unknown & descendant == absent) change <- "no_change"

• if (ancestor == unknown & descendant == present) change <- "no_change"

• if (ancestor == unknown & descendant == unknown) change <- "no_change"

If ancestor_line is TRUE, the ancestor line will be plotted on the bar representing niche evolution. The line will represent where, in the range of environmental conditions, the ancestor was present, and where its presence is uncertain (unknown).

Value

A folder named as in output_directory containing all bar figures produced, as well as a legend to describe what is plotted.

Examples

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

# a matrix of niche charactes (1 = present, 0 = absent, ? = unknown)
dataTable <- cbind("241" = rep("1", length(tree5$tip.label)),
                   "242" = rep("1", length(tree5$tip.label)),
                   "243" = c("1", "1", "0", "0", "0"),
                   "244" = c("1", "1", "0", "0", "0"),
                   "245" = c("1", "?", "0", "0", "0"))
rownames(dataTable) <- tree5$tip.label

# list with two objects (tree and character table)
treeWdata <- geiger::treedata(tree5, dataTable)

# Maximum parsimony reconstruction
rec_tab <- smooth_rec(bin_par_rec(treeWdata))

# the running (before running, define a working directory)
nichevol_bars(tree5, rec_tab, output_directory = file.path(tempdir(), "evolbars"))

nichevol documentation built on March 31, 2023, 5:38 p.m.