R: Read phylogenetic characters from file

ReadCharacters {TreeTools} | R Documentation

## Read phylogenetic characters from file

### Description

Parse a Nexus or TNT file, reading character states and names.

### Usage

    ReadCharacters(filepath, character_num = NULL, session = NULL)

    ReadTntCharacters(filepath, character_num = NULL, type = NULL, session = NULL)

    ReadAsPhyDat(filepath)

    ReadTntAsPhyDat(filepath)

    PhyDat(dataset)

### Arguments

`filepath` | character string specifying location of file
`character_num` | Index of character(s) to return. `NULL`, the default, returns all characters.
`session` | (Optional) A Shiny session with a `numericInput` named `character_num` whose maximum should be updated.
`type` | Character vector specifying categories of data to extract from file. Setting `type = c('num', 'dna')` will return only characters following a `&[num]` or `&[dna]` tag in a TNT input file. Leave as `NULL` (the default) to return all characters.
`dataset` | list of taxa and characters, in the format produced by read.nexus.data: a list of sequences each made of a single character vector, and named with the taxon name.

### Details

Tested with matrices downloaded from MorphoBank, but should also work more widely; please report incorrectly parsed files.

Matrices must contain only continuous or only discrete characters; maximum one matrix per file. Continuous characters will be read as strings (i.e. base type 'character').

### Value

`ReadCharacters()` and `ReadTNTCharacters()` return a matrix whose row names correspond to tip labels, and column names correspond to character labels, with the attribute `state.labels` listing the state labels for each character; or a list of length one containing a character string explaining why the function call was unsuccessful.

`ReadAsPhyDat()` and `ReadTntAsPhyDat()` return a `phyDat` object.

### Functions

- `PhyDat`: A convenient wrapper for phangorn's `phyDat()`, which converts a list of morphological characters into a `phyDat` object. If your morphological characters are in the form of a matrix, perhaps because they have been read using `read.table()`, try `MatrixToPhyDat()` instead.

### Author(s)

Martin R. Smith (martin.smith@durham.ac.uk)

### References

Maddison DR, Swofford DL, Maddison WP (1997). “Nexus: an extensible file format for systematic information.” Systematic Biology, 46, 590–621. doi: 10.1093/sysbio/46.4.590.

### See Also

- Convert between matrices and `phyDat` objects: `MatrixToPhyDat()`

- Write characters to TNT-format file: `WriteTntCharacters()`

### Examples

    fileName <- paste0(system.file(package='TreeTools'),
                       '/extdata/input/dataset.nex')
    ReadCharacters(fileName)

    fileName <- paste0(system.file(package='TreeTools'),
                       '/extdata/tests/continuous.nex')
    continuous <- ReadCharacters(fileName)

    # To convert from strings to numbers:
    at <- attributes(continuous)
    continuous <- suppressWarnings(as.numeric(continuous))
    attributes(continuous) <- at
    continuous

[Package TreeTools version 1.4.1 Index]