Claddis (version 0.7.0)

reconstruct_ancestral_states: Determine maximum parsimony ancestral state reconstruction(s)

Description

Given a tree, or set of trees, and a cladistic matrix returns all most parsimonious reconstruction(s) for every character.

Usage

reconstruct_ancestral_states(
  trees,
  cladistic_matrix,
  estimate_all_nodes = FALSE,
  estimate_tip_values = FALSE,
  inapplicables_as_missing = FALSE,
  polymorphism_behaviour = "uncertainty",
  uncertainty_behaviour = "uncertainty",
  polymorphism_geometry,
  polymorphism_distance,
  state_ages,
  dollo_penalty
)

Value

A list with multiple components, including:

ITEM

ITEM EXPLANATION.

Arguments

trees

A tree (phylo object) or set of trees (multiPhylo object).

cladistic_matrix

A character-taxon matrix in the format imported by read_nexus_matrix. These should be discrete with labels matching the tip labels of tree.

estimate_all_nodes

Logical that allows the user to make estimates for all ancestral values. The default (FALSE) will only make estimates for nodes that link coded terminals (recommended).

estimate_tip_values

Logical that allows the user to make estimates for tip values. The default (FALSE) will only makes estimates for internal nodes (recommended).

inapplicables_as_missing

Argument passed to calculate_tree_length.

polymorphism_behaviour

Argument passed to calculate_tree_length.

uncertainty_behaviour

Argument passed to calculate_tree_length.

polymorphism_geometry

Argument passed to make_costmatrix.

polymorphism_distance

Argument passed to make_costmatrix.

state_ages

Argument passed to make_costmatrix.

dollo_penalty

Argument passed to make_costmatrix.

Author

Graeme T. Lloyd

Details

Although most phylogenetic inference considers character evolution on a tree, they rarely explicitly assign states to internal nodes in the process, and hence this is normally done a posteriori using some form of ancestral state estimation algorithm. This function uses the parsimony optimality criterion (i.e., maximum parsimony, or the process that involves the fewest possible transitions, or, more accurately, the lowest total transition cost).

Algorithm

Like calculate_tree_length, this function is built around the generalised Swofford and Maddison (1992) algorithm, but adds the second pass as this is the one that explicitly generates all most parsimonious reconstructions. As it is a generalised approach it can work with the broadest range of character types and (rooted) trees of any degree of resolution - treating polytomies as hard.

References

Lloyd, G. T., 2018. Journeys through discrete-character morphospace: synthesizing phylogeny, tempo, and disparity. Palaeontology, 61, 637-645.

Swofford, D. L. and Maddison, W. P., 1992. Parsimony, character-state reconstructions, and evolutionary inferences. In R. L. Mayden (ed.) Systematics, Historical Ecology, and North American Freshwater Fishes. Stanford University Press, Stanford, p187-223.

See Also

calculate_tree_length, estimate_ancestral_states

Examples

# Generate two trees:
trees <- ape::read.tree(text = c("(A,(B,(C,(D,E))));", "(A,((B,C),(D,E)));"))

# Build a simple 5-by-10 binary character matrix:
cladistic_matrix <- build_cladistic_matrix(
  character_taxon_matrix = matrix(
    data = sample(
      x = c("0", "1"), # ADD MISSING, POLYMORPHISM, INAPPLICABLE ETC. HERE LATER TO TEST
      size = 50,
      replace = TRUE
    ),
    nrow = 5,
    ncol = 10,
    dimnames = list(
      LETTERS[1:5],
      c()
    )
  )
)

# Reconstruct ancestral states (limiting output to all most parsimonious
# ancestral state reconstruction for every tree and character combination):
reconstruct_ancestral_states(
  trees = trees,
  cladistic_matrix = cladistic_matrix,
  estimate_all_nodes = FALSE,
  estimate_tip_values = FALSE,
  inapplicables_as_missing = FALSE,
  polymorphism_behaviour = "uncertainty",
  uncertainty_behaviour = "uncertainty",
  polymorphism_geometry = "simplex",
  polymorphism_distance = "euclidean",
  dollo_penalty = 999,
  state_ages = c(2, 1)
)$node_estimates