README.Rmd

---
output: github_document
editor_options: 
  chunk_output_type: console
---
<!-- README.md is generated from README.Rmd. Please edit that file -->

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

# <img src="https://i.imgur.com/vTLlhbp.png" align="right" height=88 /> Analyze forest diversity and dynamics

<!-- badges: start -->
[![lifecycle](https://img.shields.io/badge/lifecycle-maturing-blue.svg)](https://www.tidyverse.org/lifecycle/#maturing)
[![Travis build status](https://travis-ci.org/forestgeo/fgeo.svg?branch=master)](https://travis-ci.org/forestgeo/fgeo)
[![Coverage status](https://codecov.io/gh/forestgeo/fgeo/branch/master/graph/badge.svg)](https://codecov.io/github/forestgeo/fgeo?branch=master)
[![CRAN status](https://www.r-pkg.org/badges/version/fgeo)](https://cran.r-project.org/package=fgeo)
<!-- badges: end -->

```{r, echo=FALSE}
# Creates a functional link when used with DT table.
fgeo_link <- function(package, topic = NULL) {
  end <- glue::glue(">{package}")
  if (!is.null(topic)) {end <- glue::glue("/reference/>{topic}")}
  glue::glue("<a href=https://forestgeo.github.io/{package}{end}</a>")
}

link_core <- function(pattern) {
  core <- fgeo_to_attach()()
  fgeo_link(core[grepl(pattern, core)])
}

analyze <- "analyze"
visualize <- "map"
manipulate <- "tool"
datasets <- "x"
```

__fgeo__ helps you to install, load, and access the documentation of multiple packages to analyze forest diversity and dynamics (`r purrr::map_chr(fgeo::fgeo_packages(include_self = FALSE), fgeo_link)`). This package-collection allows you to manipulate and plot [ForestGEO](http://www.forestgeo.si.edu/) data, and to do common analyses including abundance, demography, and species-habitats associations.

* [Search functions and datasets](https://forestgeo.github.io/fgeo/articles/siteonly/reference.html)
* [Ask questions, report bugs, or propose features](https://github.com/forestgeo/fgeo/issues/new)

## Installation

Make sure your R environment is as follows:

* R version is recent
* All packages are updated (run `update.packages()`; maybe use `ask = FALSE`)
* No other R session is running
* Current R session is clean (click _Session > Restart R_)

Install the latest stable version of __fgeo__ from [CRAN](https://cran.r-project.org/) with:

```R
install.packages("fgeo")
```

Or install the development version of __fgeo__ from [GitHub](https://github.com/) with:

```R
# install.packages("devtools")
devtools::install_github("forestgeo/fgeo.x")
```

* [How to setup .Rprofile for easiest installation of __fgeo__?](https://forestgeo.github.io/fgeo/articles/siteonly/questions-and-answers.html#how-to-setup--rprofile-for-easiest-installation-of-fgeo)
* [How to update __fgeo__?](https://forestgeo.github.io/fgeo/articles/siteonly/questions-and-answers.html#how-to-update-fgeo)
* [How to remove __fgeo__?](https://forestgeo.github.io/fgeo/articles/siteonly/questions-and-answers.html#how-to-remove-fgeo)
* [How to avoid or fix common installation problems?](https://forestgeo.github.io/fgeo/articles/siteonly/questions-and-answers.html#how-to-avoid-or-fix-common-installation-problems)

## Example

```{r example}
library(fgeo)
```

### Explore __fgeo__

On an interactive session, `fgeo_help()` and `fgeo_browse_reference()` help you to search documentation.

```
if (interactive()) {
  # To search on the viewer; accepts keywords
  fgeo_help()
  # To search on a web browser
  fgeo_browse_reference() 
}
```

### Access and manipulate data

`example_path()` allows you to access datasets stored in your R libraries.

```{r}
example_path()

(vft_file <- example_path("view/vft_4quad.csv"))
```

#### `read_<table>()`

`read_vft()` and `read_taxa()` import a ViewFullTable and ViewTaxonomy from .tsv or .csv files.

```{r}
read_vft(vft_file)
```

#### `pick_<what>()` and `drop_<what>()`

__fgeo__ is pipe-friendly. You may not use pipes but often they make code easier to read.

> Use %>% to emphasize a sequence of actions, rather than the object that the actions are being performed on.

-- <https://style.tidyverse.org/pipes.html>

`pick_dbh_under()`, `drop_status()` and friends pick and drop rows from a ForestGEO ViewFullTable or census table.

```{r}
(census <- fgeo.x::tree5)

census %>% 
  pick_dbh_under(100)
```

`pick_main_stem()` and `pick_main_stemid()` pick the main stem or main stemid(s) of each tree in each census.

```{r}
stem <- download_data("luquillo_stem6_random")

dim(stem)
dim(pick_main_stem(stem))
```

#### `add_<column(s)>()`

`add_status_tree()`adds the column `status_tree` based on the status of all stems of each tree.

```{r}
stem %>% 
  select(CensusID, treeID, stemID, status) %>% 
  add_status_tree()
```

`add_index()` and friends add columns to a ForestGEO-like dataframe.

```{r}
stem %>% 
  select(gx, gy) %>% 
  add_index()
```

### Plot data

For simplicity, we will focus on only a few species.

```{r}
stem_2sp <- stem %>% 
  filter(sp %in% c("PREMON", "CASARB"))
```

`autoplot()` and friends produce different output depending on the class of input. You can create different input classes, for example, with `sp()` and `sp_elev()`:

* Use `sp(census)` to plot the column `sp` of a `census` dataset -- i.e. to plot species distribution.

```{r autoplot-sp}
class(sp(stem_2sp))

autoplot(sp(stem_2sp))
```

* Use `sp_elev(census, elevation)` to plot the columns `sp` and `elev` of a `census` and `elevation` dataset, respectively -- i.e. to plot species distribution and topography.

```{r autoplot-sp-elev}
elevation <- fgeo.x::elevation
class(sp_elev(stem_2sp, elevation))

autoplot(sp_elev(stem_2sp, elevation))
```

### Analyze

#### Abundance

`abundance()` and `basal_area()` calculate abundance and basal area, optionally by groups.

```{r}
abundance(
  pick_main_stem(census)
)

by_species <- group_by(census, sp)

basal_area(by_species)
```

#### Demography

`recruitment_ctfs()`, `mortality_ctfs()`, and `growth_ctfs()` calculate recruitment, mortality, and growth. They all output a list. `as_tibble()` converts the output from a list to a more convenient dataframe.

```{r}
tree5 <- fgeo.x::tree5

as_tibble(
  mortality_ctfs(tree5, tree6)
)
```

#### Species-habitats association

`tt_test()` runs a torus translation test to determine habitat associations of tree species. `as_tibble()` converts the output from a list to a more convenient dataframe. `summary()` helps you to interpret the result.

```{r}
# This analysis makes sense only for tree tables
tree <- download_data("luquillo_tree5_random")

habitat <- fgeo.x::habitat
result <- tt_test(tree, habitat)

as_tibble(result)

summary(result)
```

## Downloads of fgeo packages

```{r fgeo-downloads, echo=FALSE, message=FALSE, warning=FALSE}
library(ggplot2)

fgeo::fgeo_packages() %>% 
  cranlogs::cran_downloads(from = "2019-05-09", to = lubridate::today()) %>% 
  ggplot(aes(date, count)) +
    geom_col() +
    labs(caption = "Data from <https://github.com/r-hub/cranlogs>")
```

## Related projects

Additional packages maintained by ForestGEO but not included in __fgeo__:

* [__fgeo.data__](https://forestgeo.github.io/fgeo.data/): Open datasets of ForestGEO.
* [__fgeo.krig__](https://forestgeo.github.io/fgeo.krig/): Analyze soils.

Other packages not maintained by ForestGEO:

* [CTFS-R Package](http://ctfs.si.edu/Public/CTFSRPackage/): The original package of CTFS functions. No longer supported by ForestGEO.
* [__BIOMASS__](https://CRAN.R-project.org/package=BIOMASS): An R package to estimate above-ground biomass in tropical forests.

## R code from recent publications by ForestGEO partners

Data have been made available as required by the journal to enable reproduction of the results presented in the paper. Please do not share these data without permission of the ForestGEO plot Principal Investigators (PIs). If you wish to publish papers based on these data, you are also required to get permission from the PIs of the corresponding ForestGEO plots.

* [Disentangling fire intensity and species' susceptibility to fire in a species-rich seasonal tropical forest (Trouve et al., 2019).](https://github.com/forestgeo/Trouve_et_al_2019)

* [Soil drivers of local-scale tree growth in a lowland tropical forest (Zemunik et al., 2018).](https://github.com/SoilLabAtSTRI/Soil-drivers-of-tree-growth)

* [Plant diversity increases with the strength of negative density dependence at the global scale (LaManna et al., 2018)](https://github.com/forestgeo/LaManna_et_al_Science)
    * Response #1: LaManna et al. 2018. Response to Comment on "Plant diversity increases with the strength of negative density dependence at the global scale" Science Vol. 360, Issue 6391, eaar3824. DOI: 10.1126/science.aar3824
    * Response #2: LaManna et al. 2018. Response to Comment on "Plant diversity increases with the strength of negative density dependence at the global scale". Science Vol. 360, Issue 6391, eaar5245. DOI: 10.1126/science.aar5245

## Information

* [Getting help](https://forestgeo.github.io/fgeo/SUPPORT.html).
* [Contributing](https://forestgeo.github.io/fgeo/CONTRIBUTING.html).
* [Contributor Code of Conduct](https://forestgeo.github.io/fgeo/CODE_OF_CONDUCT.html).

## Acknowledgments

Thanks to all partners of ForestGEO for sharing their ideas and code. For feedback on __fgeo__, special thanks to Gabriel Arellano, Stuart Davies, Lauren Krizel, Sean McMahon, and Haley Overstreet. For all other help, I thank contributors in the documentation of the features they helped with.