summarize_datelife_result {datelife}

Summarize a datelifeResult object.

Description

Get different types of summaries from a datelifeResult object, an output from get_datelife_result(). This allows rapid processing of data. If you need a list of chronograms from your datelifeResult object, this is the function you are looking for.

Usage

summarize_datelife_result(
  datelife_result = NULL,
  datelife_query = NULL,
  summary_format = "phylo_all",
  na_rm = TRUE,
  summary_print = c("citations", "taxa"),
  taxon_summary = c("none", "summary", "matrix"),
  criterion = "taxa"
)

Arguments

datelife_result

A datelifeResult object, usually an output of get_datelife_result().

datelife_query

A datelifeQuery object, usually an output of make_datelife_query().

summary_format

A character vector of length one, indicating the output format for results of the DateLife search. Available output formats are:

"citations"

A character vector of references where chronograms with some or all of the target taxa are published (source chronograms).

"mrca"

A named numeric vector of most recent common ancestor (mrca) ages of target taxa defined in input, obtained from the source chronograms. Names of mrca vector are equal to citations.

"newick_all"

A named character vector of newick strings corresponding to target chronograms derived from source chronograms. Names of newick_all vector are equal to citations.

"newick_sdm"

Only if multiple source chronograms are available. A character vector with a single newick string corresponding to a target chronogram obtained with SDM supertree method (Criscuolo et al. 2006).

"newick_median"

Only if multiple source chronograms are available. A character vector with a single newick string corresponding to a target chronogram from the median of all source chronograms.

"phylo_sdm"

Only if multiple source chronograms are available. A phylo object with a single target chronogram obtained with SDM supertree method (Criscuolo et al. 2006).

"phylo_median"

Only if multiple source chronograms are available. A phylo object with a single target chronogram obtained from source chronograms with median method.

"phylo_all"

A named list of phylo objects corresponding to each target chronogram obtained from available source chronograms. Names of phylo_all list correspond to citations.

"phylo_biggest"

The chronogram with the most taxa. In the case of a tie, the chronogram with clade age closest to the median age of the equally large trees is returned.

"html"

A character vector with an html string that can be saved and then opened in any web browser. It contains a 4 column table with data on target taxa: mrca, number of taxa, citations of source chronogram and newick target chronogram.

"data_frame"

A 4 column data.frame with data on target taxa: mrca, number of taxa, citations of source chronograms and newick string.

na_rm

If TRUE, it drops rows containing NAs from the datelifeResult patristic matrix; if FALSE, it returns NA where there are missing entries.

summary_print

A character vector specifying the type of summary information to be printed to screen. Options are:

"citations"

Prints references of chronograms where target taxa are found.

"taxa"

Prints a summary of the number of chronograms where each target taxon is found.

"none"

Nothing is printed to screen.

Defaults to c("citations", "taxa"), which displays both.

taxon_summary

A character vector specifying if data on target taxa missing in source chronograms should be added to the output as a "summary" or as a presence/absence "matrix". Default to "none", no information on taxon_summary added to the output.

criterion

Defaults to criterion = "taxa". Used for chronogram summarizing, i.e., obtaining a single summary chronogram from a group of input chronograms. For summarizing approaches that return a single summary tree from a group of phylogenetic trees, it is necessary that the latter form a grove, roughly, a sufficiently overlapping set of taxa between trees, see Ané et al. (2009) doi:10.1007/s00026-009-0017-x. In rare cases, a group of trees can have multiple groves. This argument indicates whether to get the grove with the most trees (criterion = "trees") or the most taxa (criterion = "taxa").

Value

The output is determined by the argument summary_format:

If summary_format = "citations"

The function returns a character vector of references.

If summary_format = "mrca"

The function returns a named numeric vector of most recent common ancestor (mrca) ages.

If summary_format = "newick_[all, sdm, or median]"

The function returns output chronograms as newick strings.

If summary_format = "phylo_[all, sdm, median, or biggest]"

The function returns output chronograms as phylo or multiPhylo objects.

If ⁠summary_format = "html" or "data_frame"⁠

The function returns a 4 column table with data on mrca ages, number of taxa, references, and output chronograms as newick strings.

References

Ané, C., Eulenstein, O., Piaggio-Talice, R., & Sanderson, M. J. (2009). "Groves of phylogenetic trees". Annals of Combinatorics, 13(2), 139-167, doi:10.1007/s00026-009-0017-x.