ordinate_cladistic_matrix: Principal Coordinates on a Cladistic Matrix

In graemetlloyd/Claddis: Measuring Morphological Diversity and Evolutionary Tempo

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
)

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.

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).

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.

Author(s)

Graeme T. Lloyd [e-mail]

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.

See Also

assign_taxa_to_bins, plot_chronophylomorphospace, plot_morphospace_stack, plot_morphospace, plot_multi_morphospace

Examples

# 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

graemetlloyd/Claddis documentation built on Sept. 8, 2024, 12:51 p.m.