galah

Travis-CI Build Status codecov CRAN Status CRAN Downloads


galah is an R interface to biodiversity data hosted by the Atlas of Living Australia (ALA). It enables users to locate and download species occurrence records (observations, specimens, eDNA records, etc.), taxonomic information, or associated media such as images or sounds, and to restrict their queries to particular taxa or locations. Users can specify which columns are returned by a query, or restrict their results to occurrences that meet particular data-quality criteria. All functions return a data.frame as their standard format, except ala_taxonomy which returns tree consisting of Node objects using the data.tree package.

The ALA is an aggregator of biodiversity data, focussed primarily on observations of individual life forms. Like the Global Biodiversity Information Facility (GBIF), the basic unit of data at ALA is an occurrence record, based on the ‘Darwin Core’ data standard.

The galah package is named for the bird of the same name (Eolophus roseicapilla), a widely-distributed endemic Australian species.

The galah logo was designed by Ian Brennan.

If you have any comments, questions or suggestions, please contact us.

Getting started

Installation

Install from CRAN:

install.packages("galah")

Install the development version from GitHub:

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

On Linux you will first need to ensure that libcurl and v8 (version <= 3.15) are installed on your system — e.g. on Ubuntu/Debian, open a terminal and do:

sudo apt-get install libcurl4-openssl-dev libv8-3.14-dev

galah depends on sf for location-based searches. To install galah you will need to make sure your system meets the sf system requirements, as specified here

Citations

To generate a citation for the package version you are using, you can run

citation(package = "galah")

If you’re using occurrence data downloaded through galah in a publication, please generate a DOI and cite it. To request a DOI for a download of ocurrence record, set mint_doi = TRUE in a call to ala_occurrences(). To generate a citation for the downloaded occurrence records, pass the data.frame generated to ala_citation().

occ <- ala_occurrences(..., mint_doi = TRUE)
doi <- attr(occ, "doi")
cit <- ala_citation(occ)

Contributing

Running tests

Tests should be run locally on any new code changes before pushing to GitHub. When code is pushed, tests will also be run on Travis CI. The results of the remote tests are available here.

# All tests
devtools::test()

# Individual files
devtools::test_file()

Writing tests

Tests are in the tests/testthat/ folder. codecov gives the percentage of code covered by tests. Ideally this should stay above 85%.

Updating the pkgdown site

The package homepage is rebuilt and updated automatically whenever code is pushed/merged into the master branch.

Other Living Atlases

galah supports retrieving data from a number of other Living Atlases; how to do this is explained in the international atlases vignette.