ebirdst (version 3.2022.3)

ebirdst_download_status: Download eBird Status Data Products

Description

Download eBird Status Data Products for a single species, or for an example species. Downloading Status and Trends data requires an access key, consult set_ebirdst_access_key() for instructions on how to obtain and store this key. The example data consist of the results for Yellow-bellied Sapsucker subset to Michigan and are much smaller than the full dataset, making these data quicker to download and process. Only the low resolution (27 km) data are available for the example data. In addition, the example data are accessible without an access key.

Usage

ebirdst_download_status(
  species,
  path = ebirdst_data_dir(),
  download_abundance = TRUE,
  download_occurrence = FALSE,
  download_count = FALSE,
  download_ranges = FALSE,
  download_regional = FALSE,
  download_pis = FALSE,
  download_ppms = FALSE,
  download_all = FALSE,
  pattern = NULL,
  dry_run = FALSE,
  force = FALSE,
  show_progress = TRUE
)

Value

Path to the folder containing the downloaded data package for the given species. If dry_run = TRUE a list of files to download will be returned.

Arguments

species

character; a single species given as a scientific name, common name or six-letter species code (e.g. "woothr"). The full list of valid species is in the ebirdst_runs data frame included in this package. To download the example dataset, use "yebsap-example".

path

character; directory to download the data to. All downloaded files will be placed in a sub-directory of this directory named for the data version year, e.g. "2020" for the 2020 Status Data Products. Each species' data package will then appear in a directory named with the eBird species code. Defaults to a persistent data directory, which can be found by calling ebirdst_data_dir().

download_abundance

whether to download estimates of abundance and proportion of population.

download_occurrence

logical; whether to download estimates of occurrence.

download_count

logical; whether to download estimates of count.

download_ranges

logical; whether to download the range polygons.

download_regional

logical; whether to download the regional summary stats, e.g. percent of population in regions.

download_pis

logical; whether to download spatial estimates of predictor importance.

download_ppms

logical; whether to download spatial predictive performance metrics.

download_all

logical; download all files in the data package. Equivalent to setting all the download_ arguments to TRUE.

pattern

character; regular expression pattern to supply to str_detect() to filter files to download. This filter will be applied in addition to any of the download_ arguments. Note that some files are mandatory and will always be downloaded.

dry_run

logical; whether to do a dry run, just listing files that will be downloaded. This can be useful when testing the use of pattern to filter the files to download.

force

logical; if the data have already been downloaded, should a fresh copy be downloaded anyway.

show_progress

logical; whether to print download progress information.

Details

The complete data package for each species contains a large number of files, all of which are cataloged in the vignettes. Most users will only require a small subset of these files, so by default this function only downloads the most commonly used files: GeoTIFFs providing estimate of relative abundance and proportion of population. For those interested in additional data products, the arguments starting with download_ control the download of these other products. The pattern argument provides even finer grained control over what gets downloaded.

Examples

if (FALSE) {
# download the example data
ebirdst_download_status("yebsap-example")

# download the data package for wood thrush
ebirdst_download_status("woothr")

# use pattern to only download low resolution (27 km) geotiff data
# dry_run can be used to see what files will be downloaded
ebirdst_download_status("lobcur", pattern = "_27km_", dry_run = TRUE)
# use pattern to only download high resolution (3 km) weekly abundance data
ebirdst_download_status("lobcur", pattern = "abundance_median_3km",
                        dry_run = TRUE)
}