R/eb-lifelist.r

In mstrimas/auklet: Analysis and Visualization of Your eBird Sightings

#' Generate life list
#'
#' Summarize your eBird data into a life list or year list. Lists can be
#' generated by country.
#'
#' @param x [eb_sightings] object; your personal eBird sightings
#' @param year integer; year or vector of years to calculate list for.
#' @param country character; countries to filter by. Countries can either be
#'   expressed as English names or
#'   [ISO 2-letter country codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).
#'   English names are matched via regular expressions using
#'   [countrycode][countrycode()], so there is some flexibility in names.
#'
#' @return A data frame (actually [dplyr::tibble]) of your list list.
#' @export
#' @examples
#' f <- system.file("extdata/MyEBirdData.csv", package = "auklet")
#' ebird_data <- eb_sightings(f)
#' eb_lifelist(ebird_data)
#'
#' # 2010 year list for canada
#' eb_lifelist(ebird_data, year = 2010, country = "CA")
eb_lifelist <- function(x, year, country) {
  UseMethod("eb_lifelist")
}

#' @export
eb_lifelist.eb_sightings <- function(x, year, country) {
  x <- eb_countable(x)

  # filter by year
  if (!missing(year)) {
    stopifnot(is_integer(year))
    x <- dplyr::filter(x, lubridate::year(.data$date) %in% year)
  }
  # filter by country
  if (!missing(country)) {
    stopifnot(is.character(country))

    # convert country names to codes
    name_codes <- countrycode::countrycode(country,
                                           origin = "country.name",
                                           destination = "iso2c",
                                           warn = FALSE)
    # lookup codes
    code_codes <- match(tolower(country),
                        tolower(countrycode::countrycode_data$iso2c))
    code_codes <- countrycode::countrycode_data$iso2c[code_codes]
    # combine, preference to codes
    country_codes <- dplyr::coalesce(name_codes, code_codes)

    # check codes are valid
    valid_codes <- !is.na(country_codes)
    if (!all(valid_codes)) {
      m <- paste0("The following countries are not valid: \n\t",
                  paste(country[!valid_codes], collapse =", "))
      stop(m)
    }
    x <- dplyr::filter(x, .data$country %in% country_codes)
  }

  x %>%
    dplyr::group_by(.data$report_as) %>%
    dplyr::arrange(.data$date, .data$submission_id) %>%
    dplyr::filter(dplyr::row_number(.data$date) == 1) %>%
    dplyr::ungroup() %>%
    dplyr::select(.data$species_common, .data$species_scientific,
                  .data$date, .data$country, .data$state_province,
                  .data$order, .data$family, .data$taxon_order) %>%
    dplyr::arrange(.data$taxon_order)
}

#' @export
eb_lifelist.data.frame <- function(x, year, country) {
  eb_lifelist.eb_sightings(df_to_eb(x), year = year, country = country)
}