README.Rmd

---
output: github_document
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)
```

# phylobase

<!-- badges: start -->
[![R-CMD-check](https://github.com/fmichonneau/phylobase/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/fmichonneau/phylobase/actions/workflows/R-CMD-check.yaml)
[![codecov.io][(https://app.codecov.io/github/fmichonneau/phylobase?branch=master)](https://app.codecov.io/github/fmichonneau/phylobase?branch=master)
![](https://cranlogs.r-pkg.org/badges/phylobase)
[![CRAN version](https://www.r-pkg.org/badges/version/phylobase)](https://cran.r-project.org/package=phylobase)
<!-- badges: end -->

## About this package

`phylobase` provides classes and methods to easily associate, manipulate,
explore, and plot phylogenetic trees and data about the species they
include. The goal of this package is to provide a base set of tools likely to be
shared by all packages designed for phylogenetic analysis. This standardization
will benefit both *end-users* by allowing them to move results across packages
and keep data associated with the phylogenetic trees; and *developers* by
focusing on method development instead of having to rewrite the base functions.

- Authors: R Hackathon et al. (alphabetically: Ben Bolker, Marguerite Butler,
  Peter Cowan, Damien de Vienne, Dirk Eddelbuettel, Mark Holder, Thibaut
  Jombart, Steve Kembel, Francois Michonneau, David Orme, Brian O'Meara,
  Emmanuel Paradis, Jim Regetz, Derrick Zwickl)
- Maintainer: Francois Michonneau
- Licence: GPL (>= 2)
- Issues, bug reports, feature requests, discussion:
  https://github.com/fmichonneau/phylobase/issues

## Installation

### Stable version

The stable version (the minor and patch version numbers are even, e.g., 0.6.8)
can be downloaded from CRAN.

```{r, eval=FALSE}
install.packages("phylobase")
```

### Development version

The development version (the patch version number is odd, e.g., 0.6.9) is
available on GitHub (https://github.com/fmichonneau/phylobase), and can be
installed using the [`devtools`](https://cran.r-project.org/package=devtools)
package.

```{r, eval=FALSE}
pak::install_github("fmichonneau/phylobase")
library(phylobase)
```

### Getting started

```{r, echo=FALSE}
library(phylobase)
```

`phylobase` comes with example data sets `geospiza` and `geospiza_raw`.

- `geospiza` is a `phylo4d` object (the `phylobase` class that holds together a
  phylogenetic tree and associated data, the `phylo4` class is for phylogenetic
  trees only).
- `geospiza_raw` is a list that contains the tree `geospiza_raw$tree` (as an
  `ape::phylo` object) and the data `geospiza_raw$data` (as a `data.frame`) that
  were used to build the `geospiza` object.

Now we'll take the \emph{Geospiza} data from \verb+geospiza_raw$data+ and merge
it with the tree. However, since \emph{G. olivacea} is included in the tree but
not in the data set, we will initially run into some trouble:

```{r, error=TRUE}
data(geospiza_raw)
g1 <- as(geospiza_raw$tree, "phylo4")
geodata <- geospiza_raw$data
g2 <- phylo4d(g1, geodata)
```

To deal with _G. olivacea_ missing from the data, we have a few choices. The
easiest is to use `missing.data="warn"` to allow `R` to create the new object
with a warning (you can also use `missing.data="OK"` to proceed without
warnings):

```{r, warn=TRUE}
g2 <- phylo4d(g1, geodata, missing.data="warn")
head(g2)
```

### Importing data

#### From NEXUS files

`phylobase` has a robust parser for NEXUS files (it uses the NEXUS Class Library
from Paul Lewis and Mark Holder,
[NCL](https://sourceforge.net/projects/ncl/files/)). It can be used to import
simultaneously tree and species data.

```{r}
myrmeFile <- system.file("nexusfiles/treeWithDiscreteData.nex", package="phylobase")
myrme <- readNexus(file=myrmeFile)
head(myrme)
```

#### From NeXML

```{r}
library(RNeXML)
nxmlFile <- system.file("nexmlfiles/comp_analysis.xml", package="phylobase")
nxml <- nexml_read(nxmlFile)
nxmlEx <- phylo4(nxml)
```