R/base.R

In timtrice/Hurricanes: Web Scraper for Atlantic and East Pacific Hurricanes and Tropical Storms

#' @title rrricanes
#' @description rrricanes is a web-scraping library for R designed to deliver
#' hurricane data (past and current) into well-organized datasets. With these
#' datasets you can explore past hurricane tracks, forecasts and structure
#' elements.
#'
#' This documentation and additional help articles
#' \href{https://ropensci.github.io/rrricanes/}{can be found online}.
#'
#' Text products (Forecast/Advisory, Public Advisory, Discussions and
#' Probabilities) are only available from 1998 to current. An effort will be
#' made to add prior data as available.
#'
#' @section Getting Storms:
#' List all storms that have developed by year and basin. Year must be in a
#' four-digit format (\%Y) and no earlier than 1998. Basin can be one or both
#' of Atlantic ("AL") or East Pacific ("EP").
#' \describe{
#'   \item{\code{\link{get_storms}}}{List all storms by year, basin}
#' }
#'
#' @section Getting Storm Data:
#'
#' \code{\link{get_storm_data}} can be used to select multiple products,
#' multiple storms and from multiple basins.
#'
#' Additional text products are:
#' \describe{
#'   \item{\code{\link{get_discus}}}{Storm Discussions}
#'   \item{\code{\link{get_fstadv}}}{Forecast/Advisory. These products contain a
#'   bulk of the information for tropical cyclones including current position,
#'   structure, forecast position and forecast structure.}
#'   \item{\code{\link{get_posest}}}{Position Estimates. Rare and used generally
#'   for threatening cyclones. This product was discontinued after the 2013
#'   season and is now issued as \code{\link{get_update}}.}
#'   \item{\code{\link{get_prblty}}}{Strike Probabilities. Show the probability
#'   of the center of a cyclone passing within 65nm of a location for a given
#'   forecast period. This product was discontinued after 2005, replaced with
#'   \code{\link{get_wndprb}}.}
#'   \item{\code{\link{get_public}}}{Public Advisory. General non-structured
#'   information exists in these products.}
#'   \item{\code{\link{get_update}}}{Updates. Generally issued when a cyclone
#'   undergoes a sudden change that requires immediate notice.}
#'   \item{\code{\link{get_wndprb}}}{Wind Speed Probability. Lists the
#'   probability of a location experiencing a minimum of 35kt, 50kt or 64kt
#'   winds for an alotted forecast period or accumulated probability. This
#'   product replaced \code{\link{get_prblty}} after the 2005 season.}
#' }
#'
#' The products above may take some time to load if the NHC website is slow (as
#' is often the case, unfortunately). For all storm advisories issued outside
#' of the current month, use the \code{rrricanesdata} package.
#'
#' To install \code{rrricanesdata}, run
#'
#' \code{
#' install.packages("rrricanesdata",
#'          repos = "https://timtrice.github.io/drat/",
#'          type = "source")
#' }
#'
#' See \code{vignette("installing_rrricanesdata", package = "rrricanes")} for
#' more information.
#'
#' @section GIS Data:
#'
#' For enhanced plotting of storm data, several GIS datasets are available. The
#' core GIS functions return URLs to help you refine the data you wish to view.
#' (Some products will not exist for all storms/advisories). These products are:
#'
#' \describe{
#'   \item{\code{\link{gis_advisory}}}{Past track, current position, forecast
#'     and wind radii}
#'   \item{\code{\link{gis_breakpoints}}}{Breakpoints for watches and warnings}
#'   \item{\code{\link{gis_latest}}}{All available GIS products for active
#'     cyclones}
#'   \item{\code{\link{gis_outlook}}}{Tropical Weather Outlook}
#'   \item{\code{\link{gis_prob_storm_surge}}}{Probabilistic Storm Surge}
#'   \item{\code{\link{gis_windfield}}}{Wind Radii}
#'   \item{\code{\link{gis_wsp}}}{Wind Speed Probabilities}
#' }
#'
#' \code{\link{gis_download}} will download the datasets from the above
#' functions.
#'
#' Some GIS datasets will need to be converted to dataframes to plot geoms. Use
#' \code{\link{shp_to_df}} to convert SpatialLinesDataFrames and
#' SpatialPolygonsDataFrames. SpatialPointsDataFrames can be converted using
#' \code{tibble::as_data_frame} targeting the @data object.
#'
#' @section Package Options:
#'
#' \code{dplyr.show_progress} displays the dplyr progress bar when scraping raw
#' product datasets. In \code{\link{get_storms}}, it is based on the number of
#' years being requested. In the product functions (i.e.,
#' \code{\link{get_fstadv}}) it is based on the number of advisories. It can be
#' misleading when calling \code{\link{get_storm_data}} because it shows the
#' progress of working through a storm's product advisories but will reset on
#' new products/storms.
#'
#' @section Package Options:
#'
#' \code{dplyr.show_progress} displays the dplyr progress bar when scraping raw
#' product datasets. In \code{\link{get_storms}}, it is based on the number of
#' years being requested. In the product functions (i.e.,
#' \code{\link{get_fstadv}}) it is based on the number of advisories. It can be
#' misleading when calling \code{\link{get_storm_data}} because it shows the
#' progress of working through a storm's product advisories but will reset on
#' new products/storms.
#'
#' \code{rrricanes.working_msg} is set to FALSE by default. When TRUE, it will
#' list the current storm, advisory and date being worked.
#'
#' @docType package
#' @name rrricanes
NULL

#' @importFrom rlang .data
#' @importFrom stats complete.cases
.pkgenv <- new.env(parent = emptyenv())

.onLoad <- function(libname, pkgname) {
  op <- options()
  op.rrricanes <- list(rrricanes.working_msg = FALSE)
  toset <- !(names(op.rrricanes) %in% names(op))
  if (any(toset)) options(op.rrricanes[toset])

  has_data <- base::requireNamespace("rrricanesdata", quietly = TRUE)
  .pkgenv[["has_data"]] <- has_data

  canes.env <- new.env(parent = emptyenv())
  canes.env$quad <- c("NE", "SE", "SW", "NW")

}

.onAttach <- function(libname, pkgname) {
  msg <- "rrricanes is not intended for use in emergency situations."
  packageStartupMessage(msg)
}

hasData <- function(has_data = .pkgenv$has_data) {
  if (!has_data) {
    stop("rrricanesdata is not installed.")
  }
}


utils::globalVariables(c(  "Date",
                        "lat", "long", "group", ".",
                         stringr::str_c(c("NE", "SE", "SW", "NW"), "34"),
                         "everything", "where",
                         "serial_numbers", "sid",
                         "Seas", "Forecast", "WindRadius"
                        ))

quads <- c("NE", "SE", "SW", "NW")