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)

Configuration

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

show_all(atlases)

## # A tibble: 10 × 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://biodiversityat…
##  3 Brazil         Sistemas de Informações sobre a Biodiversidade Brasileira               SiBBr   https://sibbr.gov.br   
##  4 France         Portail français d'accès aux données d'observation sur les espèces      OpenObs https://openobs.mnhn.fr
##  5 Global         Global Biodiversity Information Facility                                GBIF    https://gbif.org       
##  6 Guatemala      Sistema Nacional de Información sobre Diversidad Biológica de Guatemala SNIBgt  https://snib.conap.gob…
##  7 Portugal       GBIF Portugal                                                           GBIF.pt https://www.gbif.pt    
##  8 Spain          GBIF Spain                                                              GBIF.es https://gbif.es        
##  9 Sweden         Swedish Biodiversity Data Infrastructure                                SBDI    https://biodiversityda…
## 10 United Kingdom National Biodiversity Network                                           NBN     https://nbn.org.uk

Use galah_config() to set the node organisation using its region, name, or acronym. Once set, galah will automatically populate the server configuration for your selected GBIF node. To download occurrence records from your chosen GBIF node, you will need to register an account with them (using their website), then provide your registration email to galah. To download from GBIF, you will need to provide the email, username, and password.

galah_config(atlas = "GBIF",
             username = "user1",
             email = "email@email.com",
             password = "my_password")

You can find a full list of configuration options by running ?galah_config.

Basic syntax

The standard method to construct queries in {galah} is via piped functions. Pipes in galah start with the galah_call() function, and typically end with collect(), though collapse() and compute() are also supported. The development team use the base pipe by default (|>), but the {magrittr} pipe (%>%) should work too.

galah_config(atlas = "ALA",
             verbose = FALSE)
galah_call() |>
  count() |>
  collect()

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

To pass more complex queries, you can use additional {dplyr} functions such as filter(), select(), and group_by().

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

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

Each GBIF node allows you to query using their own set of in-built fields. You can investigate which fields are available using show_all() and search_all():

search_all(fields, "australian states")

## # A tibble: 2 × 3
##   id     description                            type  
##   <chr>  <chr>                                  <chr> 
## 1 cl2013 ASGS Australian States and Territories fields
## 2 cl22   Australian States and Territories      fields

Taxonomic searches

To narrow your search to a particular taxonomic group, use 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_type kingdom phylum class issues
##   <chr>       <chr>           <chr>                                          <chr> <chr>      <chr>   <chr>  <chr> <chr> 
## 1 reptilia    REPTILIA        https://biodiversity.org.au/afd/taxa/682e1228… class exactMatch Animal… Chord… Rept… noIss…

galah_call() |>
  identify("reptilia") |> 
  filter(year >= 2020) |> 
  count() |>
  collect()

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

If you want to query something other than the number of records, modify the type argument in galah_call(). Here we’ll query the number of species:

galah_call(type = "species") |>
  identify("reptilia") |> 
  filter(year >= 2020) |> 
  count() |>
  collect()

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

Download

To download records—rather than find how many records are available—simply remove the count() function from your pipe.

result <- galah_call() |>
  identify("Litoria") |>
  filter(year >= 2020, cl22 == "Tasmania") |>
  select(basisOfRecord, group = "basic") |>
  collect()

## Retrying in 1 seconds.

result |> head()

## # A tibble: 6 × 9
##   recordID            scientificName taxonConceptID decimalLatitude decimalLongitude eventDate           occurrenceStatus
##   <chr>               <chr>          <chr>                    <dbl>            <dbl> <dttm>              <chr>           
## 1 00052544-d943-42e9… Litoria ewing… https://biodi…           -42.9             147. 2022-09-19 00:00:00 PRESENT         
## 2 00168ca6-84d0-4af1… Litoria ranif… https://biodi…           -41.2             146. 2023-12-21 10:20:19 PRESENT         
## 3 001a43fe-8586-4064… Litoria ewing… https://biodi…           -43.0             147. 2021-08-07 00:00:00 PRESENT         
## 4 00250163-ec50-4eda… Litoria ranif… https://biodi…           -41.2             147. 2023-08-23 11:49:28 PRESENT         
## 5 003e0f63-9f95-4af9… Litoria ewing… https://biodi…           -42.9             148. 2022-12-24 06:27:00 PRESENT         
## 6 0070521f-bb45-46fb… Litoria ewing… https://biodi…           -43.1             147. 2023-12-20 14:29:23 PRESENT         
## # ℹ 2 more variables: dataResourceName <chr>, basisOfRecord <chr>

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