Prepare Darwin Core Event fields — dwc

This function takes a start date/date-time as well as an optional end date/date-time as its main arguments and produces the Darwin Core Event terms. If both a start and end are given the length of time the event took place is assigned to the sampleSizeValue field. If only one of the start or end values have a time component, both values are treated as dates. dwc_Event is essentially a wrapper for a series of lubridate functions, and experienced R users may prefer to use the lubridate functions directly.

Usage

dwc_Event(
  start,
  end = NA,
  time_NA_value = "00:00:00",
  tzone = "UTC",
  sampleSizeUnit = "day",
  fieldNumber = NA,
  habitat = NA,
  samplingProtocol = NA,
  samplingEffort = NA,
  fieldNotes = NA,
  eventRemarks = NA
)

Arguments

start: The start date or date-time of the sampling event. Accepts character strings with dates in one of the following formats: "dmy HMS" (eg, "24/12/2012 15:45:00"), "ymd HMS" (eg, "2012-12-24 15:45:00"), "dmy" (eg, "24/12/2012") or "ymd" (eg, "2012-12-24").
end: The end date or date-time of the sampling event. Default is NA.
time_NA_value: Where a mixture of dates/date-times occur, the dates without times are often assigned a time of 00:00:00. This is the default value here, and is used so that the eventDate field is shown correctly. We suggest being cautious if changing the default.
tzone: The timezone of the date-time passed to parse_date_time. The default is "UTC".
sampleSizeUnit: The unit of time for calculating the length of the event. Passed to time_length as the unit argument. The default is "day".
fieldNumber: Optional argument for what should be included in the fieldNumber term. Default is NA.
habitat: Optional argument for what should be included in the habitat term. Default is NA.
samplingProtocol: Optional argument for what should be included in the samplingProtocol term. Default is NA.
samplingEffort: Optional argument for what should be included in the samplingEffort term. Default is NA.
fieldNotes: Optional argument for what should be included in the fieldNotes term. Default is NA.
eventRemarks: Optional argument for what should be included in the eventRemarks term. Default is NA.

Value

A tibble with Darwin Core terms fieldNumber (if supplied), eventDate, startDayOfYear, endDayOfYear, year, month, day, verbatimEventDate, habitat (if supplied), samplingProtocol

(if supplied), sampleSizeValue (here given as the length of time of the event, given if both the start and end are given), sampleSizeUnit (given if both the start and end are given), samplingEffort (if supplied), fieldNotes (if supplied) and eventRemarks (if supplied).

Examples

# For a single start and a single end date-time:
dwc_Event(start = "2012-12-24 15:00:00", end = "2012-12-27 16:00:00")
#> # A tibble: 1 × 9
#>   eventDate      startDayOfYear endDayOfYear  year month   day verbatimEventDate
#>   <chr>                   <dbl>        <dbl> <dbl> <dbl> <int> <chr>            
#> 1 2012-12-24T15…            359          362  2012    12    24 2012-12-24 15:00…
#> # ℹ 2 more variables: sampleSizeValue <dbl>, sampleSizeUnit <chr>

# The returned tibble will be added to an existing dataframe if combined with
#  dplyr's mutate, for example:

# Load data
data("thylacine_data")

# Use dwc_Event withe dplyr::mutate()
thylacine_data |>
  dplyr::mutate(dwc_Event(
    start = date_trap_setup,
    end = date_trap_collected
  ))
#> # A tibble: 8 × 22
#>   site   trap     date_trap_setup   date_trap_collected longitude_dd latitude_dd
#>   <chr>  <chr>    <chr>             <chr>                      <dbl>       <dbl>
#> 1 Sumac  Sumac 1  05/09/2022 10:32… 06/09/2022 12:24:00         145.       -41.2
#> 2 Sumac  Sumac 2  05/09/2022 12:15… 06/09/2022 14:57:00         145.       -41.2
#> 3 Sumac  Sumac 1  05/10/2022 08:23… 06/10/2022 0:00:00          145.       -41.2
#> 4 Sumac  Sumac 2  05/10/2022 10:14… 06/10/2022 10:29:00         145.       -41.2
#> 5 Picton Picton 1 10/09/2022 10:32… 11/09/2022 12:24:00         147.       -43.3
#> 6 Picton Picton 2 10/09/2022 12:15… 11/09/2022 14:57:00         147.       -43.2
#> 7 Picton Picton 1 10/10/2022 0:00:… 11/10/2022 08:46:00         147.       -43.3
#> 8 Picton Picton 2 10/10/2022 10:14… 11/10/2022 10:29:00         147.       -43.2
#> # ℹ 16 more variables: longitude_dms <chr>, latitude_dms <chr>,
#> #   longitude_ddm <chr>, latitude_ddm <chr>, gps_uncertainty <dbl>,
#> #   species <chr>, count <dbl>, eventDate <chr>, startDayOfYear <dbl>,
#> #   endDayOfYear <dbl>, year <dbl>, month <dbl>, day <int>,
#> #   verbatimEventDate <chr>, sampleSizeValue <dbl>, sampleSizeUnit <chr>