Skip to contents

The atlas_ functions are used to return data from the atlas chosen using galah_config(). They are:

  • atlas_counts
  • atlas_occurrences
  • atlas_species
  • atlas_media
  • atlas_taxonomy

The final atlas_ function - atlas_citation - is unusual in that it does not return any new data. Instead it provides a citation for an existing dataset ( downloaded using atlas_occurrences) that has an associated DOI. The other functions are described below.

Record counts

atlas_counts() provides summary counts on records in the specified atlas, without needing to download all the records.

galah_config(atlas = "Australia")
# Total number of records in the ALA
atlas_counts()
## # A tibble: 1 × 1
##       count
##       <int>
## 1 132342396

In addition to the filter arguments, it has an optional group_by argument, which provides counts binned by the requested field.

## # A tibble: 11 × 2
##    kingdom       count
##    <chr>         <int>
##  1 Animalia  101442503
##  2 Plantae    26136825
##  3 Fungi       2293753
##  4 Chromista   1021828
##  5 Protista     352983
##  6 Bacteria     113118
##  7 Eukaryota      8826
##  8 Protozoa       4765
##  9 Archaea        4119
## 10 Virus          2307
## 11 Viroid          103

Species lists

A common use case of atlas data is to identify which species occur in a specified region, time period, or taxonomic group. atlas_species() is similar to search_taxa, in that it returns taxonomic information and unique identifiers in a tibble. It differs in not being able to return information on taxonomic levels other than the species; but also in being more flexible by supporting filtering:

species <- galah_call() |>
  galah_identify("Rodentia") |>
  galah_filter(stateProvince == "Northern Territory") |>
  atlas_species()
  
species |> head()
## # A tibble: 6 × 10
##   kingdom  phylum   class    order    family  genus        species                     author            species_guid    vernacular_name
##   <chr>    <chr>    <chr>    <chr>    <chr>   <chr>        <chr>                       <chr>             <chr>           <chr>          
## 1 Animalia Chordata Mammalia Rodentia Muridae Pseudomys    Pseudomys delicatulus       (Gould, 1842)     https://biodiv… Delicate Mouse 
## 2 Animalia Chordata Mammalia Rodentia Muridae Mesembriomys Mesembriomys gouldii        (J.E. Gray, 1843) https://biodiv… Black-footed T…
## 3 Animalia Chordata Mammalia Rodentia Muridae Zyzomys      Zyzomys argurus             (Thomas, 1889)    https://biodiv… Common Rock-rat
## 4 Animalia Chordata Mammalia Rodentia Muridae Pseudomys    Pseudomys hermannsburgensis (Waite, 1896)     https://biodiv… Sandy Inland M…
## 5 Animalia Chordata Mammalia Rodentia Muridae Melomys      Melomys burtoni             (Ramsay, 1887)    https://biodiv… Grassland Melo…
## 6 Animalia Chordata Mammalia Rodentia Muridae Notomys      Notomys alexis              Thomas, 1922      https://biodiv… Spinifex Hoppi…

Occurrence data

To download occurrence data you will need to specify your email in galah_config(). This email must be associated with an active ALA account. See more information in the config section

galah_config(email = "your_email@email.com", atlas = "Australia")

Download occurrence records for Eolophus roseicapilla

occ <- galah_call() |>
  galah_identify("Eolophus roseicapilla") |>
  galah_filter(
    stateProvince == "Australian Capital Territory",
    year >= 2010,
    profile = "ALA"
  ) |>
  galah_select(institutionID, group = "basic") |>
  atlas_occurrences()
## Retrying in 1 seconds.
## Retrying in 2 seconds.
## Retrying in 4 seconds.
## Retrying in 8 seconds.
occ |> head()
## # A tibble: 6 × 9
##   recordID          scientificName taxonConceptID decimalLatitude decimalLongitude eventDate           occurrenceStatus dataResourceName
##   <chr>             <chr>          <chr>                    <dbl>            <dbl> <dttm>              <chr>            <chr>           
## 1 0000a928-d756-42… Eolophus rose… https://biodi…           -35.6             149. 2017-04-19 09:11:00 PRESENT          eBird Australia 
## 2 0001bc78-d2e9-48… Eolophus rose… https://biodi…           -35.2             149. 2019-08-13 15:13:00 PRESENT          eBird Australia 
## 3 0002064f-08ea-42… Eolophus rose… https://biodi…           -35.3             149. 2014-03-16 06:48:00 PRESENT          eBird Australia 
## 4 00022dd2-9f85-48… Eolophus rose… https://biodi…           -35.3             149. 2022-05-08 08:20:00 PRESENT          eBird Australia 
## 5 0002cc35-8d5a-4d… Eolophus rose… https://biodi…           -35.3             149. 2015-11-01 08:00:00 PRESENT          eBird Australia 
## 6 00030a8c-082f-44… Eolophus rose… https://biodi…           -35.3             149. 2022-01-06 11:47:00 PRESENT          eBird Australia 
## # ℹ 1 more variable: institutionID <lgl>

Media metadata

In addition to text data describing individual occurrences and their attributes, ALA stores images, sounds and videos associated with a given record. Metadata on these records can be downloaded to R using atlas_media() and the same set of filters as the other data download functions.

media_data <- galah_call() |>
  galah_identify("Eolophus roseicapilla") |>
  galah_filter(
    year == 2020,
    cl22 == "Australian Capital Territory") |>
  atlas_media()
## Retrying in 1 seconds.
## Retrying in 2 seconds.
## Retrying in 4 seconds.
media_data |> head()
## # A tibble: 6 × 19
##   media_id recordID scientificName taxonConceptID decimalLatitude decimalLongitude eventDate           occurrenceStatus dataResourceName
##   <chr>    <chr>    <chr>          <chr>                    <dbl>            <dbl> <dttm>              <chr>            <chr>           
## 1 ff8322d… 003a192… Eolophus rose… https://biodi…           -35.3             149. 2020-09-12 06:11:00 PRESENT          iNaturalist Aus…
## 2 c66fc81… 015ee7c… Eolophus rose… https://biodi…           -35.4             149. 2020-08-09 05:11:00 PRESENT          iNaturalist Aus…
## 3 fe6d7b9… 05e86b7… Eolophus rose… https://biodi…           -35.4             149. 2020-11-13 22:29:00 PRESENT          NatureMapr      
## 4 2f4d32c… 063bb0f… Eolophus rose… https://biodi…           -35.6             149. 2020-08-04 01:50:00 PRESENT          iNaturalist Aus…
## 5 7340741… 063bb0f… Eolophus rose… https://biodi…           -35.6             149. 2020-08-04 01:50:00 PRESENT          iNaturalist Aus…
## 6 89171c4… 063bb0f… Eolophus rose… https://biodi…           -35.6             149. 2020-08-04 01:50:00 PRESENT          iNaturalist Aus…
## # ℹ 10 more variables: multimedia <chr>, images <chr>, videos <lgl>, sounds <lgl>, creator <chr>, license <chr>, mimetype <chr>,
## #   width <int>, height <int>, image_url <chr>

To actually download the media files to your computer, use [collect_media()].

Taxonomic trees

atlas_taxonomy provides a way to build taxonomic trees from one clade down to another using each service’s internal taxonomy. Specify which taxonomic level your tree will go down to with galah_filter() using the rank argument.

galah_call() |>
  galah_identify("chordata") |>
  galah_filter(rank == class) |>
  atlas_taxonomy()
## # A tibble: 19 × 4
##    name            rank      parent_taxon_concept_id                                                   taxon_concept_id                 
##    <chr>           <chr>     <chr>                                                                     <chr>                            
##  1 Chordata        phylum    <NA>                                                                      https://biodiversity.org.au/afd/…
##  2 Cephalochordata subphylum https://biodiversity.org.au/afd/taxa/065f1da4-53cd-40b8-a396-80fa5c74dedd https://biodiversity.org.au/afd/…
##  3 Tunicata        subphylum https://biodiversity.org.au/afd/taxa/065f1da4-53cd-40b8-a396-80fa5c74dedd https://biodiversity.org.au/afd/…
##  4 Appendicularia  class     https://biodiversity.org.au/afd/taxa/1c20ed62-d918-4e42-b625-8b86d533cc51 https://biodiversity.org.au/afd/…
##  5 Ascidiacea      class     https://biodiversity.org.au/afd/taxa/1c20ed62-d918-4e42-b625-8b86d533cc51 https://biodiversity.org.au/afd/…
##  6 Thaliacea       class     https://biodiversity.org.au/afd/taxa/1c20ed62-d918-4e42-b625-8b86d533cc51 https://biodiversity.org.au/afd/…
##  7 Vertebrata      subphylum https://biodiversity.org.au/afd/taxa/065f1da4-53cd-40b8-a396-80fa5c74dedd https://biodiversity.org.au/afd/…
##  8 Agnatha         informal  https://biodiversity.org.au/afd/taxa/5d6076b1-b7c7-487f-9d61-0fea0111cc7e https://biodiversity.org.au/afd/…
##  9 Myxini          informal  https://biodiversity.org.au/afd/taxa/66db22c8-891d-4b16-a1a2-b66feaeaa3e0 https://biodiversity.org.au/afd/…
## 10 Petromyzontida  informal  https://biodiversity.org.au/afd/taxa/66db22c8-891d-4b16-a1a2-b66feaeaa3e0 https://biodiversity.org.au/afd/…
## 11 Gnathostomata   informal  https://biodiversity.org.au/afd/taxa/5d6076b1-b7c7-487f-9d61-0fea0111cc7e https://biodiversity.org.au/afd/…
## 12 Amphibia        class     https://biodiversity.org.au/afd/taxa/ef5515fd-a0a2-4e16-b61a-0f19f8900f76 https://biodiversity.org.au/afd/…
## 13 Aves            class     https://biodiversity.org.au/afd/taxa/ef5515fd-a0a2-4e16-b61a-0f19f8900f76 https://biodiversity.org.au/afd/…
## 14 Mammalia        class     https://biodiversity.org.au/afd/taxa/ef5515fd-a0a2-4e16-b61a-0f19f8900f76 https://biodiversity.org.au/afd/…
## 15 Pisces          informal  https://biodiversity.org.au/afd/taxa/ef5515fd-a0a2-4e16-b61a-0f19f8900f76 https://biodiversity.org.au/afd/…
## 16 Actinopterygii  class     https://biodiversity.org.au/afd/taxa/e22efeb4-2cb5-4250-8d71-61c48bdaa051 https://biodiversity.org.au/afd/…
## 17 Chondrichthyes  class     https://biodiversity.org.au/afd/taxa/e22efeb4-2cb5-4250-8d71-61c48bdaa051 https://biodiversity.org.au/afd/…
## 18 Sarcopterygii   class     https://biodiversity.org.au/afd/taxa/e22efeb4-2cb5-4250-8d71-61c48bdaa051 https://biodiversity.org.au/afd/…
## 19 Reptilia        class     https://biodiversity.org.au/afd/taxa/ef5515fd-a0a2-4e16-b61a-0f19f8900f76 https://biodiversity.org.au/afd/…

Configuring galah

Various aspects of the galah package can be customized.

Email

To download occurrence records, you will need to provide an email address registered with the service that you want to use (e.g. for the ALA you can create an account here). Once an email is registered, it should be stored in the config:

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

Setting your directory

By default, galah stores downloads in a temporary folder, meaning that the local files are automatically deleted when the R session is ended. This behaviour can be altered so that downloaded files are preserved by setting the directory to a non-temporary location.

galah_config(directory = "example/dir")

Setting the download reason

ALA requires that you provide a reason when downloading occurrence data (via the galah atlas_occurrences() function). The reason is set as “scientific research” by default, but you can change this using galah_config(). See show_all_reasons() for valid download reasons.

galah_config(download_reason_id = your_reason_id)

Debugging

If things aren’t working as expected, more detail (particularly about web requests and caching behaviour) can be obtained by setting the verbose configuration option:

galah_config(verbose = TRUE)