exhaustionFunctions: Analyses of the exhaustion of Character States Over...

In paleotree: Paleontological and Phylogenetic Analyses of Evolution

Analyses of the exhaustion of Character States Over Evolutionary History

Description

The following functions are for measuring and fitting various distributions to the gradual exhaustion of unexpressed character states, as originally described by Wagner (2000, Evolution).

Usage

accioExhaustionCurve(
  phyloTree,
  charData,
  charTypes = "unordered",
  outgroup = NULL,
  firstAppearances = NULL,
  missingCharValue = "?",
  inapplicableValue = "-"
)

accioBestAcquisitionModel(
  exhaustion_info,
  changesType,
  models = c("exponential", "gamma", "lognormal", "zipf")
)

charExhaustPlot(
  exhaustion_info,
  changesType,
  xlab = "Total Characters",
  ylab = NULL,
  main = NULL,
  xsize = 3
)

Arguments

phyloTree	A phylogenetic tree of class phylo as used by package ape.
charData	A data.frame of morphological character codings (a morphological 'matrix'), with taxon units as rows and characters as columns.
charTypes	A vector of length equal to the number of characters in charData, with elements indicating whether the corresponding character in charData is "unordered" or "ordered". However, if length(charTypes) = 1, then it is repeated for all taxa. The default value for this argument is "unordered".
outgroup	A string matching to one of the tip labels as given by tip.label,
firstAppearances	A vector, with length equal to the same number of taxa (rows) as in charData, in the same corresponding order.
missingCharValue	The string value indicating a missing character coding value, by default "?".
inapplicableValue	The string value indicating an inapplicable character coding value, by default "-".
exhaustion_info	The list of results output from function accioExhaustionCurve.
changesType	A single character value, indicating the character change data to be assessed from the result of the character exhaustion analysis, must be one of either 'totalAcc' (to the total number of accumulated character changes, ideal for modeling the size and distribution of state space) or 'charAlt' (to plot the total number of character alterations, ideal for modeling the size and distribution of character space).
models	A vector of type character naming various models to be fit. The default fits the models "exponential", "gamma", "lognormal", and "zipf".
xlab	Label for the X axis; "Total Characters" by default.
ylab	Label for the Y axis. If not provided by the user, a label based on the changesType argument will be used.
main	Main title label for the plot. If not provided by the user, a label based on the changesType argument will be used.
xsize	Parameter controlling size of the axes, which are forced to be symmetric.

Details

accioExhaustionCurve uses a Sankoff parsimony ancestral-reconstruction algorithm (written by P.J. Wagner, not the one from phangorn used elsewhere in paleotree) to calculate character changes across each branch (internode edge) of a tree, and then reports the counts of character state

accioBestAcquisitionModel takes output from accioExhaustionCurve, calculates one of two character change indices, and then fits a series of user-selected models to the dataset, returning details pertaining to the best-fit model.

charExhaustPlot is a wrapper for accioBestAcquisitionModel that produces a plot of the observed character change data against the expectation under the best-fit model.

The functions accioBestAcquisitionModel and charExhaustPlot offer users two different options for examining character change: totalAcc fits models to the total accumulated number of state changes over the phylogeny, thus using exhaustion to explore the size and distribution of character space. The other option charAlt fits models to the number of character that alter from primitive to derived over phylogeny, thus reflecting the size and distribution of state space.

accioExhaustionCurve can order its reconstruction of change by stratigraphic order of first appearances. It is unclear what this means.

Value

accioExhaustionCurve outputs a list containing two objects: first, a matrix named exhaustion consisting of three columns: "Steps", "Novel_States", and "Novel_Characters", respectively giving the counts of these respective values for each branch (internode edge). The second element of this list is named State_Derivations and is a count of how often each state, across all characters, was derived relative to the primitive position along each internode edge.

The output of accioBestAcquisitionModel is a list object containing information on the best-fit model, the parameters of that model, and the calculated probability distribution function for that model at the same intervals (for use in quantile plots).

charExhaustPlot produces a plot, and outputs no data.

Note

This family of functions presented here were originally written by Peter J. Wagner, and then modified and adapted by David W. Bapst for wider release in a CRAN-distributed package: paleotree. This makes the code presented here a very different beast than typical paleotree code, for example, there are fewer tests of correct input type, length, etc.

Author(s)

Initially written by Peter J. Wagner, with modification and documentation by David W. Bapst.

References

Wagner, P. J. 2000. Exhaustion of morphologic character states among fossil taxa. Evolution 54(2):365-386.

See Also

Also see paleotree functions minCharChange and ancPropStateMat, the latter of which is a wrapper for phangorn's function ancestral.pars.

Examples

# get data
data(SongZhangDicrano)

dicranoTree <- cladogramDicranoX13

# modify char data
charMat <- data.matrix(charMatDicrano)
charMat[is.na(charMatDicrano)] <- 0
charMat <- (charMat-1)
colnames(charMat) <- NULL
# replace missing values
charMat[is.na(charMatDicrano)] <- "?"

# the 'outgroup' is Exigraptus
   # also the first taxon listed in the matrix
exhaustionResults <- accioExhaustionCurve(
   phyloTree = dicranoTree,
   charData = charMat, charTypes = "unordered",
   outgroup = "Exigraptus_uniformis")

# fits models to exhaustion for total accumulation
accioBestAcquisitionModel(
   exhaustion_info = exhaustionResults,
   changesType = "totalAcc", 	
   models = c("exponential","gamma","lognormal","zipf")) 

# plot of exhaustion of total accumulation of character states
charExhaustPlot(exhaustion_info = exhaustionResults,
	   changesType = "totalAcc")

# plot of exhaustion of character alterations
charExhaustPlot(exhaustion_info = exhaustionResults,
	   changesType = "charAlt")

	

paleotree documentation built on Aug. 22, 2022, 9:09 a.m.