ordinate_cladistic_matrix {Claddis}

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