SitesReport: Create report for sites with most unseen species

In jcoliver/lifeR: Identify Sites for Your Bird List

Create report for sites with most unseen species

Description

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

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.

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:

center_info

A list with latitude (lat), longitude (longitude), and name name of the geographic center.

results

A tibble of observations from the top sites (with a maximum number of sites defined by max_sites).

report_details

A list containing the settings used to build this report, such as days back and distances.

Examples

## Not run: 
  # 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)

## End(Not run)

jcoliver/lifeR documentation built on Feb. 14, 2025, 11:54 p.m.