Skip to contents

Start building a data query

Source: R/galah_call.R, R/print.R
galah_call.Rd

To download data from the ALA (or another atlas), one must construct a data query. This query tells the atlas API what data to download and return, as well as how it should be filtered.

Usage

galah_call(
  identify = NULL,
  filter = NULL,
  select = NULL,
  geolocate = NULL,
  data_profile = NULL,
  group_by = NULL,
  down_to = NULL,
  ...
)

# S3 method for data_request
print(x, ...)

Arguments

identify

data.frame: generated by a call to galah_identify()

filter

data.frame: generated by a call to select_filters()

select

data.frame: generated by a call to galah_select()

geolocate

string: generated by a call to galah_geolocate()

data_profile

string: generated by a call to galah_apply_profile()

group_by

data.frame: generated by a call to galah_group_by()

down_to

data.frame: generated by a call to galah_down_to()

...

other function-specific request parameters

x

an object of class data_request

Value

An object of class data_request.

Details

The galah package enables users to construct their data queries using piping syntax (i.e., %>% from magrittr, or |> from base).

Start a query with galah_call(). Pipe functions like galah_identify(), galah_filter(), [galah_select()], and galah_group_by() to narrow your query and specify filters. Finish a query with an atlas_ function to identify which type of data is downloaded (i.e., atlas_occurrences(), atlas_counts(), atlas_species(), atlas_taxonomy() or atlas_media()).

Using galah_call() with pipes allows you to build & filter a query to download data in the same way that you would wrangle data with dplyr and the tidyverse.

Examples

# Begin your query with `galah_call()`, then pipe using `%>%` or `|>`

# Get number of records of *Aves* from 2001 to 2004 by year
galah_call() |>
  galah_identify("Aves") |>
  galah_filter(year > 2000 & year < 2005) |>
  galah_group_by() |>
  atlas_counts()
#> # A tibble: 1 × 1
#>   count
#>   <dbl>
#> 1     0
  
# Get information for all species in *Cacatuidae* family
galah_call() |>
  galah_identify("Cacatuidae") |>
  atlas_species()
#> # A tibble: 14 × 10
#>    kingdom  phylum   class order     family genus species author speci…¹ verna…²
#>    <chr>    <chr>    <chr> <chr>     <chr>  <chr> <chr>   <chr>  <chr>   <chr>  
#>  1 Animalia Chordata Aves  Psittaci… Cacat… Eolo… Eoloph… (Viei… https:… Galah  
#>  2 Animalia Chordata Aves  Psittaci… Cacat… Caca… Cacatu… (Lath… https:… Sulphu…
#>  3 Animalia Chordata Aves  Psittaci… Cacat… Caca… Cacatu… Gould… https:… Little…
#>  4 Animalia Chordata Aves  Psittaci… Cacat… Zanda Zanda … (Shaw… https:… Yellow…
#>  5 Animalia Chordata Aves  Psittaci… Cacat… Caca… Cacatu… (Kuhl… https:… Long-b…
#>  6 Animalia Chordata Aves  Psittaci… Cacat… Call… Calloc… (Gran… https:… Gang-g…
#>  7 Animalia Chordata Aves  Psittaci… Cacat… Caly… Calypt… (Lath… https:… Red-ta…
#>  8 Animalia Chordata Aves  Psittaci… Cacat… Nymp… Nymphi… (Kerr… https:… Cockat…
#>  9 Animalia Chordata Aves  Psittaci… Cacat… Caly… Calypt… (Temm… https:… Glossy…
#> 10 Animalia Chordata Aves  Psittaci… Cacat… Loph… Lophoc… (Vigo… https:… Major …
#> 11 Animalia Chordata Aves  Psittaci… Cacat… Zanda Zanda … Lear,… https:… Baudin…
#> 12 Animalia Chordata Aves  Psittaci… Cacat… Caca… Cacatu… (Goul… https:… Wester…
#> 13 Animalia Chordata Aves  Psittaci… Cacat… Prob… Probos… (Gmel… https:… Palm C…
#> 14 Animalia Chordata Aves  Psittaci… Cacat… Zanda Zanda … Carna… https:… Short-…
#> # … with abbreviated variable names ¹​species_guid, ²​vernacular_name
if (FALSE) { 
# Download records of genus *Eolophus* from 2001 to 2004
galah_config(email = "your-email@email.com")

galah_call() |>
  galah_identify("Eolophus") |>
  galah_filter(year > 2000 & year < 2005) |>
  atlas_occurrences()
}