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."). The function uses grep with fixed = FALSE to identify which species to exclude, hence the backslashes in the default values in drop_patterns.
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) { # \dontrun{
  # 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)
} # }