Skip to contents

Load predictive performance metric (PPM) rasters

Source: R/load.R
load_ppm.Rd

eBird Status models are evaluated against a test set of eBird data not used during model training and a suite of predictive performance metrics (PPMs) are calculated. The PPMs for each base model are summarized to a 27 km resolution raster grid, where the cell values are the average across all models in the ensemble contributing to that cell. These data are available in raster format provided download_ppms = TRUE was used when calling ebirdst_download_status().

Usage

load_ppm(
  species,
  ppm = c("binary_f1", "binary_pr_auc", "occ_bernoulli_dev", "count_spearman",
    "log_count_pearson", "abd_poisson_dev", "abd_spearman", "log_abd_pearson"),
  path = ebirdst_data_dir()
)

Arguments

species

character; the species to load data for, 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".

ppm

character; the name of a single metric to load data for. See Details for definitions of each metric.

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().

Value

A SpatRaster object with the PPM data. For migrants, rasters are weekly with 52 layers, where the layer names are the dates (MM-DD format) of the midpoint of each week. For residents, a single year round layer is returned.

Details

Eight predictive performance metrics are provided:

  • binary_f1: F1-score comparing the model predictions converted to binary with the observed detection/non-detection for the test checklists.

  • binary_pr_auc: the area on the precision-recall curve generated by comparing the model predictions converted to binary with the observed detection/non-detection for the test checklists.

  • occ_bernoulli_dev: Bernoulli deviance comparing the predicted occurrence with the observed detection/non-detection for the test checklists.

  • count_spearman: Spearman's rank correlation coefficient comparing the predicted count with the observed count for the subset of test checklists on which the species was detected.

  • log_count_pearson: Pearson correlation coefficient comparing the logarithm of the predicted count with the logarithm of the observed count for the subset of test checklists on which the species was detected.

  • abd_poisson_dev: Poisson deviance comparing the predicted relative abundance with the observed count for the full set of test checklists.

  • abd_spearman: Spearman's rank correlation coefficient comparing the predicted relative abundance with the observed count for the full set of test checklists.

  • log_abd_pearson: Pearson correlation coefficient comparing the logarithm of the predicted relative abundance with the logarithm of the observed count for the full set of test checklists.

Examples

if (FALSE) {
# download example data if hasn't already been downloaded
ebirdst_download_status("yebsap-example", download_ppms = TRUE)

# load area under the precision-recall curve PPM raster
load_ppm("yebsap-example", ppm = "binary_pr_auc")
}