SitesReport {lifeR}

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

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)