Claddis (version 0.3.4)

MorphMatrix2PCoA: Principal Coordinates on a Cladistic Matrix

Description

Performs Principal Coordinates Analysis (PCoA) on a cladistic matrix.

Usage

MorphMatrix2PCoA(CladisticMatrix, Distance = "MORD", GEDType = "Wills",
  TransformDistances = "arcsine_sqrt",
  DistPolymorphismBehaviour = "min.difference",
  DistUncertaintyBehaviour = "min.difference",
  DistInapplicableBehaviour = "missing", CharacterDependencies = NULL,
  Alpha = 0.5, correction = "cailliez", Tree = NULL,
  EstimateAllNodes = FALSE, EstimateTipValues = FALSE,
  InapplicablesAsMissing = FALSE,
  AncestralPolymorphismBehaviour = "equalp",
  AncestralUncertaintyBehaviour = "equalp", Threshold = 0.01)

Arguments

CladisticMatrix

A vector of mode character representing the tip names for which an ancestor is sought.

Distance

The distance method to use (one of "RED", "GED", "GC", or "MORD" - the default). See MorphDistMatrix for more details.

GEDType

The type of GED use. Must be one of "Legacy", "Hybrid", or "Wills" (the default). See details for an explanation.

TransformDistances

The transformation to apply to distances. See MorphDistMatrix for details.

DistPolymorphismBehaviour

The distance behaviour for dealing with polymorphisms. Must be one of "mean.difference", "min.difference" (the default), or "random". See MorphDistMatrix for details.

DistUncertaintyBehaviour

The distance behaviour for dealing with uncertainties. Must be one of "mean.difference", "min.difference" (the default), or "random". See MorphDistMatrix for details.

DistInapplicableBehaviour

The behaviour for dealing with inapplicables. Must be one of "missing" (default), or "HSJ". See MorphDistMatrix for details.

CharacterDependencies

Only relevant if using InapplicableBehaviour = "HSJ". Must be a two-column matrix with colnames "DependentCharacter" and "IndependentCharacter" that specifies character hierarchies. See MorphDistMatrix for details.

Alpha

The alpha value (sensu Hopkins and St John 2018). Only relevant if using InapplicableBehaviour = "HSJ". See MorphDistMatrix for details.

correction

The negative eigenvalue correction to use (one of "lingoes", "none", or "cailliez" - the default). See pcoa for more details.

Tree

If a phylmorphospace is desired then a tree with root age and branch-lengths must be included.

EstimateAllNodes

If including a tree whether you want to estinate ancestral states for all characters (default is FALSE). See AncStateEstMatrix for more details.

EstimateTipValues

If including a tree whether you want to estinate missing or polymorphic tip states (default is FALSE). See AncStateEstMatrix for more details.

InapplicablesAsMissing

See AncStateEstMatrix.

AncestralPolymorphismBehaviour

Behaviour for dealing with polymorphisms when producing ancestral state estimates - see AncStateEstMatrix.

AncestralUncertaintyBehaviour

Behaviour for dealing with uncertainties when producing ancestral state estimates - see AncStateEstMatrix.

Threshold

Threshold for ancestral state estimation of discrete characters - see AncStateEstMatrix for details.

Value

Tree

The tree (if supplied). Note this may be pruned from the input tree by TrimMorphDistMatrix.

DistMatrix

The distance matrix. Note this may be pruned by TrimMorphDistMatrix and thus not include all taxa.

RemovedTaxa

A vector of taxa (or nodes) removed by TrimMorphDistMatrix. Returns NULL if none are removed.

note

See pcoa.

values

See pcoa.

vectors

See pcoa.

trace

See pcoa.

vectors.cor

See pcoa.

trace.cor

See pcoa.

Details

Takes a cladistic matrix in the format imported by ReadMorphNexus and performs Principal Coordinates (Gower 1966) analysis on it.

This function is effectively a wrapper for pcoa from the ape package and the user is referred there for some of the options (e.g., using the Caillez 1983 approach to avoiding negative eigenvalues).

If providing a tree and inferring ancestral states then options to also infer missing or uncertain tips and whether to infer values for all characters at all internal nodes are provided (via AncStateEstMatrix).

Other options within the function concern the distance metric to use and the transformation to be used if selecting a propotional distance (see MorphDistMatrix).

IMPORTANT: The function can remove taxa (or if including a tree, nodes as well) if they lead to an incomplete distance matrix (see TrimMorphDistMatrix).

References

Cailliez, F., 1983. The analytical solution of the additive constant problem. Psychometrika, 48, 305-308.

Gower, J. C., 1966. Some distance properties of latent root and vector methods used in multivariate analysis. Biometrika, 53, 325-338.

Examples

# NOT RUN {
# Run on Michaux (189) data set with defaults:
x <- MorphMatrix2PCoA(Michaux1989)

# Show output:
x

# Generate a (made up) tree:
Tree <- rtree(length(rownames(Michaux1989$Matrix_1$Matrix)))

# Add taxon names to it:
Tree$tip.label <- rownames(Michaux1989$Matrix_1$Matrix)

# Set root time by making youngest taxon extant:
Tree$root.time <- max(diag(vcv(Tree)))

# Run with tree:
y <- MorphMatrix2PCoA(Michaux1989, Tree = Tree)

# Show new output:
y

# }