Occurrence records from FinBIF

William K. Morris

The core purpose of {finbif} is accessing occurrence data stored in the FinBIF database. Occurrence data can be retrieved from FinBIF with the function finbif_occurrence(). Without any arguments specified finbif_occurrence() will retrieve the latest 10 occurrence records from FinBIF.

finbif_occurrence()

Click to show/hide output. 


#> Records downloaded: 10
#> Records available: 34700400
#> A data.frame [10 x 12]
#>    record_id     scientific_name abundance lat_wgs84 lon_wgs84           date_time
#> 1      9#111      Aglais urticae  16        60.37011  24.72526 2020-04-22 15:00:00
#> 2       8#19               Loxia  1         61.13068  21.65088 2020-04-22 07:20:00
#> 3        8#4    Poecile montanus  1         61.13068  21.65088 2020-04-22 07:20:00
#> 4       8#16      Turdus iliacus  1         61.13068  21.65088 2020-04-22 07:20:00
#> 5        8#7  Erithacus rubecula  1         61.13068  21.65088 2020-04-22 07:20:00
#> 6       8#13 Cyanistes caeruleus  1         61.13068  21.65088 2020-04-22 07:20:00
#> 7       8#10       Spinus spinus  3         61.13068  21.65088 2020-04-22 07:20:00
#> 8       7#13   Turdus philomelos  1         61.13305  21.65151 2020-04-22 06:30:00
#> 9       7#25     Tringa ochropus  1         61.13305  21.65151 2020-04-22 06:30:00
#> 10       7#7 Garrulus glandarius  1         61.13305  21.65151 2020-04-22 06:30:00
#> ...with 0 more records and 6 more variables:
#> coordinates_uncertainty, any_issues, requires_verification, requires_identification,
#> record_reliability, record_quality


The print method for the resulting finbif_occ object will display the number of records downloaded, the total number of records available, a data summary including up to 10 rows of some core record variables (when available), the number of remaining records and variables, as well as the names of additional variables.

Darwin Core Variables

You can switch from the default variable names to Darwin Core style names by setting dwc = TRUE.

colnames(finbif_occurrence(dwc = TRUE))
#>  [1] "occurrenceID"                  "scientificName"                "individualCount"              
#>  [4] "decimalLatitude"               "decimalLongitude"              "eventDateTime"                
#>  [7] "coordinateUncertaintyInMeters" "hasIssues"                     "requires_verification"        
#> [10] "requiresIdentification"        "occurrenceReliability"         "occurrenceQuality"

The functions to_dwc() and to_native() can be used to translate variable names to and from Darwin Core style and {finbif}’s native variable names style.

Choosing taxa

You can limit the records to certain taxa by specifying them as an argument.

finbif_occurrence("Cygnus cygnus")

Click to show/hide output.


Multiple taxa can be requested at once.

finbif_occurrence("Cygnus cygnus", "Cygnus olor")

Click to show/hide output.


You can also chose higher taxonomic groups and use common names (in English, Finnish and Swedish).

birds  <- finbif_occurrence("Birds")
linnut <- finbif_occurrence("Linnut")
faglar <- finbif_occurrence("Fåglar")

sapply(list(birds, linnut, faglar), nrow)
#> [1] 10 10 10

Request size

You can increase the number of records returned by using the n argument.

finbif_occurrence(n = 1001)

Click to show/hide output.


You can see how many records are available for a given request, without retrieving any records, by setting count_only = TRUE.

finbif_occurrence(count_only = TRUE)
#> [1] 34696846

Checking taxa

When you request occurrence records for specific taxa, by default, the taxon names are first checked against the FinBIF database. If any of the requested taxa are not found in the database you will receive a warning but the data will still be retrieved for the remaining taxa.

finbif_occurrence("Vulpes vulpes", "Moomin")

Click to show/hide output.


You can turn off taxon name pre-checking by setting the value of the check_taxa argument to FALSE.

finbif_occurrence("Vulpes vulpes", "Moomin", check_taxa = FALSE)

Click to show/hide output.


By setting the argument, on_check_fail to "error" (the default is "warn"), you can elevate the warnings to errors and the request will fail if any of the taxa are not found in the FinBIF database.

finbif_occurrence("Vulpes vulpes", "Moomin", on_check_fail = "error")
#> Error: Cannot find taxa: Moomin

This can be a useful strategy if you are using {finbif} non-interactively (in a script), and you do not want to proceed if any of your taxon names are wrong or misspelled.

Time & duration

The default behaviour of finbif_occurrence is to consolidate date and time data for occurrence recording events into a date_time variable. This can be turned off (which can speed up data processing time) by deselecting the date_time variable.

finbif_occurrence(select = "-date_time")

Click to show/hide output.


Timezone

Timezone input

The FinBIF database doesn’t currently store timezone information, so {finbif} makes assumptions about the appropriate timezone based on the time and location of the occurrence recording events to calculate date_time and duration. By default, a fast heuristic is used to determine the timezones. If you require greater accuracy (e.g., you are using data on the Finnish/Swedish border and daytime/nighttime hours are important), you can switch to more accurate, though slower, timezone calculation method.

Click to show/hide output.


Timezone output

The timezone of the calculated date_time variable is determined by the timezone of your operating system.

You can override this by setting the tzone argument to a different value.

Click to show/hide output.


Or set the global timezone option to set the timezone for the current session.

This may be advisable for reproducibility or when working with multiple systems.