Create report for sites with most unseen species

Usage

SitesReport(
  centers,
  ebird_key,
  species_seen,
  center_names = NULL,
  report_filename = "Goals-Report",
  report_dir = getwd(),
  report_format = c("html", "pdf"),
  max_sites = 5,
  dist = 50,
  back = 4,
  hotspot = TRUE,
  include_provisional = FALSE,
  max_tries = 5,
  timeout_sec = 30,
  messages = c("minimal", "none", "verbose"),
  drop_patterns = c("sp.", "/", "Domestic type", "hybrid"),
  include_maps = TRUE
)

Arguments

centers: Numeric vector or matrix of latitude and longitude coordinates; vector should be of length 2, e.g. c(latitude, longitude), while matrix should have two columns (first column is latitude, second column is longitude).
ebird_key: Character vector with eBird API key.
species_seen: Character vector of species that have already been seen.
center_names: Character vector of names to use for each pair of latitude and longitude coordinates in centers.
report_filename: Name of output file without file extension (see report_format); e.g. if report_filename is "sites-2021" and report_format is "html", the report will be saved to sites-2021.html.
report_dir: Destination folder for the output file; if NULL, report will be saved to working directory.
report_format: File format for report; takes one of two values: "html" or "pdf".
max_sites: Maximum number of sites to return for each pair of coordinates defined in centers; maximum is 12.
dist: Numeric radius in kilometers of distance from each geographic center point defined by coordinates in centers from which to return recent observations.
back: Number of days back to search for observations.
hotspot: Logical indicating whether or not to restrict results to hotspot locations.
include_provisional: Logical indicating whether not to include observations which have not yet been reviewed.
max_tries: Maximum number of query attempts to try (only for expert use).
timeout_sec: Integer time to allow before query is aborted (only for expert use).
messages: Character indicating the degree to which messages are printed during the report assembly process. Options are "minimal", "none", or "verbose".
drop_patterns: Character vector of patterns in species' names to exclude certain species from consideration, such as domesticated species, hybrids, and observations not identified to species level (e.g. "Toxostoma sp.").
include_maps: Logical vector indicating whether or not to draw maps of identified sites; should be length 1 or the number of centers (i.e. same length as centers if centers is a vector, same number of rows as centers if centers is a matrix).

Value

Silently returns a list with two named elements:

results_list: A list where each element is a list of the results of queries for a center. Each element is a list with two named elements:
report_details: A list containing the settings used to build this report, such as days back and distances.

Details

The function uses the eBird API (see https://documenter.getpostman.com/view/664302/S1ENwy59/) to build the report. Queries to the eBird API require a user key; you can request an eBird API key by logging into your eBird account and navigating to https://ebird.org/api/keygen/. See examples and vignette for using your eBird API key.

Examples

if (FALSE) {
  # Read in data downloaded from eBird
  list_file <- system.file("extdata", "example-list.csv", package = "lifeR")
  user_list <- read.csv(file = list_file)
  # Only common names are required
  my_species <- user_list$Common.Name
  # Read in eBird API key from a text file
  key <- scan(file = "ebird-key.txt", what = "character")

  # A single center requires vector of coordinates
  locs <- c(45, -109)
  SitesReport(centers = locs, ebird_key = key, 
  species_seen = my_species)
  
  # For multiple centers, pass a matrix to centers argument
  loc_mat <- matrix(data = c(33, -109, 39, -119.1), nrow = 2, byrow = TRUE)
  loc_names <- c("Brushy Mountain", "Yerington")
  SitesReport(centers = loc_mat, ebird_key = key, 
  species_seen = my_species, center_names = loc_names)
}