Skip to contents

Apply a reconciliation to produce an aligned data-tree pair

Source: R/reconcile_accessors.R
reconcile_apply.Rd

Turn a reconciliation object into an analysis-ready data frame and pruned phylogenetic tree whose species labels agree. This is the step that feeds directly into caper::pgls(), MCMCglmm::MCMCglmm(), phytools::fastAnc(), or any other PCM that expects matching names in data and tree.

Usage

reconcile_apply(
  reconciliation,
  data = NULL,
  tree = NULL,
  species_col = NULL,
  drop_unresolved = FALSE
)

Arguments

reconciliation

A reconciliation object returned by reconcile_tree(), reconcile_data(), or a related matcher.

data

A data frame to align. If NULL, only the tree is processed and the returned data slot is NULL.

tree

An ape::phylo object (or path to a Newick / Nexus file) to align. If NULL, only the data frame is processed and the returned tree slot is NULL. (Passing both data = NULL and tree = NULL is allowed but produces an empty result; the normal use is to pass at least one of them.)

species_col

A length-1 character vector. Column in data containing species names. Auto-detected from a small set of common heuristics (e.g. species, Species1, scientific_name) when NULL; the heuristics list is not exhaustive — pass the column name explicitly if your data uses a non-standard label.

drop_unresolved

Logical. Drops unmatched rows and tips when TRUE. Defaults to FALSE (keep everything and just warn). Set to TRUE when preparing data for an analysis that cannot tolerate mismatches.

Value

A list with two elements:

data

The aligned data frame (or NULL if data was not supplied).

tree

The aligned phylo object (or NULL if tree was not supplied).

Details

Rows in data whose species have no match in the tree (and tips in tree whose species have no match in the data) are handled according to drop_unresolved. Matched data rows are kept as-is. Matched tree tips are renamed to the source-x (data-side) name when the tree-side label differs, so downstream PCM software can look up tips by the species names in your data frame.

See also

reconcile_tree() to build the reconciliation; reconcile_merge() when you want a single merged data frame instead of aligned data + tree; reconcile_export() to write everything to disk.

Other reconciliation functions: reconcile_augment(), reconcile_crosswalk(), reconcile_data(), reconcile_diff(), reconcile_export(), reconcile_mapping(), reconcile_merge(), reconcile_multi(), reconcile_override(), reconcile_override_batch(), reconcile_plot(), reconcile_report(), reconcile_review(), reconcile_splits_lumps(), reconcile_suggest(), reconcile_summary(), reconcile_to_trees(), reconcile_tree(), reconcile_trees()

Examples

data(avonet_subset)
data(tree_jetz)
rec <- reconcile_tree(avonet_subset, tree_jetz,
                      x_species = "Species1", authority = NULL)
#> ℹ Reconciling 919 data names vs 657 tree tips
#> ℹ Matching 919 x 657 names through 2 stages...
#> ℹ Stage 1/2: Exact matching...
#> ℹ Stage 2/2: Normalised matching (0 matched so far)...
#> ✔ Matched 657/919 data names to tree tips

aligned <- reconcile_apply(rec,
                           data = avonet_subset,
                           tree = tree_jetz,
                           species_col = "Species1",
                           drop_unresolved = TRUE)
#> ! Dropped 262 rows with unresolved species from data
#> ℹ Tree has 657 tips after alignment
nrow(aligned$data)
#> [1] 657
ape::Ntip(aligned$tree)
#> [1] 657

# aligned$data and aligned$tree are ready for downstream PCM tools