Phylogenies with Annotations

Description

phylotate provides functions that allow you to read and write NEXUS and Newick trees containing annotations, including those produced by MrBayes.

It does this by extending ape's phylo object type with extra data members containing per-node annotation information. This information is stored in such a way that it can be manipulated easily and will survive most manipulations using standard ape functions (e.g. reorder, chronopl).

See the documentation for the parse_annotated function for more information on how annotations are stored internally.

The functions you probably want to use for most things are read_annotated and write_annotated.

Author(s)

Daniel Beer dlbeer@gmail.com, Anusha Beer anbeer29@gmail.com

NEXUS data example

Description

A simple tree generated by MrBayes using the sequences for Darwin's finches from the example distributed with BEAST.

Usage

data(finches)

Parse MrBayes-supplied attributes from a NEXUS file

Description

This function takes a tree object and produces a dataframe containing attributes attached to each node by MrBayes.

Usage

mb_attrs(tree)

Arguments

Details

The returned dataframe contains one row per node, and one column per attribute. The attributes parsed are prob, prob_stddev, length_mean, length_median, length_95_HPD_low, and length_95_HPD_high.

Attributes which are derivable from the others are not parsed (for example, the prob_percent attribute is not parsed, since it's prob times 100.

Value

A dataframe of attributes.

Author(s)

Anusha Beer anbeer29@gmail.com

See Also

parse_annotated, read_annotated

Examples

  # Parse the example data included with this package
  data(finches)
  t <- parse_annotated(finches, format="nexus")

  # Obtain a table of MrBayes attributes for each node
  attrs <- mb_attrs(t)

Parse an annotated phylogenetic tree

Description

This function takes the given text string, containing data in either NEXUS or Newick format, and returns annotated phylogenetic trees.

Usage

parse_annotated(str, format="nexus")

Arguments

Details

The given file text is parsed and a tree object is constructed which can be used with the functions in the ape package. Annotations of the kind produced by, for example, MrBayes, are parsed and preserved in the returned object.

In addition to edge, edge.length and tip.label, two additional vectors are added. These are node.comment and node.distance.comment. These contain annotations associated with nodes and their distance values. These arrays are indexed by node number, not by edge. The reason for this is that this ensures that the object will remain in a valid state after a call to reorder which might change the ordering of the edge arrays without being aware of annotations. If you need to obtain annotations in edge-order, subset by the second column of the edge array.

Value

an object of type "phylo" or "multiPhylo", augmented with node annotations.

Author(s)

Daniel Beer dlbeer@gmail.com

References

Paradis, E. Definition of Formats for Coding Phylogenetic Trees in R. http://ape-package.ird.fr/misc/FormatTreeR_24Oct2012.pdf

See Also

print_annotated, read_annotated, write_annotated, finches

Examples

  # Parse the example data included with this package
  data(finches)
  t <- parse_annotated(finches, format="nexus")

  # Obtain annotations in edge-order, rather than node-order
  edge.comment <- t$node.comment[t$edge[,2]]

Serialize an annotated phylogenetic tree

Description

This function takes the given tree object and returns a string representing the tree in the requested format. The difference between the "newick" and "newick.named" formats is that the former uses only node numbers in its output, whereas the latter uses the tip labels (sanitized and deduplicated if necessary).

Usage

print_annotated(tree, format="nexus")

Arguments

Details

The tree object should be either a "phylo" or "multiPhylo" object. It may optionally be augmented with annotations, as described in the documentation for the parse_annotated function.

The output is a string suitable for writing to a file.

Value

a string containing a serialized tree.

Author(s)

Daniel Beer dlbeer@gmail.com

See Also

parse_annotated, read_annotated, write_annotated

Read an annotated phylogenetic tree

Description

This function takes the given file, containing data in either NEXUS or Newick format, and returns annotated phylogenetic trees.

Usage

read_annotated(filename, format="nexus")

Arguments

Details

The given file text is parsed and a tree object is constructed which can be used with the functions in the ape package. Annotations of the kind produced by, for example, MrBayes, are parsed and preserved in the returned object.

See parse_annotated for more information about the structure of the returned value.

Value

an object of type "phylo" or "multiPhylo", augmented with node annotations.

Author(s)

Daniel Beer dlbeer@gmail.com

See Also

print_annotated, parse_annotated, write_annotated

Write an annotated phylogenetic tree to a file

Description

This function takes the given tree object and returns a string representing the tree in the requested format. The difference between the "newick" and "newick.named" formats is that the former uses only node numbers in its output, whereas the latter uses the tip labels (sanitized and deduplicated if necessary).

Usage

write_annotated(tree, filename, format="nexus")

Arguments

Details

The tree object should be either a "phylo" or "multiPhylo" object. It may optionally be augmented with annotations, as described in the documentation for the parse_annotated function.

Author(s)

Daniel Beer dlbeer@gmail.com

See Also

parse_annotated, print_annotated, read_annotated