phylobase: readNexus – R documentation

Pricing

Become an expert in R — Interactive courses, Cheat Sheets, certificates and more!

Get Started for Free

Documentation

phylobase

readNexus

Create a phylo4, phylo4d or data.frame object from a NEXUS or a Newick file

Description

readNexus reads a NEXUS file and outputs a phylo4, phylo4d or data.frame object.

Usage

readNCL(
  file,
  simplify = FALSE,
  type = c("all", "tree", "data"),
  spacesAsUnderscores = TRUE,
  char.all = FALSE,
  polymorphic.convert = TRUE,
  levels.uniform = FALSE,
  quiet = TRUE,
  check.node.labels = c("keep", "drop", "asdata"),
  return.labels = TRUE,
  file.format = c("nexus", "newick"),
  check.names = TRUE,
  convert.edge.length = FALSE,
  ...
)

readNexus(
  file,
  simplify = FALSE,
  type = c("all", "tree", "data"),
  char.all = FALSE,
  polymorphic.convert = TRUE,
  levels.uniform = FALSE,
  quiet = TRUE,
  check.node.labels = c("keep", "drop", "asdata"),
  return.labels = TRUE,
  check.names = TRUE,
  convert.edge.length = FALSE,
  ...
)

readNewick(
  file,
  simplify = FALSE,
  quiet = TRUE,
  check.node.labels = c("keep", "drop", "asdata"),
  convert.edge.length = FALSE,
  ...
)

Arguments

`file`	a NEXUS file for `readNexus` or a file that contains Newick formatted trees for `readNewick`.
`simplify`	If TRUE, if there are multiple trees in the file, only the first one is returned; otherwise a list of `phylo4(d)` objects is returned if the file contains multiple trees.
`type`	Determines which type of objects to return, if present in the file (see Details).
`spacesAsUnderscores`	In the NEXUS file format white spaces are not allowed in taxa labels and are represented by underscores. Therefore, NCL converts underscores found in taxa labels in the NEXUS file into white spaces (e.g. `species_1` will become `"species 1"`. If you want to preserve the underscores, set as TRUE, the default).
`char.all`	If `TRUE`, returns all characters, even those excluded in the NEXUS file
`polymorphic.convert`	If `TRUE`, converts polymorphic characters to missing data
`levels.uniform`	If `TRUE`, uses the same levels for all characters
`quiet`	If `FALSE` the output of the NCL interface is printed. This is mainly for debugging purposes. This option can considerably slow down the process if the tree is big or there are many trees in the file.
`check.node.labels`	Determines how the node labels in the NEXUS or Newick files should be treated in the phylo4 object, see Details for more information.
`return.labels`	Determines whether state names (if `TRUE`) or state codes should be returned.
`file.format`	character indicating the format of the specified file (either “`newick`” or “`nexus`”). It's more convenient to just use `readNexus` or `readNewick`.
`check.names`	logical. If ‘TRUE’ then the names of the characters from the NEXUS file are checked to ensure that they are syntactically valid variable names and are not duplicated. If necessary they are adjusted using ‘make.names’.
`convert.edge.length`	logical. If `TRUE` negative edge lengths are replaced with 0. At this time `phylobase` does not accept objects with negative branch lengths, this workaround allows to import trees with negative branch lengths.
`...`	Additional arguments to be passed to phylo4 or phylo4d constructor (see Details)

Details

readNewick reads a Newick file and outputs a phylo4 or phylo4d object.

readNexus is used internally by both readNexus and readNewick to extract data held in a tree files, specifically in NEXUS files from DATA, CHARACTER or TREES blocks.

The type argument specifies which of these is returned:

data: will only return a data.frame of the contents of all DATA and CHARACTER blocks.
tree: will only return a phylo4 object of the contents of the TREES block.
all: if only data or a tree are present in the file, this option will act as the options above, returning either a data.frame or a phylo4 object respectively. If both are present then a phylo4d object is returned containing both.

The function returns NULL if the type of data requested is not present in the file, or if neither data nor tree blocks are present.

Depending on the context readNexus will call either the phylo4 or phylo4d constructor. The phylo4d constructor will be used with type="all", or if the option check.node.labels="asdata" is invoked.

readNewick imports Newick formatted tree files and will return a phylo4 or a phylo4d object if the option check.node.labels="asdata" is invoked.

For both readNexus and readNewick, the options for check.node.labels can take the values:

keep: the node labels of the trees will be passed as node labels in the phylo4 object
drop: the node labels of the trees will be ignored in the phylo4 object
asdata: the node labels will be passed as data and a phylo4d object will be returned.

If you use the option asdata on a file with no node labels, a warning message is issued, and is thus equivalent to the value drop.

For both readNexus and readNewick, additional arguments can be passed to the constructors such as annote, missing.data or extra.data. See the ‘Details’ section of phylo4d-methods for the complete list of options.

Value

Depending on the value of type and the contents of the file, one of: a data.frame, a phylo4 object, a phylo4d object or NULL. If several trees are included in the NEXUS file and the option simplify=FALSE a list of phylo4 or phylo4d objects is returned.

Note

Underscores in state labels (i.e. trait or taxon names) will be translated to spaces. Unless check.names=FALSE, trait names will be converted to valid R names (see make.names) on input to R, so spaces will be translated to periods.

Author(s)

Brian O'Meara, Francois Michonneau, Derrick Zwickl