funbiogeo

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

# funbiogeo <a href="https://frbcesab.github.io/funbiogeo/"><img src="man/figures/logo.png" align="right" height="139" alt="funbiogeo website" /></a>

<!-- badges: start -->

[![R CMD
check](https://github.com/FRBCesab/funbiogeo/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/FRBCesab/funbiogeo/actions/workflows/R-CMD-check.yaml)
[![Website
deployment](https://github.com/FRBCesab/funbiogeo/actions/workflows/pkgdown.yaml/badge.svg)](https://github.com/FRBCesab/funbiogeo/actions/workflows/pkgdown.yaml)
[![Codecov test
coverage](https://codecov.io/gh/FRBCesab/funbiogeo/graph/badge.svg?token=JPXXVNMAJ0)](https://app.codecov.io/gh/FRBCesab/funbiogeo)
[![License: GPL
v2](https://img.shields.io/badge/License-GPL%20v2-blue.svg)](https://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html)
<!-- badges: end -->

- [Overview](#overview)
- [Features](#features)
- [Installation](#installation)
- [First steps](#first-steps)
- [Long-form documentation (=vignettes)](#long-form-documentation)
- [Citation](#citation)
- [Contributing](#contributing)
- [Acknowledgments](#acknowledgments)
- [References](#references)

## Overview

The package `funbiogeo` aims to help users with analyses in functional
biogeography ([Violle *et al.* 2014](#references)), the biogeography of
species’ traits, by loading and combining data, exploring the
relationships between traits and their availability trait coverage,
providing many diagnostic plots to understand how to filter them,
producing maps, correlating them with the environment, and helping to
aggregate data at different scales. It is aimed at first-timers of
functional biogeography as well as more experienced users who want to
obtain quick and easy exploratory plots.

Below is a quick introduction to the main features of `funbiogeo`. If
you want some more details about them, check [our
vignettes](#long-form-documentation).

## Features

`funbiogeo` offers:

- Standardized functions to filter and select your data for further
  analyses,
- Pleasing default diagnostic plots to visualize the structure of your
  data,
- Extensive documentation (multiple vignettes, well-documented
  functions, real-life example dataset) to guide you through functional
  biogeography analyses,
- Nice default plotting functions fully compatible with the outputs of
  functional diversity packages (`betapart`, `fundiversity`, `hillR`,
  `mFD`, etc.),
- A publication ready, automated, standardized report that provides
  analyses and plots of your data,
- Functions to easily “upscale” (=aggregate) your data to coarser
  spatial resolutions whatever the type of aggregation geometry you want
  (regular grids, irregular polygons, and rasters).

<div class="figure">

<img src="inst/misc/functions_scheme.drawio.png" alt="Naming scheme of available functions in funbiogeo" width="100%" />
<p class="caption">

Naming scheme of available functions in funbiogeo
</p>

</div>

## Installation

For the moment `funbiogeo` is not on CRAN but you can install the
development version from [R-universe](https://r-universe.dev) as
follows:

``` r
install.packages("funbiogeo", repos = c("https://frbcesab.r-universe.dev", "https://cloud.r-project.org"))
```

## First steps

This section will show you some useful functions from `funbiogeo`. For a
longer introduction, please refer to the [“Introduction”
vignette](https://frbcesab.github.io/funbiogeo/articles/introduction.html).

The package contains default example data named `woodiv_traits`,
`woodiv_site_species`, and `woodiv_locations` all from the WOODIV
database ([Monnet et al. 2021](#references)). You can, for example,
visualize the completeness of your trait dataset (which traits are known
for which proportion of species) using the
`fb_plot_species_traits_completeness()` function:

``` r
fb_plot_species_traits_completeness(woodiv_traits)
```

<img src="man/figures/README-plot-sp-tr-complete-1.png" alt="" width="100%" />

One other useful visualization is to see the trait coverage of each
trait across all sites, using the function
`fb_map_site_traits_completeness()`:

``` r
fb_map_site_traits_completeness(woodiv_locations, woodiv_site_species, woodiv_traits)
```

<img src="man/figures/README-plot-site-tr-complete-1.png" alt="" width="100%" />

All of the features of `funbiogeo` are presented through the [vignettes
of the package](https://frbcesab.github.io/funbiogeo/articles/).

## Long-form documentation

`funbiogeo` provides five vignettes to explain its functioning:

- An [introduction to
  `funbiogeo`](https://frbcesab.github.io/funbiogeo/articles/introduction.html)
  that describes its core features and guides you through a typical
  analysis.
- A vignette on [all diagnostic
  plots](https://frbcesab.github.io/funbiogeo/articles/diagnostic-plots.html)
  provided in the package, which details how to use each plotting
  function and how to interpret their output.
- A vignette on the [data
  format](https://frbcesab.github.io/funbiogeo/articles/long-format.html)
  that `funbiogeo` needs, which shows you the use of specific functions
  to format your data to work well within `funbiogeo`.
- A vignette on [data
  upscaling](https://frbcesab.github.io/funbiogeo/articles/upscaling.html)
  that illustrates how to leverage `funbiogeo` to automatically
  aggregate your data to a coarser resolution and use it in subsequent
  analyses.
- A vignette focusing on [special
  cases](https://frbcesab.github.io/funbiogeo/articles/special-cases.html),
  e.g., how to work with categorical traits, or how to consider
  intraspecific trait variations.

## Citation

At the moment, `funbiogeo` doesn’t offer a companion paper nor is it on
CRAN. But if you happen to use it in your paper, you can cite the
package through:

> Casajus N & Grenié M (2026) *funbiogeo: Streamlining Functional
> Biogeography Analyses*. R package version 0.0.1,
> <https://github.com/frbcesab/funbiogeo/>.

You can also run:

``` r
citation("funbiogeo")
```

## Contributing

All types of contributions are encouraged and valued. For more
information, check out our [Contributor
Guidelines](https://github.com/FRBCesab/funbiogeo/blob/main/CONTRIBUTING.md).

Please note that the `funbiogeo` project is released with a [Contributor
Code of
Conduct](https://contributor-covenant.org/version/2/1/CODE_OF_CONDUCT.html).
By contributing to this project, you agree to abide by its terms.

## Acknowledgments

This package has been developed for the
[FRB-CESAB](https://www.fondationbiodiversite.fr/en/about-the-foundation/le-cesab/)
working group
[FREE](https://www.fondationbiodiversite.fr/en/the-frb-in-action/programs-and-projects/le-cesab/free/)
and its followup [FREE
2](https://www.fondationbiodiversite.fr/en/the-frb-in-action/programs-and-projects/le-cesab/free-2/)
which aims to advance the concept of functional rarity and examine the
causes and consequences of functional rarity from local to global
scales.

## References

Monnet, AC., Cilleros, K., Médail, F. et al. WOODIV, a database of
occurrences, functional traits, and phylogenetic data for all
Euro-Mediterranean trees. Sci Data 8, 89 (2021). DOI:
[10.1038/s41597-021-00873-3](https://doi.org/10.1038/s41597-021-00873-3)

Violle C, Reich, PB Pacala SW, *et al.* (2014) The emergence and promise
of functional biogeography. *Proceedings of the National Academy of
Sciences*, **111**, 13690-13696. DOI:
[10.1073/pnas.1415442111](https://www.pnas.org/doi/full/10.1073/pnas.1415442111)