ordinate_cladistic_matrix: Principal Coordinates on a Cladistic Matrix

Description

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

Usage

ordinate_cladistic_matrix(
  cladistic_matrix,
  distance_metric = "mord",
  ged_type = "wills",
  distance_transformation = "arcsine_sqrt",
  distance_polymorphism_behaviour = "min_difference",
  distance_uncertainty_behaviour = "min_difference",
  distance_inapplicable_behaviour = "missing",
  character_dependencies = NULL,
  alpha = 0.5,
  correction = "cailliez",
  time_tree = NULL,
  estimate_all_nodes = FALSE,
  estimate_tip_values = FALSE,
  inapplicables_as_missing = FALSE,
  ancestral_polymorphism_behaviour = "equalp",
  ancestral_uncertainty_behaviour = "equalp",
  threshold = 0.01,
  all_missing_allowed = FALSE
)

Value

time_tree: The tree (if supplied). Note this may be pruned from the input tree by trim_matrix.
distance_matrix: The distance matrix. Note this may be pruned by trim_matrix and thus not include all taxa.
removed_taxa: A vector of taxa and/or nodes removed by trim_matrix. Returns NULL if none were removed.
note: See pcoa.
values: See pcoa.
vectors: See pcoa. Note: this will be the same as vectors.cor from the pcoa output if a correction was applied.
trace: See pcoa. Note: this will be the same as trace.cor from the pcoa output if a correction was applied.

Arguments

cladistic_matrix: A character-taxon matrix in the format imported by read_nexus_matrix.
distance_metric: See calculate_morphological_distances.
ged_type: See calculate_morphological_distances.
distance_transformation: See calculate_morphological_distances.
distance_polymorphism_behaviour: See calculate_morphological_distances.
distance_uncertainty_behaviour: See calculate_morphological_distances.
distance_inapplicable_behaviour: See calculate_morphological_distances.
character_dependencies: See calculate_morphological_distances.
alpha: See calculate_morphological_distances.
correction: The negative eigenvalue correction to use (one of "lingoes", "none", or "cailliez" - the default). See pcoa for more details.
time_tree: If a phylmorphospace is desired then a tree with root age and branch-lengths must be included.
estimate_all_nodes: See estimate_ancestral_states.
estimate_tip_values: See estimate_ancestral_states.
inapplicables_as_missing: See estimate_ancestral_states.
ancestral_polymorphism_behaviour: See estimate_ancestral_states.
ancestral_uncertainty_behaviour: See estimate_ancestral_states.
threshold: See estimate_ancestral_states.
all_missing_allowed: See estimate_ancestral_states.

Author

Graeme T. Lloyd graemetlloyd@gmail.com

Details

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

This function is effectively a wrapper for the pipeline:

estimate_ancestral_states -> calculate_morphological_distances -> pcoa

With the first part being optional (if wanting a phylomorphospace) and the latter coming from the ape package (the user is referred there for some of the options, e.g., using the Caillez 1983 approach to avoiding negative eigenvalues). (See Lloyd 2016 for more on disparity pipelines.)

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 by the estimate_ancestral_states part.

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

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

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

Run this code


# Run on Michaux (1989) data set with default settings:
x <- ordinate_cladistic_matrix(cladistic_matrix = michaux_1989)

# Show entire output:
x

# Generate a (made up) tree:
time_tree <- ape::rtree(n = length(x = rownames(x = michaux_1989$matrix_1$matrix)))

# Add taxon names to it:
time_tree$tip.label <- rownames(x = michaux_1989$matrix_1$matrix)

# Set root time by making youngest taxon extant:
time_tree$root.time <- max(diag(x = ape::vcv(phy = time_tree)))

# Run with tree:
y <- ordinate_cladistic_matrix(cladistic_matrix = michaux_1989, time_tree = time_tree)

# Show new output:
y

Run the code above in your browser using DataLab