# Quick start guide

#### Martin Westgate & Dax Kellie

#### 2023-01-18

# About

`galah` is an R interface to biodiversity data hosted by the ‘living atlases’; a set of organisations that share a common codebase, and act as nodes of the Global Biodiversity Information Facility (GBIF). These organisations collate and store observations of individual life forms, using the ‘Darwin Core’ data standard.

`galah` enables users to locate and download species observations, taxonomic information, record counts, or associated media such as images or sounds. Users can restrict their queries to particular taxa or locations by specifying which columns and rows are returned by a query, or by restricting their results to observations that meet particular quality-control criteria. With a few minor exceptions, all functions return a `tibble` as their standard format.

# Installation

To install from CRAN:

    install.packages("galah")

Or install the development version from GitHub:

    install.packages("remotes")
    remotes::install_github("AtlasOfLivingAustralia/galah")

Load the package

    library(galah)

# Choosing an atlas

By default, `galah` downloads information from the Atlas of Living Australia (ALA). To show the full list of Atlases currently supported by `galah`, use `show_all(atlases)`.

    show_all(atlases)

    ## # A tibble: 11 × 4
    ##    region         institution                                                             acronym url
    ##    <chr>          <chr>                                                                   <chr>   <chr>
    ##  1 Australia      Atlas of Living Australia                                               ALA     https://www.ala.org.au
    ##  2 Austria        Biodiversitäts-Atlas Österreich                                         BAO     https://biodiversityatlas.at
    ##  3 Brazil         Sistemas de Informações sobre a Biodiversidade Brasileira               SiBBr   https://sibbr.gov.br
    ##  4 Estonia        eElurikkus                                                              <NA>    https://elurikkus.ee
    ##  5 France         Portail français d'accès aux données d'observation sur les espèces      OpenObs https://openobs.mnhn.fr/
    ##  6 Global         Global Biodiversity Information Facility                                GBIF    https://gbif.org
    ##  7 Guatemala      Sistema Nacional de Información sobre Diversidad Biológica de Guatemala SNIBgt  https://snib.conap.gob.gt
    ##  8 Portugal       GBIF Portugal                                                           GBIF.pt https://www.gbif.pt
    ##  9 Spain          GBIF Spain                                                              GBIF.es https://www.gbif.es
    ## 10 Sweden         Swedish Biodiversity Data Infrastructure                                SBDI    https://biodiversitydata.se
    ## 11 United Kingdom National Biodiversity Network                                           NBN     https://nbn.org.uk

Use `galah_config()` to set the Atlas to use. This will automatically populate the server configuration for your selected Atlas. By default, the atlas is Australia.

    galah_config(atlas = "United Kingdom")

# Building queries

Functions that return data from the chosen atlas have the prefix `atlas_`; e.g. to find the total number of records in the atlas, use:

    galah_config(atlas = "ALA")
    atlas_counts()

    ## # A tibble: 1 × 1
    ##       count
    ##       <int>
    ## 1 113038010

To pass more complex queries, start with the `galah_call()` function and pipe additional arguments to modify the query. modifying functions have a `galah_` prefix and support non-standard evaluation (NSE).

    galah_call() |>
      galah_filter(year >= 2020) |>
      atlas_counts()

    ## # A tibble: 1 × 1
    ##      count
    ##      <int>
    ## 1 15150011

Alternatively, you can use a subset of `dplyr` verbs to pipe your queries, assuming you start with `galah_call()`.

    galah_call() |>
      filter(year >= 2020) |>
      group_by(year) |>
      count()

    ## # A tibble: 4 × 2
    ##   year    count
    ##   <chr>   <int>
    ## 1 2021  7155750
    ## 2 2020  6419193
    ## 3 2022  1547173
    ## 4 2023    27895

To narrow the search to a particular taxonomic group, use `galah_identify()` or `identify`. Note that this function only accepts scientific names and is not case sensitive. It’s good practice to first use `search_taxa()` to check that the taxa you provide returns the correct taxonomic results.

    search_taxa("reptilia") # Check whether taxonomic info is correct

    ## # A tibble: 1 × 9
    ##   search_term scientific_name taxon_concept_id                                                    rank  match…¹ kingdom phylum class issues
    ##   <chr>       <chr>           <chr>                                                               <chr> <chr>   <chr>   <chr>  <chr> <chr>
    ## 1 reptilia    REPTILIA        https://biodiversity.org.au/afd/taxa/682e1228-5b3c-45ff-833b-550ef… class exactM… Animal… Chord… Rept… noIss…
    ## # … with abbreviated variable name ¹​match_type

    galah_call() |>
      galah_filter(year >= 2020) |>
      galah_identify("reptilia") |>
      atlas_counts()

    ## # A tibble: 1 × 1
    ##    count
    ##    <int>
    ## 1 101979

# Downloading records

The most common use case for `galah` is to download ‘occurrence’ records; observations of plants or animals made by contributors to the atlas. To download, first register with the relevant atlas, then provide your registration email. For GBIF queries, you will need to provide the email, username, and password that you have registered with GBIF.

    galah_config(email = "email@email.com")

Then you can customise records you require and query the atlas in question:

    result <- galah_call() |>
      galah_identify("Litoria") |>
      galah_filter(year >= 2020, cl22 == "Tasmania") |>
      galah_select(basisOfRecord, group = "basic") |>
      atlas_occurrences()

    result |> head()

    ## # A tibble: 6 × 9
    ##   decimalLatitude decimalLongitude eventDate           scientificName    taxonConceptID                     recor…¹ dataR…² occur…³ basis…⁴
    ##             <dbl>            <dbl> <dttm>              <chr>             <chr>                              <chr>   <chr>   <chr>   <chr>
    ## 1           -43.4             147. 2020-09-04 14:00:00 Litoria ewingii   https://biodiversity.org.au/afd/t… e8045b… FrogID  PRESENT HUMAN_…
    ## 2           -43.4             146. 2020-01-01 13:00:00 Litoria ewingii   https://biodiversity.org.au/afd/t… 44187a… FrogID  PRESENT HUMAN_…
    ## 3           -43.4             146. 2020-01-01 13:00:00 Litoria ewingii   https://biodiversity.org.au/afd/t… bc34a7… FrogID  PRESENT HUMAN_…
    ## 4           -43.4             146. 2020-01-01 13:00:00 Litoria ewingii   https://biodiversity.org.au/afd/t… ca4707… FrogID  PRESENT HUMAN_…
    ## 5           -43.4             146. 2020-01-01 13:00:00 Litoria burrowsae https://biodiversity.org.au/afd/t… 9c71f5… FrogID  PRESENT HUMAN_…
    ## 6           -43.4             146. 2020-01-01 13:00:00 Litoria ewingii   https://biodiversity.org.au/afd/t… 4bbaad… FrogID  PRESENT HUMAN_…
    ## # … with abbreviated variable names ¹​recordID, ²​dataResourceName, ³​occurrenceStatus, ⁴​basisOfRecord

Check out our other vignettes for more detail on how to use these functions.