| Type: | Package |
| Title: | Handle the FORCIS Foraminifera Database |
| Version: | 1.0.1 |
| Description: | Provides an interface to the 'FORCIS' database (Chaabane et al. (2024) <doi:10.5281/zenodo.7390791>) on global foraminifera distribution. This package allows to download and to handle 'FORCIS' data. It is part of the FRB-CESAB working group FORCIS.https://www.fondationbiodiversite.fr/en/the-frb-in-action/programs-and-projects/le-cesab/forcis/. |
| URL: | https://docs.ropensci.org/forcis/,https://github.com/ropensci/forcis |
| BugReports: | https://github.com/ropensci/forcis/issues |
| License: | GPL-2 |GPL-3 [expanded from: GPL (≥ 2)] |
| Encoding: | UTF-8 |
| RoxygenNote: | 7.3.2 |
| VignetteBuilder: | knitr |
| Depends: | R (≥ 4.1.0) |
| Imports: | ggplot2, httr2, rlang, sf, tibble, tidyr, utils, vroom |
| Suggests: | fs, dplyr, httptest2, knitr, rmarkdown, testthat (≥ 3.0.0),vdiffr, withr |
| Config/testthat/edition: | 3 |
| NeedsCompilation: | no |
| Packaged: | 2025-05-20 09:26:48 UTC; nicolas |
| Author: | Nicolas Casajus [aut, cre, cph], Mattia Greco [aut], Sonia Chaabane [aut], Xavier Giraud [aut], Thibault de Garidel-Thoron [aut], Khalil Hammami [ctb], Air Forbes [rev], FRB-CESAB [fnd] |
| Maintainer: | Nicolas Casajus <nicolas.casajus@fondationbiodiversite.fr> |
| Repository: | CRAN |
| Date/Publication: | 2025-05-23 12:02:02 UTC |
forcis: Handle the FORCIS Foraminifera Database
Description
Provides an interface to the 'FORCIS' database (Chaabane et al. (2024)doi:10.5281/zenodo.7390791) on global foraminifera distribution. This package allows to download and to handle 'FORCIS' data. It is part of the FRB-CESAB working group FORCIS.https://www.fondationbiodiversite.fr/en/the-frb-in-action/programs-and-projects/le-cesab/forcis/.
Author(s)
Maintainer: Nicolas Casajusnicolas.casajus@fondationbiodiversite.fr (ORCID) [copyright holder]
Authors:
Mattia Grecomattia_greco@outlook.com (ORCID)
Sonia Chaabanesonia.chaabane@gmail.com (ORCID)
Xavier Giraudgiraud@cerege.fr (ORCID)
Thibault de Garidel-Thorongaridel@cerege.fr (ORCID)
Other contributors:
Khalil Hammamikhalil.hammami@enetcom.usf.tn [contributor]
Air Forbesamforbes@ualberta.ca (ORCID) [reviewer]
FRB-CESAB [funder]
See Also
Useful links:
Report bugs athttps://github.com/ropensci/forcis/issues
Compute count conversions
Description
Functions to convert species counts between different formats: raw abundance,relative abundance, and number concentration, using counts metadata.
Usage
compute_abundances(data, aggregate = TRUE)compute_concentrations(data, aggregate = TRUE)compute_frequencies(data, aggregate = TRUE)Arguments
data | a |
aggregate | a |
Details
compute_concentrations()converts all counts to number concentrations(n specimens/m³).compute_frequencies()converts all counts to relative abundances(% specimens per sampling unit).compute_abundances()converts all counts to raw abundances(n specimens/sampling unit).
Value
Atibble in long format with two additional columns:taxa,the taxon name andcounts_*, the number concentration (counts_n_conc) orthe relative abundance (counts_rel_ab) or the raw abundance(counts_raw_ab).
Examples
# Import example dataset ----file_name <- system.file(file.path("extdata", "FORCIS_net_sample.csv"), package = "forcis")net_data <- read.csv(file_name)# Select a taxonomy ----net_data <- select_taxonomy(net_data, taxonomy = "VT")# Dimensions of the data.frame ----dim(net_data)# Compute concentration ----net_data_conc <- compute_concentrations(net_data)# Dimensions of the data.frame ----dim(net_data_conc)Reshape and simplify FORCIS data
Description
Reshapes FORCIS data by pivoting species columns into two columns:taxa(taxon names) andcounts (taxon abundances). It converts widerdata.frameto a long format.
Usage
convert_to_long_format(data)Arguments
data | a |
Value
Atibble reshaped in a long format.
Examples
# Import example dataset ----file_name <- system.file(file.path("extdata", "FORCIS_net_sample.csv"), package = "forcis")net_data <- read.csv(file_name)# Dimensions of the data.frame ----dim(net_data)# Reshape data ----net_data <- convert_to_long_format(net_data)# Dimensions of the data.frame ----dim(net_data)# Column names ----colnames(net_data)Convert a data frame into an sf object
Description
This function can be used to convert adata.frame into ansf object.Note that coordinates (columnssite_lon_start_decimal andsite_lat_start_decimal) are projected in the Robinson coordinate system.
Usage
data_to_sf(data)Arguments
data | a |
Value
Ansf POINTS object.
Examples
# Attach package ----library("ggplot2")# Import example dataset ----file_name <- system.file(file.path("extdata", "FORCIS_net_sample.csv"), package = "forcis")net_data <- read.csv(file_name)# Dimensions of the data.frame ----dim(net_data)# Filter by years ----net_data_sub <- filter_by_year(net_data, years = 1992)# Convert to an sf object ----net_data_sub_sf <- data_to_sf(net_data_sub)# World basemap ----ggplot() + geom_basemap() + geom_sf(data = net_data_sub_sf)Download the FORCIS database
Description
Downloads the entire FORCIS database as a collection of fivecsv files fromZenodo (https://zenodo.org/doi/10.5281/zenodo.7390791). Additionalfiles will be also downloaded.
Usage
download_forcis_db( path, version = options()$forcis_version, check_for_update = options()$forcis_check_for_update, overwrite = FALSE, timeout = 60)Arguments
path | a |
version | a |
check_for_update | a |
overwrite | a |
timeout | an |
Details
The FORCIS database is regularly updated. The global structure of the tablesdoesn’t change between versions but some bugs can be fixed and new recordscan be added. This is why it is recommended to use the latest version of thedatabase. The package is designed to handle the versioning of the database onZenodo and will inform the user if a new version is available each timehe/she uses one of theread_*_data() functions.
For more information, please read the vignette available athttps://docs.ropensci.org/forcis/articles/database-versions.html.
Value
No return value. The FORCIS files will be saved in thepath folder.
References
Chaabane S, De Garidel-Thoron T, Giraud X,et al. (2023) The FORCISdatabase: A global census of planktonic Foraminifera from ocean waters.Scientific Data, 10, 354.DOI:doi:10.1038/s41597-023-02264-2.
See Also
read_plankton_nets_data() to import the FORCIS database.
Examples
# Folder in which the database will be saved ----# N.B. In this example we use a temporary folder but you should select an# existing folder (for instance "data/").path <- tempdir()# Download the database ----download_forcis_db(path, timeout = 300)# Check the content of the folder ----list.files(path, recursive = TRUE)Filter FORCIS data by a spatial bounding box
Description
Filters FORCIS data by a spatial bounding box.
Usage
filter_by_bbox(data, bbox)Arguments
data | a |
bbox | an object of class |
Value
Atibble containing a subset ofdata for the desired boundingbox.
Examples
# Import example dataset ----file_name <- system.file(file.path("extdata", "FORCIS_net_sample.csv"), package = "forcis")net_data <- read.csv(file_name)# Dimensions of the data.frame ----dim(net_data)# Filter by oceans ----net_data_sub <- filter_by_bbox(net_data, bbox = c(45, -61, 82, -24))# Dimensions of the data.frame ----dim(net_data_sub)Filter FORCIS data by month of sampling
Description
Filters FORCIS data by month of sampling.
Usage
filter_by_month(data, months)Arguments
data | a |
months | a |
Value
Atibble containing a subset ofdata for the desired months.
Examples
# Import example dataset ----file_name <- system.file(file.path("extdata", "FORCIS_net_sample.csv"), package = "forcis")net_data <- read.csv(file_name)# Dimensions of the data.frame ----dim(net_data)# Filter by months ----net_data_sub <- filter_by_month(net_data, months = 1:2)# Dimensions of the data.frame ----dim(net_data_sub)Filter FORCIS data by ocean
Description
Filters FORCIS data by one or several oceans.
Usage
filter_by_ocean(data, ocean)Arguments
data | a |
ocean | a |
Value
Atibble containing a subset ofdata for the desired oceans.
Examples
# Import example dataset ----file_name <- system.file(file.path("extdata", "FORCIS_net_sample.csv"), package = "forcis")net_data <- read.csv(file_name)# Dimensions of the data.frame ----dim(net_data)# Get ocean names ----get_ocean_names()# Filter by oceans ----net_data_sub <- filter_by_ocean(net_data, ocean = "Indian Ocean")# Dimensions of the data.frame ----dim(net_data_sub)Filter FORCIS data by a spatial polygon
Description
Filters FORCIS data by a spatial polygon.
Usage
filter_by_polygon(data, polygon)Arguments
data | a |
polygon | an |
Value
Atibble containing a subset ofdata for the desired spatialpolygon.
Examples
# Import example dataset ----file_name <- system.file(file.path("extdata", "FORCIS_net_sample.csv"), package = "forcis")net_data <- read.csv(file_name)# Dimensions of the data.frame ----dim(net_data)# Import Indian Ocean spatial polygons ----file_name <- system.file(file.path("extdata", "IHO_Indian_ocean_polygon.gpkg"), package = "forcis")indian_ocean <- sf::st_read(file_name)# Filter by polygon ----net_data_sub <- filter_by_polygon(net_data, polygon = indian_ocean)# Dimensions of the data.frame ----dim(net_data_sub)Filter FORCIS data by species
Description
Filters FORCIS data by a species list.
Usage
filter_by_species(data, species)Arguments
data | a |
species | a |
Value
Atibble containing a subset ofdata.
Examples
# Import example dataset ----file_name <- system.file(file.path("extdata", "FORCIS_net_sample.csv"), package = "forcis")net_data <- read.csv(file_name)# Select a taxonomy ----net_data <- select_taxonomy(net_data, taxonomy = "VT")# Select only required columns (and taxa) ----net_data <- select_forcis_columns(net_data)# Dimensions of the data.frame ----dim(net_data)# Get species names ----get_species_names(net_data)# Select records for three species ----net_data_sub <- filter_by_species(data = net_data, species = c("g_inflata_VT", "g_elongatus_VT", "g_glutinata_VT"))# Dimensions of the data.frame ----dim(net_data_sub)# Get species names ----get_species_names(net_data_sub)Filter FORCIS data by year of sampling
Description
Filters FORCIS data by year of sampling.
Usage
filter_by_year(data, years)Arguments
data | a |
years | a |
Value
Atibble containing a subset ofdata for the desired years.
Examples
# Import example dataset ----file_name <- system.file(file.path("extdata", "FORCIS_net_sample.csv"), package = "forcis")net_data <- read.csv(file_name)# Dimensions of the data.frame ----dim(net_data)# Filter by years ----net_data_sub <- filter_by_year(net_data, years = 1992)# Dimensions of the data.frame ----dim(net_data_sub)Add a World basemap to a ggplot object
Description
Creates a World base map that can be added to aggplot object.Spatial layers come from the Natural Earth project(https://www.naturalearthdata.com/) and are defined in the Robinsoncoordinate system.
Usage
geom_basemap()Value
Aggplot object.
Examples
# Attach package ----library("ggplot2")# World basemap ----ggplot() + geom_basemap()Get available versions of the FORCIS database
Description
Gets all available versions of the FORCIS database by querying the Zenodo API(https://developers.zenodo.org).
Usage
get_available_versions()Value
Atibble with three columns:
publication_date: the date of the release of the versionversion: the label of the versionaccess_right: is the version open or restricted?
Examples
# Versions of the FORCIS database ----get_available_versions()Get World ocean names
Description
This function returns the name of World oceans according to the IHO Sea Areasdataset version 3 (Flanders Marine Institute, 2018).
Usage
get_ocean_names()Value
Acharacter vector with World ocean names.
References
Flanders Marine Institute (2018). IHO Sea Areas, version 3.Available online at:https://www.marineregions.org/.DOI:doi:10.14284/323.
Examples
# Print the name of World oceans ----get_ocean_names()Get required column names
Description
Gets required column names (except taxa names) for the package. Thisfunction is designed to help users to add additional columns inselect_forcis_columns() (argumentcols) if missing from this list.
These columns are required by some functions (compute_*(),plot_*(),etc.) of the package and shouldn't be deleted.
Usage
get_required_columns()Value
Acharacter vector.
Examples
# Get required column names (expect taxa names) ----get_required_columns()Get species names from column names
Description
Gets species names from column names. This function is just an utility toeasily retrieve taxon names.
Usage
get_species_names(data)Arguments
data | a |
Value
Acharacter vector of species names.
Examples
# Import example dataset ----file_name <- system.file(file.path("extdata", "FORCIS_net_sample.csv"), package = "forcis")net_data <- read.csv(file_name)# Select a taxonomy ----net_data <- select_taxonomy(net_data, taxonomy = "VT")# Retrieve taxon names ----get_species_names(net_data)Print information of a specific version of the FORCIS database
Description
Prints information of a specific version of the FORCIS database by queryingthe Zenodo API (https://developers.zenodo.org).
Usage
get_version_metadata(version = NULL)Arguments
version | a |
Value
Alist with all information about the version, including:title,doi,publication_date,description,access_right,creators,keywords,version,resource_type,license, andfiles.
Examples
# Get information for the latest version of the FORCIS database ----get_version_metadata()Map the spatial distribution of FORCIS data
Description
Maps the spatial distribution of FORCIS data.
Usage
ggmap_data(data, col = "red", ...)Arguments
data | a |
col | a |
... | other graphical parameters passed on to |
Value
Aggplot object.
Examples
# Import example dataset ----file_name <- system.file(file.path("extdata", "FORCIS_net_sample.csv"), package = "forcis")net_data <- read.csv(file_name)# Map data (default) ----ggmap_data(net_data)# Map data ----ggmap_data(net_data, col = "black", fill = "red", shape = 21, size = 2)Plot sample records by depth of collection
Description
This function produces a barplot of FORCIS sample records by depth.
Usage
plot_record_by_depth(data)Arguments
data | a |
Value
Aggplot object.
Examples
# Import example dataset ----file_name <- system.file(file.path("extdata", "FORCIS_net_sample.csv"), package = "forcis")net_data <- read.csv(file_name)# Plot data by year (example dataset) ----plot_record_by_depth(net_data)Plot sample records by month
Description
This function produces a barplot of FORCIS sample records by month.
Usage
plot_record_by_month(data)Arguments
data | a |
Value
Aggplot object.
Examples
# Import example dataset ----file_name <- system.file(file.path("extdata", "FORCIS_net_sample.csv"), package = "forcis")net_data <- read.csv(file_name)# Plot data by year (example dataset) ----plot_record_by_month(net_data)Plot sample records by season
Description
This function produces a barplot of FORCIS sample records by season.
Usage
plot_record_by_season(data)Arguments
data | a |
Value
Aggplot object.
Examples
# Import example dataset ----file_name <- system.file(file.path("extdata", "FORCIS_net_sample.csv"), package = "forcis")net_data <- read.csv(file_name)# Plot data by year (example dataset) ----plot_record_by_season(net_data)Plot sample records by year
Description
This function produces a barplot of FORCIS sample records by year.
Usage
plot_record_by_year(data)Arguments
data | a |
Value
Aggplot object.
Examples
# Import example dataset ----file_name <- system.file(file.path("extdata", "FORCIS_net_sample.csv"), package = "forcis")net_data <- read.csv(file_name)# Plot data by year (example dataset) ----plot_record_by_year(net_data)Read FORCIS data
Description
These functions read one specificcsv file of the FORCIS database(see below) stored in the folderpath. The functiondownload_forcis_db()must be used first to store locally the database.
Usage
read_cpr_north_data( path, version = options()$forcis_version, check_for_update = options()$forcis_check_for_update)read_cpr_south_data( path, version = options()$forcis_version, check_for_update = options()$forcis_check_for_update)read_plankton_nets_data( path, version = options()$forcis_version, check_for_update = options()$forcis_check_for_update)read_pump_data( path, version = options()$forcis_version, check_for_update = options()$forcis_check_for_update)read_sediment_trap_data( path, version = options()$forcis_version, check_for_update = options()$forcis_check_for_update)Arguments
path | a |
version | a |
check_for_update | a |
Details
read_plankton_nets_data()reads the FORCIS plankton nets dataread_pump_data()reads the FORCIS pump dataread_cpr_north_data()reads the FORCIS CPR North dataread_cpr_south_data()reads the FORCIS CPR South dataread_sediment_trap_data()reads the FORCIS sediment traps data
Value
Atibble. Seehttps://zenodo.org/doi/10.5281/zenodo.7390791 for a preview of thedatasets.
See Also
download_forcis_db() to download the complete FORCIS database.
Examples
# Folder in which the database will be saved ----# N.B. In this example we use a temporary folder but you should select an# existing folder (for instance "data/").path <- tempdir()# Download the database ----download_forcis_db(path, timeout = 300)# Import plankton nets data ----plankton_nets_data <- read_plankton_nets_data(path)Select columns in FORCIS data
Description
Selects columns in FORCIS data. Because FORCIS data contains more than 100columns, this function can be used to lighten thedata.frame to easilyhandle it and to speed up some computations.
Usage
select_forcis_columns(data, cols = NULL)Arguments
data | a |
cols | a |
Value
Atibble.
Examples
# Import example dataset ----file_name <- system.file(file.path("extdata", "FORCIS_net_sample.csv"), package = "forcis")net_data <- read.csv(file_name)# Dimensions of the data.frame ----dim(net_data)# Select a taxonomy ----net_data <- select_taxonomy(net_data, taxonomy = "VT")# Dimensions of the data.frame ----dim(net_data)# Select only required columns (and taxa) ----net_data <- select_forcis_columns(net_data)# Dimensions of the data.frame ----dim(net_data)Select a taxonomy in FORCIS data
Description
Selects a taxonomy in FORCIS data. FORCIS database provides three differenttaxonomies:"LT" (lumped taxonomy),"VT" (validated taxonomy) and"OT"(original taxonomy). Seedoi:10.1038/s41597-023-02264-2 for furtherinformation.
Usage
select_taxonomy(data, taxonomy)Arguments
data | a |
taxonomy | a |
Value
Atibble.
Examples
# Import example dataset ----file_name <- system.file(file.path("extdata", "FORCIS_net_sample.csv"), package = "forcis")net_data <- read.csv(file_name)# Dimensions of the data.frame ----dim(net_data)# Select a taxonomy ----net_data <- select_taxonomy(net_data, taxonomy = "VT")# Dimensions of the data.frame ----dim(net_data)