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%"
)
```
# ETERnity

<!-- badges: start -->
<!-- badges: end -->

The goal of ete is to provide an interface to the Evolution of Terrestrial Ecosystems (ETE) Program database.

## Installation

You can install the released version of ete from GitHub with:

``` r
devtools::install_github("smithsonian/ETERnity")
```

## Examples

### Loading ETE Data

The first step to using ETERnity is to load the library, and then use
the `load_ete_data` function to download the latest verion of ETE data
from Figshare, and load it into 6 tables.

```{r example}
library(ETERnity)

data_tables <- load_ete_data(download_if_missing = TRUE)
#> Downloading version 1 of the data...
#> trying URL 'https://ndownloader.figshare.com/articles/[...]'
#> Content type 'application/zip' length 53537971 bytes (51.1 MB)
#> ==================================================
#> downloaded 51.1 MB
#> Unzipping file to /Users/[username]/.ete...

names(data_tables)

```

### User Functions

We have created a suite of user functions that allow you to pull data out of the ETE tables by provider. You can pull out yours or anyone else's.

**geteteoccur(provider)**: Get your occurrence table in long format.
```{r geteteoccur}
amatangelo_occur <- geteteoccur(data_tables, 'Amatangelo')
head(amatangelo_occur)
```

**geteteoccurDataset(dataset)**: Get your occurrence table in long format for one timebin
```{r geteteoccurDataset}
amatan_wi_occur <- geteteoccurDataset(data_tables, 'Amatan_WI_Pla_Hist')
head(amatan_wi_occur)
```

**unmelt2specXsite(table)**: Put your occurrence table in P/A matrix format
```{r unmelt2specXsite}
PAtable <- unmelt2specXsite(amatan_wi_occur)
PAtable[1:5,1:5]
```

**getlatlon(provider)**: Get a list of your sites and their coordinates
```{r getlatlon}
wing_sites <- getlatlon(data_tables, 'Wing')
head(wing_sites)
```

**getages(provider)**: Get a list of your sites and their ages
```{r getages}
ages <- getages(data_tables, "Behrensmeyer1")
head(ages)
```

**getsitetraits(provider)**: Get your site traits matrix
```{r getsitetraits}
sitetraits <- getsitetraits(data_tables, "Blois")
head(sitetraits)
```

**getspptraits(provider)**: Get your species trait matrix
```{r getspptraits}
spptraits <- getspptraits(data_tables,"Lyons")
head(spptraits)
```

## Citation

If you use the ETERnity package, please cite accordingly:

## Attribution

The dataset download and load functions all borrowed heavily from [portalr](https://github.com/weecology/portalr/blob/master/R/download_data.R).

  - [JOSS publication](https://doi.org/10.21105/joss.01098):
    
    Erica M. Christensen, Glenda M. Yenni, Hao Ye, Juniper L. Simonis,
    Ellen K. Bledsoe, Renata M. Diaz, Shawn D. Taylor, Ethan P. White,
    and S. K. Morgan Ernest. (2019). portalr: an R package for
    summarizing and using the Portal Project Data. Journal of Open
    Source Software, 4(33), 1098, <https://doi.org/10.21105/joss.01098>