The likelihood of a PCM represents the probability density function
of observed trait values (data) at the tips of a tree given the tree and
the model parameters. Seen as a function of the model parameters, the
likelihood is used to fit the model to the observed trait data and the
phylogenetic tree (which is typically inferred from another sort of data, such
as an alignment of genetic sequences for the species at the tips of the tree).
The PCMLik function
provides a common interface for calculating the (log-)likelihood of different
PCMs.
Below we denote by N the number of tips, by M the total number of nodes in the
tree including tips, internal and root node, and by k - the number of traits.
PCMLik(X, tree, model, SE = matrix(0, PCMNumTraits(model),
PCMTreeNumTips(tree)), metaI = PCMInfo(X = X, tree = tree, model =
model, SE = SE, verbose = verbose), log = TRUE, verbose = FALSE)a k x N numerical matrix with possible NA and NaN entries. Each
column of X contains the measured trait values for one species (tip in tree).
Missing values can be either not-available (NA) or not existing (NaN).
These two values have are treated differently when calculating
likelihoods: see PCMPresentCoordinates.
a phylo object with N tips.
an S3 object specifying both, the model type (class, e.g. "OU") as well as the concrete model parameter values at which the likelihood is to be calculated (see also Details).
a k x N matrix specifying the standard error for each measurement in
X. Alternatively, a k x k x N cube specifying an upper triangular k x k
factor of the variance covariance matrix for the measurement error
for each node i=1, ..., N.
Default: matrix(0.0, PCMNumTraits(model), PCMTreeNumTips(tree)).
a list returned from a call to PCMInfo(X, tree, model, SE),
containing meta-data such as N, M and k. Alternatively, this can be a
function object that returns such a list, e.g. the functionPCMInfo
or the function PCMInfoCpp from the PCMBaseCpp package.
logical indicating whether a log-likelehood should be calculated. Default is TRUE.
logical indicating if some debug-messages should printed.
a numerical value with named attributes as follows:
A numerical vector of length k specifying the value at the root for which the likelihood value was calculated. If the model contains a member called X0, this vector is used; otherwise the value of X0 maximizing the likelihood for the given model parameters is calculated by maximizing the quadratic polynomial 'X0 * L_root * X0 + m_root * X0 + r_root'.
A named list containing error information if a numerical or other
logical error occurred during likelihood calculation (this is a list returned by
PCMParseErrorMessage.
Allows to specify a different NA value such as -Inf or -1e20 which can be used in combination with log = TRUE when
using optim to maximize the log-likelihood;
Setting this option to FALSE will cause any
error to result in calling the stop R-base function. If not caught
in a tryCatch, this will cause the inference procedure to abort at the occurence of a numerical error. By default, this option is set to TRUE, which
means that getOption("PCMBase.Value.NA", as.double(NA)) is returned with
an error attribute and a warning is issued.
For efficiency, the argument metaI
can be provided explicitly, because this is not supposed to change during a
model inference procedure such as likelihood maximization.
PCMInfo PCMAbCdEf PCMLmr PCMSim PCMCond PCMParseErrorMessage