machu.2.ace: Perform ancestral character estimation of response curves

In wxguillo/machuruku: Ancestral niche reconstruction

Perform ancestral character estimation of response curves

Description

Extract reconstructed response curve parameters at a given set of timeslices, or at each tip and node

Usage

machu.2.ace(
  tip.resp,
  tree,
  timeslice = NULL,
  unc = F,
  csv.name = NULL,
  ace.method = "REML",
  verbose = F
)

Arguments

tip.resp	Output of machu.1.tip.resp().
tree	Phylogenetic tree, a phylo object. Must be ultrametric, and taxon names must match those of 'tip.resp' exactly.
timeslice	A numeric vector giving the timeslices to extract reconstructed climate response values from. If NULL, provides values for the tips and nodes of the tree. All values must be less than the overall height of the tree.
unc	If TRUE, output upper and lower confidence intervals for each climate response value. Default = F.
csv.name	A string that specifies the output CSV file's location and name. Should include .csv extension. Will be saved to getwd() unless another path is specified.
ace.method	A string that specifies to ape::ace() which 'method' to use. Options are "REML" and "ML". See ?ape::ace for more details. Default = "REML".
verbose	Print progress updates and output file location/name to screen. Default = F.

Details

This function uses ace() from the package "ape" to generate climate response curves at each node of a time-calibrated phylogeny, and extracts the values along the branches at a particular time if so desired. By default, the output is a set of climate response curve parameters for each node and each tip in the tree. However, each node occurs at different poitns in time, making paleoclimatic projections tricky. Thus the user can also provide one or more timeslices with the 'timeslice' parameter. The function will find each branch present at each timeslice and interpolate the response curve parameters along the branches to those points in time. The function can also record uncertainty in ancestral character estimation with the 'unc' parameter.

You can use phytools::force.ultrametric() to fix small deviations from ultrametricity in your tree. If you are using an alternative tree format from ape's 'phylo' format, the function will automatically attempt to convert it to phylo. If it fails, the function will probably break down the line. Try to convert to 'phylo' yourself before using it in the function.

You should use a dated tree with this function, otherwise your projections into paleoclimate data will not make much sense. If you're really desperate, you can try ape::chronos() to get a quick-and-dirty dated tree, but I doubt it would be acceptable for publication. Really you should be using the output of time-calibration software such as BEAST or RelTime.

The 'timeslice' parameter uses linear interpolation to calculate values for each "branch-taxon". For example, timeslice=1e6 will detect which branches exist at 1 Ma, and perform a linear interpolation of climate response values using the values at the subtending nodes/tips. See Guillory & Brown (2021) for a more detailed explanation. Of course, make sure to specify timeslices in the relative scale your tree's node ages are coded in. For example, BEAST node ages are often in units of millions of years, so "1" would be equivalent to the "1e6" I use in my example.

The 'unc' parameter behavior has been changed for machuruku 2.0. Now setting unc=T only extracts the upper and lower 95% confidence intervals for each climate response parameter provided by ace(). These are automatically incorporated into the Bioclim calculations in machu.3.anc.niche(), producing more conservative niche models. When "tips and nodes" are returned (not timeslices), the tips do not have associated confidence intervals because they are held over from the 'tip.resp' input, not produced via ace().

Use machu.ace.load() to reload outputs saved with 'csv.name'.

Value

A list of one element per scenario, either one or more timeslices or all tips and nodes, each a table of reconstructed climate response parameters.

Examples

# return timeslices for 1 and 3 Ma
ace <- machu.2.ace(tip.resp, tree, timeslice=c(1e6, 3e6))
# same as above, with uncertainty
ace <- machu.2.ace(tip.resp, tree, timeslice=c(1e6, 3e6), unc=T)
# return only tips and nodes
ace <- machu.2.ace(tip.resp, tree)
# same as above, saving output to getwd()
ace <- machu.2.ace(tip.resp, tree, csv.name="ace.csv")

wxguillo/machuruku documentation built on Jan. 23, 2025, 3:25 p.m.