Set, create or modify columns with locality information

Locality information refers to a description of a place, rather than a spatial coordinate. This function helps to format columns with locality information to a tibble using Darwin Core Standard.

In practice this is used no differently from mutate(), but gives some informative errors, and serves as a useful lookup for fields in the Darwin Core Standard.

Usage

set_locality(
  .df,
  continent = NULL,
  country = NULL,
  countryCode = NULL,
  stateProvince = NULL,
  locality = NULL,
  .keep = "unused"
)

Arguments

.df

A data.frame or tibble that the column should be appended to.

continent

(string) Valid continent. See details.

country

Valid country name. See country_codes.

countryCode

Valid country code. See country_codes.

stateProvince

A sub-national region.

locality

A specific description of a location or place.

.keep

Control which columns from .data are retained in the output. Note that unlike dplyr::mutate(), which defaults to "all" this defaults to "unused"; i.e. only keeps Darwin Core columns, and not those columns used to generate them.

Value

A tibble with the requested columns added/reformatted.

Details

Values of continent should be one of "Africa", "Antarctica", "Asia", "Europe", "North America", "Oceania" or "South America".

countryCode should be supplied according to the ISO 3166-1 ALPHA-2 standard, as per TDWG advice. Examples of countryCode:

• AUS

• NZ

• BRA

Examples of locality:

• Bariloche, 25 km NNE via Ruta Nacional 40 (=Ruta 237)

• Queets Rainforest, Olympic National Park

See also

set_coordinates() for numeric spatial data.

Examples

df <- tibble::tibble(
  scientificName = c("Crinia Signifera", "Crinia Signifera", "Litoria peronii"),
  latitude = c(-35.27, -35.24, -35.83),
  longitude = c(149.33, 149.34, 149.34),
  eventDate = c("2010-10-14", "2010-10-14", "2010-10-14"),
  countryCode = c("AU", "AU", "AU"),
  state = c("New South Wales", "New South Wales", "New South Wales"),
  locality = c("Melville Caves", "Melville Caves", "Bryans Swamp about 3km away")
)

# Reformat columns to Darwin Core Standard terms
df |>
  set_locality(
    countryCode = countryCode,
    stateProvince = state,
    locality = locality
  )
#> ⠙ Checking 3 columns: countryCode, locality, and stateProvince
#> ⠹ Checking 3 columns: countryCode, locality, and stateProvince
#> ✔ Checking 3 columns: countryCode, locality, and stateProvince [935ms]
#> 
#> # A tibble: 3 × 7
#>   scientificName latitude longitude eventDate countryCode locality stateProvince
#>   <chr>             <dbl>     <dbl> <chr>     <chr>       <chr>    <chr>        
#> 1 Crinia Signif…    -35.3      149. 2010-10-… AU          Melvill… New South Wa…
#> 2 Crinia Signif…    -35.2      149. 2010-10-… AU          Melvill… New South Wa…
#> 3 Litoria peron…    -35.8      149. 2010-10-… AU          Bryans … New South Wa…

# Columns with valid Darwin Core terms as names are automatically detected
# and checked. This will do the same as above.
df |>
  set_locality(
    stateProvince = state
  )
#> ⠙ Checking 3 columns: countryCode, locality, and stateProvince
#> ✔ Checking 3 columns: countryCode, locality, and stateProvince [918ms]
#> 
#> # A tibble: 3 × 7
#>   scientificName latitude longitude eventDate countryCode locality stateProvince
#>   <chr>             <dbl>     <dbl> <chr>     <chr>       <chr>    <chr>        
#> 1 Crinia Signif…    -35.3      149. 2010-10-… AU          Melvill… New South Wa…
#> 2 Crinia Signif…    -35.2      149. 2010-10-… AU          Melvill… New South Wa…
#> 3 Litoria peron…    -35.8      149. 2010-10-… AU          Bryans … New South Wa…