fgeo helps you to install, load, and access the documentation of multiple packages to analyze forest diversity and dynamics. It allows you to manipulate and plot ForestGEO data, and to do common analyses including abundance, demography, and species-habitats associations.

Installation

Expected R environment

  • R version is recent
  • All packages are updated (run update.packages())
  • No other R session is running
  • Current R session is clean (click Session > Restart R)

Install the latest stable version of fgeo with:

install.packages("devtools")
devtools::install_github("forestgeo/fgeo@*release")

Or install the development version of fgeo with:

install.packages("devtools")
devtools::install_github("forestgeo/fgeo", upgrade = "never")

  • To upgrade packages see ?devtools::update_packages()
  • To remove packages see ?remove.packages()

Tips to avoid or fix common installation problems

Alternative installation

If you failed to install fgeo try this instead:

If this still fails, follow the advice below and then try to install fgeo again.

Update R, RStudio, and R packages

Instruct RStudio not to preserve your workspace between sessions

In RStudio go to Tools > Global Options…

Use RStudio projects (or the here package)

Restart R many times each day

Press Cmd/Ctrl + Shift + F10 to restart RStudio or go to Session > Restart R.

Increase the rate limit to install from GitHub

If you reach GitHub’s rate limit see usethis::browse_github_pat().

If that was unclear continue reading. This describes the same process but in more detail.

  • Make sure your token description says exactly GITHUB_PAT and click Generate token

  • Store your new token in the environmental variable GITHUB_PAT by running usethis::edit_r_environ() in R.
  • A file called .Renviron will open. Type the name and value of your GitHub token. Ensure to end this file with a new empty line. Your .Renviron file should now look like this:

  • Save and close .Renviron.

Install package development utilities

Sometimes you may want to install the source version of an R package from CRAN or GitHub. If that package contains a src/ folder you will need to install package development utilities.

Troubleshoot: error: X11 library is missing: install XQuartz …

If you are a mac user, fgeo may fail to install with the error below. Install XQuartz from https://www.xquartz.org/ and try to install fgeo again.

Example

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.

Importing multiple censuses from a directory into a list

(This and the following section don’t use fgeo because other packages already do this well.)

Combine fs::dir_ls() with purrr::map() to import multiple censuses from a directory into a list:

  • Use fs::dir_ls() to create the paths to the files you want to import.
  • Use purrr::map() to iterate over each path and apply a custom function to import them.
library(purrr)
#> 
#> Attaching package: 'purrr'
#> The following object is masked from 'package:fgeo.tool':
#> 
#>     %||%
library(fs)

(rdata_files <- example_path("rdata"))
#> [1] "C:/Users/LeporeM/Documents/R/R-3.5.2/library/fgeo.x/extdata/rdata"
(paths <- fs::dir_ls(rdata_files))
#> C:/Users/LeporeM/Documents/R/R-3.5.2/library/fgeo.x/extdata/rdata/tree5.RData
#> C:/Users/LeporeM/Documents/R/R-3.5.2/library/fgeo.x/extdata/rdata/tree6.RData

# The formula syntax `~ fun(.x)` is a shortcut for `function(.x) fun(.x)`
censuses <- map(paths, ~ get(load(.x)))
censuses
#> $`C:/Users/LeporeM/Documents/R/R-3.5.2/library/fgeo.x/extdata/rdata/tree5.RData`
#> # A tibble: 3 x 19
#>   treeID stemID tag   StemTag sp    quadrat    gx    gy MeasureID CensusID
#>    <int>  <int> <chr> <chr>   <chr> <chr>   <dbl> <dbl>     <int>    <int>
#> 1    104    143 10009 10009   DACE~ 113      10.3  245.    439947        5
#> 2    119    158 1001~ 100104  MYRS~ 1021    183.   410.    466597        5
#> 3    180    225 1001~ 100174  CASA~ 921     165.   410.    466623        5
#> # ... with 9 more variables: dbh <dbl>, pom <chr>, hom <dbl>,
#> #   ExactDate <date>, DFstatus <chr>, codes <chr>, nostems <dbl>,
#> #   status <chr>, date <dbl>
#> 
#> $`C:/Users/LeporeM/Documents/R/R-3.5.2/library/fgeo.x/extdata/rdata/tree6.RData`
#> # A tibble: 3 x 19
#>   treeID stemID tag   StemTag sp    quadrat    gx    gy MeasureID CensusID
#>    <int>  <int> <chr> <chr>   <chr> <chr>   <dbl> <dbl>     <int>    <int>
#> 1    104    143 10009 10009   DACE~ 113      10.3  245.    582850        6
#> 2    119    158 1001~ 100104  MYRS~ 1021    183.   410.    578696        6
#> 3    180    225 1001~ 100174  CASA~ 921     165.   410.    617049        6
#> # ... with 9 more variables: dbh <dbl>, pom <chr>, hom <dbl>,
#> #   ExactDate <date>, DFstatus <chr>, codes <chr>, nostems <dbl>,
#> #   status <chr>, date <dbl>

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

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

Use %>% to emphasise 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.

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

Plot data

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

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.

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

Analyze

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

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. There are many other people that deserve special acknowledgment; I thank them in the documentation and home page of each individual package that make up the fgeo development.