| Title: | 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/>. |
| Authors: | Nicolas Casajus [aut, cre, cph] (ORCID: <https://orcid.org/0000-0002-5537-5294>), Mattia Greco [aut] (ORCID: <https://orcid.org/0000-0003-2416-6235>), Sonia Chaabane [aut] (ORCID: <https://orcid.org/0000-0002-4653-8610>), Xavier Giraud [aut] (ORCID: <https://orcid.org/0000-0001-5067-8176>), Thibault de Garidel-Thoron [aut] (ORCID: <https://orcid.org/0000-0001-8983-9571>), Khalil Hammami [ctb], Air Forbes [rev] (ORCID: <https://orcid.org/0000-0002-9842-7648>), FRB-CESAB [fnd] |
| Maintainer: | Nicolas Casajus <[email protected]> |
| License: | GPL (>= 2) |
| Version: | 1.0.1 |
| Built: | 2025-05-20 10:32:29 UTC |
| Source: | https://github.com/ropensci/forcis |
Functions to convert species counts between different formats: raw abundance, relative abundance, and number concentration, using counts metadata.
compute_abundances(data, aggregate = TRUE) compute_concentrations(data, aggregate = TRUE) compute_frequencies(data, aggregate = TRUE)compute_abundances(data, aggregate = TRUE) compute_concentrations(data, aggregate = TRUE) compute_frequencies(data, aggregate = TRUE)
data |
a |
aggregate |
a |
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).
A tibble in long format with two additional columns: taxa,
the taxon name and counts_*, the number concentration (counts_n_conc) or
the relative abundance (counts_rel_ab) or the raw abundance
(counts_raw_ab).
# 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)# 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)
Reshapes FORCIS data by pivoting species columns into two columns: taxa
(taxon names) and counts (taxon abundances). It converts wider data.frame
to a long format.
convert_to_long_format(data)convert_to_long_format(data)
data |
a |
A tibble reshaped in a long format.
# 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)# 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)
This function can be used to convert a data.frame into an sf object.
Note that coordinates (columns site_lon_start_decimal and
site_lat_start_decimal) are projected in the Robinson coordinate system.
data_to_sf(data)data_to_sf(data)
data |
a |
An sf POINTS object.
# 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)# 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)
Downloads the entire FORCIS database as a collection of five csv files from
Zenodo (https://zenodo.org/doi/10.5281/zenodo.7390791). Additional
files will be also downloaded.
download_forcis_db( path, version = options()$forcis_version, check_for_update = options()$forcis_check_for_update, overwrite = FALSE, timeout = 60 )download_forcis_db( path, version = options()$forcis_version, check_for_update = options()$forcis_check_for_update, overwrite = FALSE, timeout = 60 )
path |
a |
version |
a |
check_for_update |
a |
overwrite |
a |
timeout |
an |
The FORCIS database is regularly updated. The global structure of the tables
doesn’t change between versions but some bugs can be fixed and new records
can be added. This is why it is recommended to use the latest version of the
database. The package is designed to handle the versioning of the database on
Zenodo and will inform the user if a new version is available each time
he/she uses one of the read_*_data() functions.
For more information, please read the vignette available at https://docs.ropensci.org/forcis/articles/database-versions.html.
No return value. The FORCIS files will be saved in the path folder.
Chaabane S, De Garidel-Thoron T, Giraud X, et al. (2023) The FORCIS database: A global census of planktonic Foraminifera from ocean waters. Scientific Data, 10, 354. DOI: doi:10.1038/s41597-023-02264-2.
read_plankton_nets_data() to import the FORCIS database.
# 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)# 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)
Filters FORCIS data by a spatial bounding box.
filter_by_bbox(data, bbox)filter_by_bbox(data, bbox)
data |
a |
bbox |
an object of class |
A tibble containing a subset of data for the desired bounding
box.
# 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)# 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)
Filters FORCIS data by month of sampling.
filter_by_month(data, months)filter_by_month(data, months)
data |
a |
months |
a |
A tibble containing a subset of data for the desired months.
# 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)# 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)
Filters FORCIS data by one or several oceans.
filter_by_ocean(data, ocean)filter_by_ocean(data, ocean)
data |
a |
ocean |
a |
A tibble containing a subset of data for the desired oceans.
# 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)# 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)
Filters FORCIS data by a spatial polygon.
filter_by_polygon(data, polygon)filter_by_polygon(data, polygon)
data |
a |
polygon |
an |
A tibble containing a subset of data for the desired spatial
polygon.
# 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)# 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)
Filters FORCIS data by a species list.
filter_by_species(data, species)filter_by_species(data, species)
data |
a |
species |
a |
A tibble containing a subset of data.
# 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)# 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)
Filters FORCIS data by year of sampling.
filter_by_year(data, years)filter_by_year(data, years)
data |
a |
years |
a |
A tibble containing a subset of data for the desired years.
# 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)# 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)
Creates a World base map that can be added to a ggplot object.
Spatial layers come from the Natural Earth project
(https://www.naturalearthdata.com/) and are defined in the Robinson
coordinate system.
geom_basemap()geom_basemap()
A ggplot object.
# Attach package ---- library("ggplot2") # World basemap ---- ggplot() + geom_basemap()# Attach package ---- library("ggplot2") # World basemap ---- ggplot() + geom_basemap()
Gets all available versions of the FORCIS database by querying the Zenodo API (https://developers.zenodo.org).
get_available_versions()get_available_versions()
A tibble with three columns:
publication_date: the date of the release of the version
version: the label of the version
access_right: is the version open or restricted?
# Versions of the FORCIS database ---- get_available_versions()# Versions of the FORCIS database ---- get_available_versions()
This function returns the name of World oceans according to the IHO Sea Areas dataset version 3 (Flanders Marine Institute, 2018).
get_ocean_names()get_ocean_names()
A character vector with World ocean names.
Flanders Marine Institute (2018). IHO Sea Areas, version 3. Available online at: https://www.marineregions.org/. DOI: doi:10.14284/323.
# Print the name of World oceans ---- get_ocean_names()# Print the name of World oceans ---- get_ocean_names()
Gets required column names (except taxa names) for the package. This
function is designed to help users to add additional columns in
select_forcis_columns() (argument cols) if missing from this list.
These columns are required by some functions (compute_*(), plot_*(),
etc.) of the package and shouldn't be deleted.
get_required_columns()get_required_columns()
A character vector.
# Get required column names (expect taxa names) ---- get_required_columns()# Get required column names (expect taxa names) ---- get_required_columns()
Gets species names from column names. This function is just an utility to easily retrieve taxon names.
get_species_names(data)get_species_names(data)
data |
a |
A character vector of species names.
# 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)# 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)
Prints information of a specific version of the FORCIS database by querying the Zenodo API (https://developers.zenodo.org).
get_version_metadata(version = NULL)get_version_metadata(version = NULL)
version |
a |
A list with all information about the version, including: title,
doi, publication_date, description, access_right, creators,
keywords, version, resource_type, license, and files.
# Get information for the latest version of the FORCIS database ---- get_version_metadata()# Get information for the latest version of the FORCIS database ---- get_version_metadata()
Maps the spatial distribution of FORCIS data.
ggmap_data(data, col = "red", ...)ggmap_data(data, col = "red", ...)
data |
a |
col |
a |
... |
other graphical parameters passed on to |
A ggplot object.
# 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)# 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)
This function produces a barplot of FORCIS sample records by depth.
plot_record_by_depth(data)plot_record_by_depth(data)
data |
a |
A ggplot object.
# 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)# 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)
This function produces a barplot of FORCIS sample records by month.
plot_record_by_month(data)plot_record_by_month(data)
data |
a |
A ggplot object.
# 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)# 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)
This function produces a barplot of FORCIS sample records by season.
plot_record_by_season(data)plot_record_by_season(data)
data |
a |
A ggplot object.
# 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)# 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)
This function produces a barplot of FORCIS sample records by year.
plot_record_by_year(data)plot_record_by_year(data)
data |
a |
A ggplot object.
# 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)# 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)
These functions read one specific csv file of the FORCIS database
(see below) stored in the folder path. The function download_forcis_db()
must be used first to store locally the database.
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 )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 )
path |
a |
version |
a |
check_for_update |
a |
read_plankton_nets_data() reads the FORCIS plankton nets data
read_pump_data() reads the FORCIS pump data
read_cpr_north_data() reads the FORCIS CPR North data
read_cpr_south_data() reads the FORCIS CPR South data
read_sediment_trap_data() reads the FORCIS sediment traps data
A tibble. See
https://zenodo.org/doi/10.5281/zenodo.7390791 for a preview of the
datasets.
download_forcis_db() to download the complete FORCIS database.
# 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)# 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)
Selects columns in FORCIS data. Because FORCIS data contains more than 100
columns, this function can be used to lighten the data.frame to easily
handle it and to speed up some computations.
select_forcis_columns(data, cols = NULL)select_forcis_columns(data, cols = NULL)
data |
a |
cols |
a |
A tibble.
# 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)# 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)
Selects a taxonomy in FORCIS data. FORCIS database provides three different
taxonomies: "LT" (lumped taxonomy), "VT" (validated taxonomy) and "OT"
(original taxonomy). See doi:10.1038/s41597-023-02264-2 for further
information.
select_taxonomy(data, taxonomy)select_taxonomy(data, taxonomy)
data |
a |
taxonomy |
a |
A tibble.
# 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)# 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)