doc: document filter and select functions

R/filter_by_bbox.R

@@ -1,9 +1,9 @@
 #' Filter FORCIS data by a spatial bounding box 
 #'
 #' @description
-#' This function can be used to filter FORCIS data by a spatial bounding box.
+#' Filters FORCIS data by a spatial bounding box.
 #' 
-#' @param data a `data.frame`, i.e. a FORCIS dataset.
+#' @param data a `data.frame`. One obtained by `read_*_data()` functions.
 #' 
 #' @param bbox an object of class `bbox` (package `sf`) or a vector of four 
 #'   `numeric` values defining a square bounding box. Values must follow this 
@@ -12,12 +12,35 @@
 #'   **Important:** if a vector of numeric values is provided, coordinates must
 #'   be defined in the system WGS 84 (`epsg=4326`).
 #'
-#' @return A `data.frame` containing a subset of `data`.
+#' @return A `data.frame` containing a subset of `data` for the desired 
+#'   bounding box.
 #' 
 #' @export
 #'
 #' @examples
-#' ## ADD EXAMPLE ----
+#' # Attach the package ----
+#' library("forcis")
+#' 
+#' # Import example dataset ----
+#' file_name <- system.file(file.path("extdata", "FORCIS_pump_sample.csv"), 
+#'                          package = "forcis")
+#' 
+#' pump_data <- vroom::vroom(file_name, delim = ";", show_col_types = FALSE)
+#' 
+#' # Add 'data_type' column ----
+#' pump_data$"data_type" <- "Pump"
+#' 
+#' # Dimensions of the data.frame ----
+#' dim(pump_data)
+#' 
+#' # Get ocean names ----
+#' get_ocean_names()
+#' 
+#' # Filter by oceans ----
+#' pump_data_sub <- filter_by_bbox(pump_data, bbox = c(35, 0, 45, 30))
+#' 
+#' # Dimensions of the data.frame ----
+#' dim(pump_data_sub)
 
 filter_by_bbox <- function(data, bbox) {
 

R/filter_by_month.R

@@ -1,9 +1,9 @@
 #' Filter FORCIS data by month of sampling
 #'
 #' @description
-#' This function can be used to filter FORCIS data by month of sampling.
+#' Filters FORCIS data by month of sampling.
 #' 
-#' @param data a `data.frame`, i.e. a FORCIS dataset.
+#' @param data a `data.frame`. One obtained by `read_*_data()` functions.
 #' 
 #' @param months a `numeric` containing one or several months.
 #'
@@ -12,7 +12,26 @@
 #' @export
 #' 
 #' @examples
-#' ## ADD EXAMPLE ----
+#' # Attach the package ----
+#' library("forcis")
+#' 
+#' # Import example dataset ----
+#' file_name <- system.file(file.path("extdata", "FORCIS_pump_sample.csv"), 
+#'                          package = "forcis")
+#' 
+#' pump_data <- vroom::vroom(file_name, delim = ";", show_col_types = FALSE)
+#' 
+#' # Add 'data_type' column ----
+#' pump_data$"data_type" <- "Pump"
+#' 
+#' # Dimensions of the data.frame ----
+#' dim(pump_data)
+#' 
+#' # Filter by months ----
+#' pump_data_sub <- filter_by_month(pump_data, months = 1:2)
+#' 
+#' # Dimensions of the data.frame ----
+#' dim(pump_data_sub)
 
 filter_by_month <- function(data, months) {
 

R/filter_by_ocean.R

@@ -1,19 +1,41 @@
 #' Filter FORCIS data by ocean
 #'
 #' @description
-#' This function can be used to filter FORCIS data by one or several oceans.
+#' Filters FORCIS data by one or several oceans.
 #' 
-#' @param data a `data.frame`, i.e. a FORCIS dataset.
+#' @param data a `data.frame`. One obtained by `read_*_data()` functions.
 #' 
 #' @param ocean a `character` vector of one or several ocean names. Use the
 #'   function `get_ocean_names()` to find the correct spelling.
 #'
-#' @return A `data.frame` containing a subset of `data`.
+#' @return A `data.frame` containing a subset of `data` for the desired oceans.
 #' 
 #' @export
 #'
 #' @examples
-#' ## ADD EXAMPLE ----
+#' # Attach the package ----
+#' library("forcis")
+#' 
+#' # Import example dataset ----
+#' file_name <- system.file(file.path("extdata", "FORCIS_pump_sample.csv"), 
+#'                          package = "forcis")
+#' 
+#' pump_data <- vroom::vroom(file_name, delim = ";", show_col_types = FALSE)
+#' 
+#' # Add 'data_type' column ----
+#' pump_data$"data_type" <- "Pump"
+#' 
+#' # Dimensions of the data.frame ----
+#' dim(pump_data)
+#' 
+#' # Get ocean names ----
+#' get_ocean_names()
+#' 
+#' # Filter by oceans ----
+#' pump_data_sub <- filter_by_ocean(pump_data, ocean = "Indian Ocean")
+#' 
+#' # Dimensions of the data.frame ----
+#' dim(pump_data_sub)
 
 filter_by_ocean <- function(data, ocean) {
 

R/filter_by_polygon.R

@@ -1,18 +1,44 @@
 #' Filter FORCIS data by a spatial polygon
 #'
 #' @description
-#' This function can be used to filter FORCIS data by a spatial polygon.
+#' Filters FORCIS data by a spatial polygon.
 #' 
-#' @param data a `data.frame`, i.e. a FORCIS dataset.
+#' @param data a `data.frame`. One obtained by `read_*_data()` functions.
 #' 
 #' @param polygon an `sf POLYGON` object.
 #'
-#' @return A `data.frame` containing a subset of `data`.
+#' @return A `data.frame` containing a subset of `data` for the desired spatial
+#'   polygon.
 #' 
 #' @export
 #'
 #' @examples
-#' ## ADD EXAMPLE ----
+#' # Attach the package ----
+#' library("forcis")
+#' 
+#' # Import example dataset ----
+#' file_name <- system.file(file.path("extdata", "FORCIS_pump_sample.csv"), 
+#'                          package = "forcis")
+#' 
+#' pump_data <- vroom::vroom(file_name, delim = ";", show_col_types = FALSE)
+#' 
+#' # Add 'data_type' column ----
+#' pump_data$"data_type" <- "Pump"
+#' 
+#' # Dimensions of the data.frame ----
+#' dim(pump_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 ----
+#' pump_data_sub <- filter_by_polygon(pump_data, polygon = indian_ocean)
+#' 
+#' # Dimensions of the data.frame ----
+#' dim(pump_data_sub)
 
 filter_by_polygon <- function(data, polygon) {
 

R/filter_by_species.R

@@ -1,20 +1,58 @@
 #' Filter FORCIS data by species 
 #'
 #' @description
-#' A short description...
+#' Filters FORCIS data by a species list.
 #' 
-#' @param data a `data.frame`, i.e. a FORCIS dataset, except for CPR North data.
+#' @param data a `data.frame`. Must be the output of the function 
+#'   `reshape_data()`, i.e. a FORCIS dataset in long format.
 #' 
 #' @param species a `character` vector listing species of interest.
 #' 
-#' @param rm_na a `logical` value. If `FALSE`, keeps taxa with `NA` counts.
+#' @param rm_na a `logical` value. If `FALSE` (default), keeps taxa with `NA` 
+#'   counts.
 #' 
 #' @return A `data.frame` containing a subset of `data`.
 #' 
 #' @export
 #'
 #' @examples
-#' ## ADD EXAMPLE ----
+#' # Import example dataset ----
+#' file_name <- system.file(file.path("extdata", "FORCIS_pump_sample.csv"), 
+#'                          package = "forcis")
+#' 
+#' pump_data <- vroom::vroom(file_name, delim = ";", show_col_types = FALSE)
+#' 
+#' # Add 'data_type' column ----
+#' pump_data$"data_type" <- "Pump"
+#' 
+#' # Select a taxonomy ----
+#' pump_data <- select_taxonomy(pump_data, taxonomy = "OT")
+#' 
+#' # Select only required columns (and taxa) ----
+#' pump_data <- select_columns(pump_data)
+#' 
+#' # Dimensions of the data.frame ----
+#' dim(pump_data)
+#' 
+#' # Convert data into long format ----
+#' pump_data <- reshape_data(pump_data)
+#' 
+#' # Dimensions of the data.frame ----
+#' dim(pump_data)
+#' 
+#' # Total number of species ----
+#' length(unique(pump_data$"taxa"))
+#' 
+#' # Select records for three species ----
+#' pump_data_sub <- filter_by_species(data    = pump_data, 
+#'                                    species = c("g_inflata", "g_ruber", 
+#'                                                "g_glutinata"))
+#'
+#' # Dimensions of the data.frame ----
+#' dim(pump_data_sub)
+#' 
+#' # Total number of species ----
+#' length(unique(pump_data_sub$"taxa"))
 
 filter_by_species <- function(data, species, rm_na = FALSE) {
 

R/filter_by_year.R

@@ -1,9 +1,9 @@
 #' Filter FORCIS data by year of sampling
 #'
 #' @description
-#' This function can be used to filter FORCIS data by year of sampling.
+#' Filters FORCIS data by year of sampling.
 #' 
-#' @param data a `data.frame`, i.e. a FORCIS dataset.
+#' @param data a `data.frame`. One obtained by `read_*_data()` functions.
 #' 
 #' @param years a `numeric` containing one or several years.
 #'
@@ -12,7 +12,26 @@
 #' @export
 #'
 #' @examples
-#' ## ADD EXAMPLE ----
+#' # Attach the package ----
+#' library("forcis")
+#' 
+#' # Import example dataset ----
+#' file_name <- system.file(file.path("extdata", "FORCIS_pump_sample.csv"), 
+#'                          package = "forcis")
+#' 
+#' pump_data <- vroom::vroom(file_name, delim = ";", show_col_types = FALSE)
+#' 
+#' # Add 'data_type' column ----
+#' pump_data$"data_type" <- "Pump"
+#' 
+#' # Dimensions of the data.frame ----
+#' dim(pump_data)
+#' 
+#' # Filter by years ----
+#' pump_data_sub <- filter_by_year(pump_data, years = 1985)
+#' 
+#' # Dimensions of the data.frame ----
+#' dim(pump_data_sub)
 
 filter_by_year <- function(data, years) {
 

R/select_columns.R

@@ -8,26 +8,40 @@
 #' @param data a `data.frame`. One obtained by `read_*_data()` functions.
 #'
 #' @param cols a `character` vector of column names to keep in addition to the 
-#'   required ones (see [get_required_columns()]) and to the taxa columns.
+#'   required ones (see [get_required_columns()]) and to the taxa columns. Can 
+#'   be `NULL` (default).
 #' 
 #' @export
 #'
 #' @return A `data.frame`.
 #' 
 #' @examples
-#' \dontrun{
-#' # Folder in which the database is stored ----
-#' path_to_db <- "data"
+#' # Attach the package ----
+#' library("forcis")
 #' 
-#' # Download and read the plankton nets data ----
-#' nets <- forcis::read_plankton_nets_data(path_to_db)
+#' # Import example dataset ----
+#' file_name <- system.file(file.path("extdata", "FORCIS_pump_sample.csv"), 
+#'                          package = "forcis")
+#' 
+#' pump_data <- vroom::vroom(file_name, delim = ";", show_col_types = FALSE)
+#' 
+#' # Add 'data_type' column ----
+#' pump_data$"data_type" <- "Pump"
+#' 
+#' # Dimensions of the data.frame ----
+#' dim(pump_data)
 #' 
 #' # Select a taxonomy ----
-#' nets <- forcis::select_taxonomy(nets, taxonomy = "OT")
+#' pump_data <- select_taxonomy(pump_data, taxonomy = "OT")
+#' 
+#' # Dimensions of the data.frame ----
+#' dim(pump_data)
+#' 
+#' # Select only required columns (and taxa) ----
+#' pump_data <- select_columns(pump_data)
 #' 
-#' # Select required columns (and taxa) ----
-#' nets <- forcis::select_columns(nets)
-#' }
+#' # Dimensions of the data.frame ----
+#' dim(pump_data)
 
 select_columns <- function(data, cols = NULL) {
 

R/select_taxonomy.R

@@ -15,16 +15,26 @@
 #' @return A `data.frame`.
 #' 
 #' @examples
-#' \dontrun{
-#' # Folder in which the database is stored ----
-#' path_to_db <- "data"
+#' # Attach the package ----
+#' library("forcis")
 #' 
-#' # Download and read the plankton nets data ----
-#' nets <- forcis::read_plankton_nets_data(path_to_db)
+#' # Import example dataset ----
+#' file_name <- system.file(file.path("extdata", "FORCIS_pump_sample.csv"), 
+#'                          package = "forcis")
+#' 
+#' pump_data <- vroom::vroom(file_name, delim = ";", show_col_types = FALSE)
+#' 
+#' # Add 'data_type' column ----
+#' pump_data$"data_type" <- "Pump"
+#' 
+#' # Dimensions of the data.frame ----
+#' dim(pump_data)
 #' 
 #' # Select a taxonomy ----
-#' nets <- forcis::select_taxonomy(nets, taxonomy = "OT")
-#' }
+#' pump_data <- select_taxonomy(pump_data, taxonomy = "OT")
+#' 
+#' # Dimensions of the data.frame ----
+#' dim(pump_data)
 
 select_taxonomy <- function(data, taxonomy) {