Check typos and fill documentation

DESCRIPTION

@@ -53,6 +53,6 @@ Suggests:
     vdiffr,
     withr
 Roxygen: list(markdown = TRUE)
-RoxygenNote: 7.3.3
 VignetteBuilder: knitr
 Config/testthat/edition: 3
+Config/roxygen2/version: 8.0.0

R/datasets.R

@@ -3,9 +3,9 @@
 #' @description
 #' This dataset is derived from the WOODIV database (available at:
 #' \url{https://www.nature.com/articles/s41597-021-00873-3}). It contains the 
-#' grid cells of sites (10 km x 10 km  horizontal 
+#' grid cells of sites (10 km x 10 km horizontal 
 #' resolution) sampled in Portugal, Spain, France, and Italy (Mediterranean 
-#' part) for which at least one of the 24 Conifer tree species occurs.
+#' part) for which at least one of the 24 conifer tree species occurs.
 #' 
 #' This dataset exemplifies the argument `site_locations` used in 
 #' several functions of `funbiogeo`. The variable `site` corresponds to the 

R/fb_aggregate_site_data.R

@@ -8,24 +8,24 @@
 #' 
 #' @inheritParams fb_get_environment
 
-#' @param site_data a `matrix` or `data.frame` containing values per sites to 
-#'   aggregate along the provided grid. Can have one or several columns
-#'   (variables to aggregate). The first column must contain sites names as
+#' @param site_data a `matrix` or `data.frame` containing values per site to 
+#'   aggregate along the provided grid. It can contain one or several columns
+#'   (variables to aggregate). The first column must contain site names as
 #'   provided in the first argument `site_locations`.
 #'
 #' @param agg_geom a `terra::SpatRaster` or an `sf` object. This defines the
 #'   geometry along which to aggregate the initial data. See more in the Details
 #'   section.
 #'   
-#' @param fun the function used to aggregate points values when there are 
+#' @param fun the function used to aggregate point values when there are 
 #'   multiple points in one cell. Default is `mean`.
 #'   
 #' @param ... additional argument(s) passed to the provided function `fun`
 #'   
 #' @details
-#' The `agg_geom` object will condition the type of object ouput by the
-#' function. It can be of any sort as an `SpatRaster` or `sf` object. Depending
-#' on the need, it could be a regular square grid or hexagonal grid, it could
+#' The `agg_geom` object will condition the type of object output by the
+#' function. It can be of any sort of a `SpatRaster` or a `sf` object. Depending
+#' on the need, it could be a regular square grid or hexagonal grid; it could
 #' also be irregular polygons like biomes or ecoregions, or points, and even
 #' lines (such as when aggregating across transects or trajectories).
 #' 

R/fb_count_sites_by_species.R

@@ -1,8 +1,8 @@
 #' Count Number of Sites Occupied by Species
 #' 
 #' @description
-#' For each species computes the percentage of sites where the species is 
-#' present (distribution value higher than 0 and non-NA).
+#' This function computes the number and proportion of sites occupied by each
+#' species (distribution value higher than 0 and non-NA).
 #' 
 #' @inheritParams fb_get_trait_coverage_by_site
 #'

R/fb_count_species_by_site.R

@@ -1,9 +1,9 @@
 #' Count Number of Species per Site
 #' 
 #' @description
-#' For each site computes the proportion of species present (distribution value
-#' higher than 0 and non-NA) compared to all species provided.
-#' For example, a site could contain only 20% of all species provided.
+#' This function computes for each site the number and proportion of species
+#' present (distribution value higher than 0 and non-NA) compared to all species
+#' provided. For example, a site could contain only 20% of all species provided.
 #' 
 #' @inheritParams fb_get_trait_coverage_by_site
 #'

R/fb_count_species_by_trait.R

@@ -1,8 +1,8 @@
 #' Count Number of Species for Each Trait
 #' 
 #' @description
-#' For each trait computes the percentage of species without `NA` (missing 
-#' trait values).
+#' This function computes, for each trait, the number and proportion of species
+#' without missing trait value (`NA`).
 #' 
 #' @inheritParams fb_get_trait_coverage_by_site
 #'

R/fb_count_traits_by_species.R

@@ -1,8 +1,8 @@
 #' Compute Number of Known Trait(s) per Species
 #' 
 #' @description
-#' For each species computes the percentage of traits without `NA` (missing 
-#' trait values).
+#' For each species, this function computes the number and proportion of traits
+#' without `NA` (missing trait values).
 #' 
 #' @inheritParams fb_get_trait_coverage_by_site
 #'

R/fb_cwm.R

@@ -3,7 +3,18 @@
 #' This function returns the community-weighted mean of provided trait values.
 #' It only works with quantitative traits and will warn you otherwise.
 #' It will remove species that either have `NA` values in the `site_species`
-#' input or `NA` values as their trait.
+#' input or `NA` values as their trait in the provided trait object.
+#' 
+#' The community-weighted mean is a site-based trait mean weighted by the
+#' abundance of the species. It can be written with the following equation:
+#' 
+#' \deqn{
+#'   \text{CWM}_k = \sum_{i = 1}^S p_{ik} \times t_{ik}
+#' }
+#' 
+#' with \eqn{\text{CWM}_k} the CWM of site k, \eqn{p_{ik}} the relative
+#' abundance of species \eqn{i} in site \eqn{k}, and \eqn{t_{ik}} the trait of
+#' species \eqn{i} in site \eqn{k}.
 #' 
 #' @inheritParams fb_get_trait_coverage_by_site
 #'

R/fb_filter_sites_by_species_coverage.R

@@ -1,15 +1,17 @@
 #' Filter sites with a given species coverage threshold
 #' 
 #' @description
-#' Selects sites (rows) for which the percentage of present species 
-#' (distribution value higher than 0 and non-NA) is higher than a threshold.
+#' Selects sites (rows) for which the proportion of species present
+#' (distribution value higher than 0 and non-NA) is higher than the user-defined 
+#' threshold.
 #' 
 #' @param threshold_species_proportion a numeric of length 1 between 0 and 1.
-#'   The percentage of species coverage threshold.
+#'   The threshold of species coverage under which to exclude the sites.
 #' 
 #' @inheritParams fb_get_trait_coverage_by_site
 #'
-#' @return A subset of `site_species` with sites covered by X% of species.
+#' @return A subset of `site_species` with sites with at least
+#'   `threshold_species_proportion`% species present.
 #' 
 #' @export
 #'

R/fb_filter_sites_by_trait_coverage.R

@@ -1,7 +1,11 @@
 #' Filter sites with a given trait coverage threshold
 #' 
 #' @description
-#' ...
+#' Select sites (rows of the `site_species` object) with all given traits
+#' available for at least the user-defined proportion of species
+#' `threshold_traits_proportion`. If a single trait is given, then the threshold
+#' applies to a single trait, if more than one trait is provided, then the
+#' function considers a threshold across all traits taken together.
 #' 
 #' @param threshold_traits_proportion a numeric of length 1 between 0 and 1.
 #'   The percentage trait coverage threshold

R/fb_filter_species_by_site_coverage.R

@@ -3,7 +3,7 @@
 #' @description
 #' Selects species (columns) for which the percentage of sites where the 
 #' species is present (distribution value higher than 0 and non-NA) is higher 
-#' than a threshold.
+#' than a user-defined threshold.
 #' 
 #' @param threshold_sites_proportion a numeric of length 1 between 0 and 1.
 #'   The percentage of sites coverage threshold.

R/fb_filter_species_by_trait_coverage.R

@@ -1,8 +1,10 @@
 #' Filter species with a given traits coverage threshold
 #' 
 #' @description
-#' Selects species (rows) for which the percentage of traits without 
-#' `NA` (missing trait values) is higher than a threshold.
+#' Selects species (rows) for which the proportion of traits without 
+#' `NA` (missing trait values) is higher than the user-defined threshold.
+#' It considers as many traits as the ones provided to filter given
+#' the threshold.
 #' 
 #' @param threshold_traits_proportion a numeric of length 1 between 0 and 1.
 #'   The percentage of traits coverage threshold.

R/fb_filter_traits_by_species_coverage.R

@@ -2,7 +2,7 @@
 #' 
 #' @description
 #' Selects traits (columns) for which the percentage of species without 
-#' `NA` (missing trait values) is higher than a threshold.
+#' `NA` (missing trait values) is higher than a user-defined threshold.
 #' 
 #' @param threshold_species_proportion `numeric(1)` \[default = `NULL`\]\cr{}
 #'   between 0 and 1. The percentage of species coverage threshold.

R/fb_format_site_locations.R

@@ -1,9 +1,10 @@
 #' Extract site x locations information from long format data
 #' 
 #' Convert a flat `data.frame` with site coordinates into a proper `sf` object
-#' that can then be used by other functions. This function assumes that
-#' the coordinates are given in WGS84 (longitude vs. latitude). The function
-#' automatically removes repeated coordinates from the input dataset.
+#' that can then be used by other functions. This function assumes by default 
+#' that the coordinates are given in WGS84 (longitude vs. latitude), but this
+#' can be changed through the `crs` argument. The function automatically removes
+#' repeated coordinates from the input dataset.
 #'
 #' @param data a `data.frame` in a long format (see example).
 #' 

R/fb_format_species_categories.R

@@ -1,8 +1,8 @@
 #' Extract species x categories information from long format data
 #' 
 #' Convert a flat `data.frame` with species names and species (supra-)category
-#' (e.g. family, order, endemism status, etc.) into a proper `data.frame` object
-#' that can then be used by other functions.
+#' (e.g. family, order, endemism status, etc.) into a proper
+#' `species_categories` object that can then be used by other functions.
 #' The final output contains species in rows and two columns (species name and
 #' species category).
 #'

R/fb_format_species_traits.R

@@ -1,8 +1,8 @@
 #' Extract species x traits information from long format data
 #' 
 #' Convert a flat `data.frame` with traits values for different species
-#' into a proper `data.frame` object that can then be used by other functions.
-#' The final output contains species in rows and traits in columns.
+#' into a proper `species_traits` object that can then be used by other
+#' functions. The final output contains species in rows and traits in columns.
 #'
 #' @param data a `data.frame` in a long format (see example).
 #' 

R/fb_get_all_trait_coverages_by_site.R

@@ -1,6 +1,6 @@
 #' Compute Trait Coverage per Site for Each Trait
 #' 
-#' Compute trait coverage for all sites, i.e., the percentage of total 
+#' Compute trait coverage for all sites, i.e., the proportion of total 
 #' abundance/presence of species that have traits data compared to total
 #' species. This function assumes that all species provided in the traits
 #' dataset have all their traits specified (meaning that all species have either

R/fb_get_environment.R

@@ -1,14 +1,17 @@
 #' Extract Raster Values at Location of Sites
+#' 
+#' This function uses a `site_locations` object and a given `SpatRaster`.
+#' It extracts the mean value of the provided raster for each site.
 #'
-#' @param site_locations an `sf` object with the spatial geometries of sites.
+#' @param site_locations a `sf` object with the spatial geometries of sites.
 #'                       **NOTE**: the first column should be named **`"site"`**
 #'                       and indicate site names.
 #' 
 #' @param environment_raster a `SpatRaster` object (package `terra`).
 #'   A single or multi-layers environmental raster.
 #'
 #' @return A `data.frame` with average environmental values (columns) per site
-#' (rows), with the first column being `"site"` indicating site names.
+#' (rows), with the first column being `"site"`, indicating site names.
 #' 
 #' @export
 #' 

R/fb_get_trait_combination_coverage.R

@@ -1,13 +1,12 @@
 #' Compute site trait coverage for each trait combination
 #' 
 #' This function computes trait coverage for each site for different trait
-#' combinations. If not provided, consider all possible trait combinations.
 #' The function will not run if the total number of combinations given is over
 #' 10,000.
 #'
 #' @inheritParams fb_get_trait_coverage_by_site
 #' @param comb_size an integer vector defining one or more sizes of combinations
-#'   (default: `NULL`)
+#'   over which to compute trait coverage. (default: `NULL`)
 #'
 #' @return
 #'   a data.frame with the following columns:

R/fb_get_trait_coverage_by_site.R

@@ -1,9 +1,8 @@
 #' Compute Trait Coverage For Each Site Weighted by Abundance
 #' 
-#' Compute trait coverage for all sites, i.e., the percentage of total 
-#' abundance/presence of species that have traits data compared to total
-#' species.
-#' This function assumes that all species provided in the traits dataset have
+#' Compute trait coverage for all sites, i.e., the proportion of total 
+#' abundance/presence of species that have traits data compared to all species.
+#' This function assumes that all species provided in the trait dataset have
 #' all their traits specified (meaning that all species have either known or
 #' `NA` values reported as their traits).
 #'  **NB**: this function returns trait coverage using all traits

R/fb_make_report.R

@@ -1,8 +1,10 @@
 #' Create an Rmarkdown Report to Explore User Data
 #'
 #' Creates an R Markdown (`.Rmd`) report from a template to explore and 
-#' summarize user data. User can modify this report and use the function
-#' [rmarkdown::render()] (or click the _Render_ of the RStudio IDE) to convert 
+#' summarize user data in (functional) biogeography through the use of the
+#' site-species, the species-traits, and the site-locations objects. Users can
+#' modify this report and use the function [rmarkdown::render()]
+#' (or click the _Render_ of the RStudio IDE) to convert 
 #' this `.Rmd` in different formats:
 #'   - HTML document (`output_format = "bookdown::html_document2"`);
 #'   - PDF document (`output_format = "bookdown::pdf_document2"`);

R/fb_map_raster.R

@@ -1,4 +1,9 @@
 #' Map a Single Raster Layer
+#' 
+#' This is a helper function to plot a map of an environmental raster.
+#' The raster is plotted as is, with its given coordinate reference system.
+#' The function can provide a background map if the `background` argument is
+#' toggled.
 #'
 #' @param x a `SpatRaster` object (package `terra`). A raster of one single
 #' layer

R/fb_map_site_data.R

@@ -1,9 +1,9 @@
 #' Map Arbitrary Site Data
 #'
-#' From the site-locations data and a dataset organized by site, plot a map of
-#' this information.
-#' The returned plot is as little customized as possible to let the user do
-#' the customization.
+#' This function helps to map arbitrary site data using the site-locations
+#' object and a dataset organized by site. The returned plot is as little 
+#' customized as possible to let the user choose. The function can provide a
+#' basic background map if the `background` argument is toggled.
 #'
 #' @param site_data `data.frame()` of additional site information containing
 #'   the column `"site"` to merge with the `site_locations` argument

R/fb_map_site_traits_completeness.R

@@ -3,7 +3,7 @@
 #' Returns a `ggplot2` map of sites colored by trait coverage (proportion
 #' of species having a known trait value). By default shows one plot for each
 #' trait and add an additional facet named `"all_traits"` considering the
-#' trait coverage with all traits taken together.
+#' trait coverage with all provided traits taken together.
 #'
 #' @inheritParams fb_get_environment
 #' @inheritParams fb_get_all_trait_coverages_by_site