Type: Package
Title: Dendrograms for Evolutionary Analysis
Version: 2.1.0
Maintainer: Shaun Wilkinson <shaunpwilkinson@gmail.com>
Description: Contains functions for developing phylogenetic trees as deeply-nested lists ("dendrogram" objects). Enables bi-directional conversion between dendrogram and "phylo" objects (see Paradis et al (2004) <doi:10.1093/bioinformatics/btg412>), and features several tools for command-line tree manipulation and import/export via Newick parenthetic text.
License: GPL-3
LazyData: TRUE
URL: http://github.com/ropensci/phylogram
BugReports: http://github.com/ropensci/phylogram/issues
Encoding: UTF-8
Imports: ape (≥ 4.0), methods, stats
Suggests: dendextend, knitr, rmarkdown, testthat
RoxygenNote: 6.0.1
VignetteBuilder: knitr
NeedsCompilation: no
Packaged: 2018-06-25 11:46:26 UTC; shaun
Author: Shaun Wilkinson ORCID iD [aut, cre], Simon Davy ORCID iD [aut]
Repository: CRAN
Date/Publication: 2018-06-25 15:24:56 UTC

Dendrograms for evolutionary analysis.

Description

The phylogram R package is a tool for for developing phylogenetic trees as deeply-nested lists known as "dendrogram" objects. It provides functions for conversion between "dendrogram" and "phylo" class objects, as well as several tools for command-line tree manipulation and import/export via Newick parenthetic text. This improves accessibility to the comprehensive range of object-specific analytical and tree-visualization functions found across a wide array of bioinformatic R packages.

Functions

A brief description of the primary phylogram functions are provided with links to their help pages below.

File import/export

Object conversion

Tree editing and manipulation

Apply unweighted branch lengths.

Description

This function sets the 'height' attributes of all leaf nodes to zero and progressively resets the heights of the inner nodes by single incremental units in a bottom-up fashion.

Usage

as.cladogram(x)

Arguments

x

an object of class "dendrogram".

Value

an object of class "dendrogram".

Author(s)

Shaun Wilkinson

Examples

  x <- read.dendrogram(text = "(A:0.1,B:0.2,(C:0.3,D:0.4):0.5);")
  plot(x, horiz = TRUE)
  x <- as.cladogram(x)
  plot(x, horiz = TRUE)

Convert a "phylo" object to a dendrogram.

Description

This function converts a "phylo" object (Paradis et al 2004) to a dendrogram.

Usage

## S3 method for class 'phylo'
as.dendrogram(object, ...)

Arguments

object

an object of class "phylo".

...

further arguments to be passed between methods.

Value

an object of class "dendrogram".

Author(s)

Shaun Wilkinson

References

Paradis E, Claude J, Strimmer K, (2004) APE: analyses of phylogenetics and evolution in R language. Bioinformatics 20, 289-290.

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

Paradis E (2012) Analysis of Phylogenetics and Evolution with R (Second Edition). Springer, New York.

Examples

  newick <- "(A:0.1,B:0.2,(C:0.3,D:0.4):0.5);"
  x <- read.dendrogram(text = newick)
  y <- as.phylo(x)
  z <- as.dendrogram(y)
  identical(x, z)

Convert a dendrogram to a "phylo" object.

Description

This function converts a dendrogram into an object of class "phylo" (see Paradis et al 2004).

Usage

## S3 method for class 'dendrogram'
as.phylo(x, ...)

Arguments

x

a dendrogram.

...

further arguments to be passed between methods.

Value

an object of class "phylo".

Author(s)

Shaun Wilkinson

References

Paradis E, Claude J, Strimmer K, (2004) APE: analyses of phylogenetics and evolution in R language. Bioinformatics 20, 289-290.

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

Paradis E (2012) Analysis of Phylogenetics and Evolution with R (Second Edition). Springer, New York.

Examples

  newick <- "(A:0.1,B:0.2,(C:0.3,D:0.4):0.5);"
  x <- read.dendrogram(text = newick)
  y <- as.phylo(x)
  z <- as.dendrogram(y)

Reorder tree branches in ladderized pattern.

Description

This function ladderizes the branches of a dendrogram object to aid in visual interpretation.

Usage

ladder(x, decreasing = FALSE)

Arguments

x

an object of class "dendrogram".

decreasing

logical indicating whether the tree should be ladderized upwards or downwards. Defaults to FALSE (downwards).

Details

This function is the dendrogram analogue of the ladderize function in the ape package (Paradis et al 2004, 2012).

Value

Returns an object of class dendrogram.

Author(s)

Shaun Wilkinson

References

Paradis E, Claude J, Strimmer K, (2004) APE: analyses of phylogenetics and evolution in R language. Bioinformatics 20, 289-290.

Paradis E (2012) Analysis of Phylogenetics and Evolution with R (Second Edition). Springer, New York.

See Also

The ladderize function in the ape package performs a similar operation for objects of class "phylo".

Examples

  x <- read.dendrogram(text = "(A:0.1,B:0.2,(C:0.3,D:0.4):0.5);")
  plot(x, horiz = TRUE)
  x <- ladder(x, decreasing = TRUE)
  plot(x, horiz = TRUE)

Remove tree nodes by regular expression pattern matching.

Description

"prune" takes an object of class "dendrogram" and removes all branches whose branch labels match a given regular expression.

Usage

prune(tree, pattern, keep = FALSE, ...)

Arguments

tree

an object of class "dendrogram".

pattern

a regular expression.

keep

logical indicating whether the nodes whose labels match the regular expression provided in "pattern" should be kept and the remainder discarded. Defaults to FALSE. Note that nodes without "label" attributes are ignored.

...

further arguments to be passed to grepl and gsub.

Details

This function recursively tests the "label" attribute of each dendrogram node (including non-leaf inner nodes if applicable) for the specified pattern, removing those that register a positive hit. Note that positive matching inner nodes are removed along with all of their sub-nodes, regardless of whether the "label" attributes of the sub-nodes match the pattern.

Value

Returns an object of class "dendrogram".

Author(s)

Shaun Wilkinson

See Also

The drop.tip function in the ape package performs a similar operation for objects of class "phylo". See regex for help with compiling regular expressions.

Examples

  x <- read.dendrogram(text = "(A:0.1,B:0.2,(C:0.3,D:0.4):0.5);")
  plot(x, horiz = TRUE)
  x <- prune(x, pattern = "^A$")
  plot(x, horiz = TRUE)

Read a dendrogram from parenthetic text.

Description

This function wraps the read.tree parser from the ape package to read a phylogenetic tree from parenthetic text in the Newick/New Hampshire format, and converts it to object of class "dendrogram".

Usage

read.dendrogram(file = "", text = NULL, ...)

Arguments

file

character string giving a valid path to the file from which to read the data.

text

optional character string in lieu of a "file" argument. If a text argument is provided instead of a file path, the data are read via a text connection.

...

further arguments to be passed to read.tree (which may then be passed on to scan).

Value

an object of class "dendrogram".

Author(s)

Shaun Wilkinson

References

Felsenstein J (1986) The Newick tree format. http://evolution.genetics.washington.edu/phylip/newicktree.html

Olsen G (1990) Interpretation of the "Newick's 8:45" tree format standard. http://evolution.genetics.washington.edu/phylip/newick_doc.html

Paradis E, Claude J, Strimmer K, (2004) APE: analyses of phylogenetics and evolution in R language. Bioinformatics 20, 289-290.

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

Paradis E (2012) Analysis of Phylogenetics and Evolution with R (Second Edition). Springer, New York.

See Also

write.dendrogram writes an object of class "dendrogram" to a Newick text string. The read.tree function in the ape package parses objects of class "phylo" and "multiPhylo".

Examples

  x <- read.dendrogram(text = "(A:0.1,B:0.2,(C:0.3,D:0.4):0.5);")
  plot(x, horiz = TRUE)

Set dendrogram attributes for a nested list.

Description

remidpoint is a helper function used for manually creating "dendrogram" objects from nested lists. The function recursively assigns the necessary 'midpoint', 'members', and 'leaf' attributes at each node.

Usage

remidpoint(x)

Arguments

x

a nested list, possibly of class "dendrogram"

Value

returns a nested list, or an object of class "dendrogram" depending on the class of the input object.

Author(s)

Shaun Wilkinson

Examples

  ## manually create a small dendrogram with three members, A, B and C
  x <- list("A", list("B", "C"))
  attr(x[[1]], "leaf") <- TRUE
  attr(x[[2]][[1]], "leaf") <- TRUE
  attr(x[[2]][[2]], "leaf") <- TRUE
  attr(x[[1]], "label") <- "A"
  attr(x[[2]][[1]], "label") <- "B"
  attr(x[[2]][[2]], "label") <- "C"
  attr(x, "height") <- 1
  attr(x[[1]], "height") <- 0
  attr(x[[2]], "height") <- 0.5
  attr(x[[2]][[1]], "height") <- 0
  attr(x[[2]][[2]], "height") <- 0
  x <- remidpoint(x)
  class(x) <- "dendrogram"
  plot(x, horiz = TRUE)

Reset dendrogram height attributes.

Description

reposition is a helper function used for manually creating "dendrogram" objects from nested lists. The function recursively reassigns the 'height' attributes at each node by a given constant.

Usage

reposition(x, shift = "reset")

Arguments

x

an object of class "dendrogram".

shift

either the character string "reset" (shift the graph so that the height of the farthest leaf from the root is zero), or a numeric value giving the amount to shift the graph along the primary axis.

Value

Returns an object of class "dendrogram".

Author(s)

Shaun Wilkinson

Examples

  x <- read.dendrogram(text = "(A:0.1,B:0.2,(C:0.3,D:0.4):0.5);")
  plot(x, horiz = TRUE)
  x <- reposition(x)
  plot(x, horiz = TRUE)

Write a dendrogram object to parenthetic text.

Description

This function exports a dendrogram object as a Newick/New Hampshire text string.

Usage

write.dendrogram(x, file = "", append = FALSE, edges = TRUE, ...)

Arguments

x

an object of class "dendrogram".

file

a character string naming a file or connection to write the output to. If no file path is specified or file = "" the result is printed to the console.

append

logical indicating whether the output should be appended to the file. If append = FALSE the contents of the file will be overwritten (the default setting).

edges

logical indicating whether edge weights should be included in the output string.

...

further arguments to be passed to format. Used to specify the numbering style of the edge weights (if edges = TRUE).

References

Felsenstein J (1986) The Newick tree format. http://evolution.genetics.washington.edu/phylip/newicktree.html

Olsen G (1990) Interpretation of the "Newick's 8:45" tree format standard. http://evolution.genetics.washington.edu/phylip/newick_doc.html

See Also

read.dendrogram to parse a "dendrogram" object from a text file. The write.tree function in the ape package performs a similar operation for "phylo" and "multiPhylo" objects.

Examples

  newick <- "(A:0.1,B:0.2,(C:0.3,D:0.4):0.5);"
  x <- read.dendrogram(text = newick)
  write.dendrogram(x, edges = TRUE)