| exhaustionFunctions {paleotree} | R Documentation |
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 |
charData |
A |
charTypes |
A vector of length equal to
the number of characters in |
outgroup |
A string matching to one
of the tip labels as given by |
firstAppearances |
A vector, with length equal to the
same number of taxa (rows) as in
|
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 |
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
|
models |
A vector of type |
xlab |
Label for the X axis;
|
ylab |
Label for the Y axis. If not provided by the user,
a label based on the |
main |
Main title label for the plot. If not provided by
the user, a label based on the |
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")