fgeo

[Meta R-package on CRAN] Analyse forest diversity and dynamics

https://github.com/forestgeo/fgeo

Keywords

Keywords from Contributors

Repository

[Meta R-package on CRAN] Analyse forest diversity and dynamics

README.Rmd

---
output: github_document
editor_options: 
  chunk_output_type: console
---


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

#  Analyze forest diversity and dynamics


[![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)


```{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("")
}

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_()`

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

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

#### `pick_()` and `drop_()`

__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.

-- 

`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_()`

`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 ")
```

## 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.


      
  
      

    

        Owner
    

    

      

        

          

            

                

                  Name: ForestGEO
                
                

                  Login: forestgeo
                
                

                  Kind: organization
                
                

                  Email: forestgeo@si.edu
                
                

                  Location: Smithsonian Tropical Research Institute
                
            
          

          

            

                

                  Website: http://www.forestgeo.si.edu/
                
                

                  Repositories: 7
                
                

                  Profile: https://github.com/forestgeo
                
            
          
        

          

            
Forest Global Earth Observatory, Smithsonian Institution
          
      
    
  

    
    
    
    
    
      

    
GitHub Events

    

      

        

          

            
Total
            

                

                  Watch event: 3
                
            
          

          

            
Last Year
            

                

                  Watch event: 3
                
            
          
        
      
    
  

      

    

      Committers
    

      

        Last synced: 6 months ago
      

      

        

          

            

              
All Time
              

                

                  Total Commits: 703
                
                

                  Total Committers: 20
                
                

                  Avg Commits per committer: 35.15
                
                

                  Development Distribution Score (DDS): 0.196
                
              
            

              

                
Past Year
                

                  

                    Commits: 0
                  
                  

                    Committers: 0
                  
                  

                    Avg Commits per committer: 0.0
                  
                  

                    Development Distribution Score (DDS): 0.0
                  
                
              
          
        
      

      

        

          
Top Committers
        
        

          

            

              

                
Name
                
Email
                
Commits
              
            
            

                

                  
maurolepore
                  
m****e@g****m
                  
565
                
                

                  
hadley
                  
h****m@g****m
                  
107
                
                

                  
Haley Overstreet
                  
4****h
                  
5
                
                

                  
Lepore
                  
L****M@S****U
                  
3
                
                

                  
Dirk Eddelbuettel
                  
e****d@d****g
                  
3
                
                

                  
Gábor Csárdi
                  
c****r@g****m
                  
3
                
                

                  
Derek Chiu
                  
d****u@b****a
                  
2
                
                

                  
ForestGEO
                  
f****o@s****u
                  
2
                
                

                  
Jennifer (Jenny) Bryan
                  
j****n@g****m
                  
2
                
                

                  
Ben Marwick
                  
b****k@h****m
                  
1
                
                

                  
Darío Hereñú
                  
m****a@g****m
                  
1
                
                

                  
Greg Macfarlane
                  
g****e@g****m
                  
1
                
                

                  
Jim Hester
                  
j****r@g****m
                  
1
                
                

                  
Matthew Lincoln
                  
m****n
                  
1
                
                

                  
Michael Toth
                  
m****h@g****m
                  
1
                
                

                  
Ri Ram
                  
e****4@g****m
                  
1
                
                

                  
Serhat Cevikel
                  
s****l@y****m
                  
1
                
                

                  
zhaoy
                  
z****y
                  
1
                
                

                  
Jennifer (Jenny) Bryan
                  
j****y@s****a
                  
1
                
                

                  
Rainer Stuetz
                  
r****z@a****t
                  
1