paleotree (version 3.4.7)

exhaustionFunctions: 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
)

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.

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.

Author

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

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.

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

# \donttest{

# 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")

# }