Read an Observation.org export

Imports a SQLite, CSV or Excel export into an analysis-ready obs_df tibble. Column names are canonical English identifiers. CSV and Excel headers from Observation.org are always English (validation status, life stage, ...); only the values follow the export language. Coded fields are returned as a readable label plus a stable *_code column.

Usage

obs_read(
  path,
  species = NULL,
  group = NULL,
  date = NULL,
  date_start = NULL,
  date_end = NULL,
  country = NULL,
  validation = NULL,
  bbox = NULL,
  polygon = NULL,
  locale = "en",
  collect = 1e+05,
  limit = NULL
)

Arguments

path: Path to a .sqlite / .db, .csv or .xlsx export.
species: Scientific or common name (partial match).
group: Species group name ("Birds", "Aves").
date: Length-2 vector c(start, end) as "YYYY-MM-DD", or a single date. Overrides date_start / date_end when supplied.
date_start, date_end: Date bounds.
country: ISO-2 code ("ES") or country name.
validation: Status codes ("A"), labels, or "validated" for A/J/P.
bbox: Bounding box c(xmin, ymin, xmax, ymax).
polygon: Area to keep. WKT, GeoJSON (string or file path), or an sf polygon. Points are tested against the polygon; SQLite first uses the polygon bounding box. Requires sf.
locale: Label language. "en" (default). Spanish, Dutch, French and German ship with the package ("es", "nl", "fr", "de"). Any other Observation.org language code is fetched from the API when you are online and then cached. Does not rename columns.
collect: How many SQLite rows to load into memory. A number is the maximum to collect: above it, return a lazy obs_df. Default 100000. TRUE always collects; FALSE never collects (call obs_collect() later). CSV, Excel and polygon filters always collect.
limit: Maximum rows.

Value

An obs_df tibble (or a lazy obs_df for large SQLite files).

Details

Choose the label language per call with locale. Labels are fixed when the table is read, so two tables can use different languages in the same session. English, Spanish, Dutch, French and German ship with the package. Any other Observation.org language code is fetched from the API when you are online, then cached. Column names never change.

polygon keeps points inside a WKT or GeoJSON area (or an sf polygon). That needs sf and always collects into memory. See vignette("labels") and vignette("spatial-filters") for worked examples.

SQLite files may include mixed counts (several sexes, life stages or activities in one record). Those rows have is_multiple = TRUE and a details cell such as "10 Male; 7 Female". Call obs_expand() before counting individuals by sex or life stage; maps should keep the compact table so each observation is still one point. CSV and Excel exports do not carry that breakdown, so is_multiple is FALSE and details is NA.

Labels come from dictionaries shipped with the package. Call obs_update_dictionaries() to refresh them from the Observation.org API when you are online.

Call obs_anonymise() before sharing a table: it replaces observer ids and names with a one-way hash. The example files from obs_example_db() are already anonymised.

Zero matching rows warn instead of failing. If species looks wrong, call obs_species() to check the name against the public Observation.org catalogue (that needs a network connection; this function does not).

Examples

db <- obs_example_db()
sparrows <- obs_read(db, species = "Passer domesticus")
obs_summary(sparrows)
#> 
#> ── Observation summary ─────────────────────────────────────────────────────────
#> Observations: 1113
#> Validated (A/J/P): 740 (66.5%)
#> Species: 2
#> Date range: 2020-01-01 to 2021-01-01
#> Multiple observations: 13
#> 
#> ── Validation ──
#> 
#>                       validation   n
#>  accepted (automatic validation) 729
#>                          unknown 372
#>         accepted (with evidence)  11
#>        cannot be validated (yet)   1
#> ── Sex (individuals) ──
#> 
#>          sex    n
#>  Unspecified 7579
#>         Male  125
#>       Female   67
#> ── Life stage (individuals) ──
#> 
#>      life_stage    n
#>         unknown 7274
#>           adult  468
#>  adult breeding   18
#>   second summer    7
#>        juvenile    3
#>         deviant    1
#> ── Species groups ──
#> 
#>  species_group    n
#>          Birds 1113

nl <- obs_read(db, locale = "nl")
unique(nl$validation)
#> [1] "onbekend"                            
#> [2] "goedgekeurd (automatische validatie)"
#> [3] "goedgekeurd (met bewijs)"            
#> [4] "goedgekeurd (aannemelijk)"           
#> [5] "(nog) niet te beoordelen"            

if (FALSE) { # \dontrun{
park <- "POLYGON ((-6.1 37.3, -5.8 37.3, -5.8 37.5, -6.1 37.5, -6.1 37.3))"
inside <- obs_read(db, polygon = park)
obs_map(inside, polygon = park, basemap = "outline")

obs_read(db, locale = "pt")
} # }

Usage

Arguments

Value

Details

See also

Examples