Switch use_ function prefix to set_

NAMESPACE

@@ -8,20 +8,20 @@ export(event_terms)
 export(occurrence_terms)
 export(random_id)
 export(sequential_id)
+export(set_abundance)
+export(set_collection)
+export(set_coordinates)
+export(set_coordinates_sf)
+export(set_datetime)
+export(set_events)
+export(set_locality)
+export(set_measurements)
+export(set_observer)
+export(set_occurrences)
+export(set_scientific_name)
+export(set_taxonomy)
 export(suggest_workflow)
-export(use_abundance)
-export(use_collection)
-export(use_coordinates)
-export(use_datetime)
-export(use_events)
 export(use_individual_traits)
-export(use_locality)
-export(use_measurements)
-export(use_observer)
-export(use_occurrences)
-export(use_scientific_name)
-export(use_sf)
-export(use_taxonomy)
 importFrom(cli,ansi_align)
 importFrom(cli,ansi_collapse)
 importFrom(cli,ansi_nchar)

R/check.R

@@ -49,7 +49,7 @@ wait <- function(seconds = 1) {
 #'
 #' @description
 #' Informs users which columns will be checked by `check_` functions. This includes
-#' columns that have been specified in a `use_` function by the user, or columns
+#' columns that have been specified in a `set_` function by the user, or columns
 #' that exist in the user dataframe that already match Darwin Core terms.
 #'
 #' @importFrom cli cli_progress_step

R/corella-package.R

@@ -27,19 +27,19 @@
 #'  The following functions add single DwC fields, or collections of related
 #'  fields, to an existing `tibble`.
 #'
-#'   * [use_events()] basic information on observation events (`eventID`, `parentEventID`, `eventType`)
-#'   * [use_occurrences()] basic information on observations (`occurrenceID`, `basisOfRecord`)
-#'   * [use_scientific_name()] record the highest level of taxonomic specificity in the dataset (`scientificName`, `scientificNameAuthorship`, `taxonRank`)
-#'   * [use_taxonomy()] to specify higher taxonomic columns (`kingdom`, `phylum`, `class`, `order`, `family`, `genus`, `species`, `specificEpithet`, `vernacularName`)
-#'   * [use_coordinates()] for spatial data (`decimalLatitude`, `decimalLongitude`, `geodeticDatum`, `coordinateUncertaintyInMeters`, `coordinatePrecision`)
-#'   * [use_sf()] for spatial data in `sf` format
-#'   * [use_locality()] for spatial descriptions (`continent`, `country`, `countryCode`, `stateProvince`, `locality`)
-#'   * [use_datetime()] for temporal data (`eventDate`, `year`, `month`, `day`, `eventTime`)
-#'   * [use_collection()] to give museum- or collection- specific information (`datasetID`, `datasetName`, `catalogNumber`)
-#'   * [use_observer()] to specify who made the observation (`recordedByID`, `recordedBy`)
-#'   * [use_abundance()] to state how many animals were seen during the observation (`individualCount`, `organismQuantity`, `organismQuantityType`)
-#'   * [use_individual_traits()] attributes of individuals measured (`individualID`, `lifeStage`, `sex`, `vitality`, `reproductiveCondition`)
-#'   * [use_measurements()] for 'Measurement or Fact' data (optional)
+#'   * [set_events()] basic information on observation events (`eventID`, `parentEventID`, `eventType`)
+#'   * [set_occurrences()] basic information on observations (`occurrenceID`, `basisOfRecord`)
+#'   * [set_scientific_name()] record the highest level of taxonomic specificity in the dataset (`scientificName`, `scientificNameAuthorship`, `taxonRank`)
+#'   * [set_taxonomy()] to specify higher taxonomic columns (`kingdom`, `phylum`, `class`, `order`, `family`, `genus`, `species`, `specificEpithet`, `vernacularName`)
+#'   * [set_coordinates()] for spatial data (`decimalLatitude`, `decimalLongitude`, `geodeticDatum`, `coordinateUncertaintyInMeters`, `coordinatePrecision`)
+#'   * [set_coordinates_sf()] for spatial data in `sf` format
+#'   * [set_locality()] for spatial descriptions (`continent`, `country`, `countryCode`, `stateProvince`, `locality`)
+#'   * [set_datetime()] for temporal data (`eventDate`, `year`, `month`, `day`, `eventTime`)
+#'   * [set_collection()] to give museum- or collection- specific information (`datasetID`, `datasetName`, `catalogNumber`)
+#'   * [set_observer()] to specify who made the observation (`recordedByID`, `recordedBy`)
+#'   * [set_abundance()] to state how many animals were seen during the observation (`individualCount`, `organismQuantity`, `organismQuantityType`)
+#'   * [set_individual_traits()] attributes of individuals measured (`individualID`, `lifeStage`, `sex`, `vitality`, `reproductiveCondition`)
+#'   * [set_measurements()] for 'Measurement or Fact' data (optional)
 #'
 #'  **Checking data for Darwin Core compliance**
 #'

R/use_abundance.R → R/set_abundance.R

@@ -1,10 +1,15 @@
-#' Add abundance fields to a `tibble`
+#' Set, create or modify columns with abundance information using Darwin Core
 #'
+#' @description
 #' In some field methods, it is common to observe more than one individual
 #' per observation; to observe abundance using non-integer measures such as
 #' mass or area; or to seek individuals but not find them (abundance of zero).
-#' As these approaches use different DwC terms, this function assists in
+#' As these approaches use different Darwin Core terms, this function assists in
 #' specifying abundances in a flexible way.
+#'
+#' In practice this is no different from using `mutate()`, but gives some
+#' informative errors, and serves as a useful lookup for how columns with
+#' abundance information are represented in the Darwin Core Standard.
 #' @param .df a `data.frame` or `tibble` that the column should be appended to.
 #' @param individualCount The number of individuals present
 #' @param organismQuantity A number or enumeration value for the quantity of
@@ -33,12 +38,12 @@
 #'   )
 #'
 #' df |>
-#'   use_abundance(individualCount = n_obs)
+#'   set_abundance(individualCount = n_obs)
 #'
 #' @importFrom dplyr mutate
 #' @importFrom rlang abort
 #' @export
-use_abundance <- function(.df,
+set_abundance <- function(.df,
                           individualCount = NULL,
                           organismQuantity = NULL,
                           organismQuantityType = NULL,

R/use_collection.R → R/set_collection.R

@@ -1,4 +1,4 @@
-#' Add museum- or collection-specific information to a `tibble`
+#' Set, create or modify columns with museum- or collection-specific information using Darwin Core
 #'
 #' @description
 #' Format fields that specify the collection or catalog number of a
@@ -37,7 +37,7 @@
 #' @importFrom dplyr mutate
 #' @importFrom rlang abort
 #' @export
-use_collection <- function(
+set_collection <- function(
     .df,
     datasetID = NULL,
     datasetName = NULL,

R/use_coordinates.R → R/set_coordinates.R

@@ -1,4 +1,4 @@
-#' Add spatial fields to a `tibble`
+#' Set, create or modify columns with spatial information using Darwin Core
 #'
 #' This function helps format standard location fields to a `tibble`.
 #'
@@ -31,7 +31,7 @@
 #' @importFrom dplyr mutate
 #' @importFrom rlang abort
 #' @export
-use_coordinates <- function(
+set_coordinates <- function(
     .df,
     decimalLatitude = NULL,
     decimalLongitude = NULL,

R/use_sf.R → R/set_coordinates_sf.R

@@ -1,7 +1,8 @@
-#' Add spatial fields to a `tibble` using `sf` `POINT` coordinates
+#' Set, create or modify columns with `sf` spatial information using Darwin Core
 #'
+#' @description
 #' This function helps format standard location fields to a `tibble`. It differs
-#' from `use_coordinates()` by accepting `sf` geometry columns of class `POINT`
+#' from `set_coordinates()` by accepting `sf` geometry columns of class `POINT`
 #' as coordinates (rather than `numeric` lat/lon coordinates). The advantage
 #' of using an `sf` geometry is that the Coordinate Reference System (CRS) is
 #' automatically formatted into the required `geodeticDatum` column.
@@ -13,16 +14,16 @@
 #' `"unused"`; i.e. only keeps Darwin Core fields, and not those fields used to
 #' generate them.
 #' @returns A tibble with the requested fields added.
-#' @seealso [use_coordinates()] for providing numeric coordinates,
-#' [use_locality()] for providing text-based spatial information
+#' @seealso [set_coordinates()] for providing numeric coordinates,
+#' [set_locality()] for providing text-based spatial information
 #' @importFrom rlang abort
 #' @importFrom rlang get_expr
 #' @importFrom sf st_drop_geometry
 #' @importFrom sf st_geometry_type
 #' @importFrom cli cli_warn
 #' @importFrom cli cli_abort
 #' @export
-use_sf <- function(
+set_coordinates_sf <- function(
     .df,
     geometry = NULL,
     .keep = "unused"

R/use_datetime.R → R/set_datetime.R

@@ -1,6 +1,7 @@
-#' Add date and time fields to a `tibble`
+#' Set, create or modify columns with date and time information using Darwin Core
 #'
-#' This function helps format standard date/time fields to a `tibble`.
+#' @description
+#' This function helps format standard date/time columns in a `tibble`.
 #'
 #' In practice this is no different from using `mutate()`, but gives some
 #' informative errors, and serves as a useful lookup for how spatial fields are
@@ -27,7 +28,7 @@
 #' @importFrom dplyr mutate
 #' @importFrom rlang abort
 #' @export
-use_datetime <- function(
+set_datetime <- function(
     .df,
     eventDate = NULL,
     year = NULL,

R/use_events.R → R/set_events.R

@@ -1,7 +1,7 @@
-#' Add a sampling, collection or image-capture Event to a `tibble`
+#' Set, create or modify columns with Event information using Darwin Core
 #'
 #' @description
-#' Format fields that contain information about an
+#' Format columns that contain information about an
 #' [Event](https://dwc.tdwg.org/list/#dwc_Event). An "Event" in Darwin Core
 #' standard refers to an action that occurs at a place and time. Examples
 #' include:
@@ -62,7 +62,7 @@
 #' @importFrom purrr map
 #' @importFrom purrr keep
 #' @export
-use_events <- function(
+set_events <- function(
     .df,
     eventID = NULL,
     eventType = NULL,

R/use_individual_traits.R → R/set_individual_traits.R

@@ -1,4 +1,4 @@
-#' Add information of individual organisms to a `tibble`
+#' Set, create or modify columns with information of individual organisms using Darwin Core
 #'
 #' @description
 #' Format fields that contain measurements or attributes of individual

R/use_locality.R → R/set_locality.R

@@ -1,7 +1,13 @@
-#' Add `locality` data to a `tibble`
+#' Set, create or modify columns with locality information using Darwin Core
 #'
+#' @description
 #' Locality information refers to a description of a place, rather than a
-#' spatial coordinate.
+#' spatial coordinate. This function helps specify or modify columns
+#' with locality information in a flexible way.
+#'
+#' In practice this is no different from using `mutate()`, but gives some
+#' informative errors, and serves as a useful lookup for fields in
+#' the Darwin Core Standard.
 #' @param .df a `data.frame` or `tibble` that the column should be appended to.
 #' @param continent (string) Valid continent. See details.
 #' @param country Valid country name. See `country_codes`.
@@ -30,7 +36,7 @@
 #' @importFrom purrr map
 #' @importFrom purrr pluck
 #' @export
-use_locality <- function(.df,
+set_locality <- function(.df,
                          continent = NULL,
                          country = NULL,
                          countryCode = NULL,

R/use_measurements.R → R/set_measurements.R

@@ -1,8 +1,21 @@
-#' Add measurement data for an individual or event to a `tibble`
+#' Convert columns with measurement data for an individual or event to Darwin Core standard
 #'
 #' @description
+#' `r lifecycle::badge("experimental")`
 #' This function is a work in progress, and should be used with caution.
 #'
+#' In raw collected data, many types of information can be captured in one
+#' column. For example, the column name `LMA_g.m2` contains the measured trait
+#' (Leaf Mass per Area, LMA) and the unit of measurement (grams per meter
+#' squared, g/m2), and recorded in that column are the values themselves. In
+#' Darwin Core, these different types of information must be separated into
+#' multiple columns so that they can be ingested correctly and aggregated with
+#' sources of data accurately.
+#'
+#' This function converts information preserved in a single measurement column
+#' into multiple columns (`measurementID`, `measurementUnit`, and
+#' `measurementType`) as per Darwin Core standard.
+#'
 #' @param .df a `data.frame` or `tibble` that the column should be appended to.
 #' @param cols vector of column names to be included as 'measurements'. Unquoted.
 #' @param unit vector of strings giving units for each variable
@@ -13,7 +26,13 @@
 #' generate them.
 #' @returns A tibble with the requested fields added.
 #' @details
-#' add examples
+#' Columns are nested in a
+#' single column `measurementOrFact` that contains Darwin Core standard
+#' measurement fields. By nesting three measurement columns within the
+#' `measurementOrFact`, despite measurement columns converting to long format
+#' (one row per measurement, per occurrence),
+#' data will remain organised by occurrences (one row per occurrences). Data
+#' can be unnested into long format using `dplyr::unnest()`
 #'
 #' @importFrom dplyr mutate
 #' @importFrom rlang abort
@@ -23,7 +42,7 @@
 #' @importFrom dplyr row_number
 #' @importFrom purrr map_dfr
 #' @export
-use_measurements <- function(
+set_measurements <- function(
     .df,
     cols = NULL,
     unit = NULL,

R/use_observer.R → R/set_observer.R

@@ -1,5 +1,6 @@
-#' Add who made an observation to a `tibble`
+#' Set, create or modify columns with information of who made an observation (using Darwin Core)
 #'
+#' @description
 #' Format fields that contain information about who made a specific observation
 #' of an organism.
 #'
@@ -34,7 +35,7 @@
 #' @importFrom purrr map
 #' @importFrom purrr keep
 #' @export
-use_observer <- function(
+set_observer <- function(
     .df,
     recordedBy = NULL,
     recordedByID = NULL,

R/use_occurrences.R → R/set_occurrences.R

@@ -1,4 +1,4 @@
-#' Add occurrence-specific information to a `tibble`
+#' Set, create or modify columns with occurrence-specific information using Darwin Core
 #'
 #' @description
 #' Format fields uniquely identify each occurrence record and specify the type
@@ -45,7 +45,7 @@
 #' @importFrom dplyr mutate
 #' @importFrom rlang abort
 #' @export
-use_occurrences <- function(
+set_occurrences <- function(
     .df,
     occurrenceID = NULL,
     basisOfRecord = NULL,

R/use_scientific_name.R → R/set_scientific_name.R

@@ -1,4 +1,4 @@
-#' Add scientific name and authorship to a `tibble`
+#' Set, create or modify columns with scientific name and authorship information using Darwin Core
 #'
 #' Format the field `scientificName`, the lowest identified taxonomic name of an
 #' occurrence, along with the rank and authorship of the provided name.
@@ -36,7 +36,7 @@
 #' @importFrom dplyr mutate
 #' @importFrom rlang abort
 #' @export
-use_scientific_name <- function(
+set_scientific_name <- function(
     .df,
     scientificName = NULL,
     scientificNameAuthorship = NULL,

R/use_taxonomy.R → R/set_taxonomy.R

@@ -1,5 +1,6 @@
-#' Add taxonomic information to a `tibble`
+#' Set, create or modify columns with taxonomic information using Darwin Core
 #'
+#' @description
 #' Format fields that contain taxonomic name information from kingdom to
 #' species, as well as the common/vernacular name, to a `tibble`.
 #'
@@ -32,7 +33,7 @@
 #' @importFrom dplyr mutate
 #' @importFrom rlang abort
 #' @export
-use_taxonomy <- function(
+set_taxonomy <- function(
     .df,
     kingdom = NULL,
     phylum = NULL,