diff --git a/R/annual.R b/R/annual.R index 60d098b..3e9ad3a 100644 --- a/R/annual.R +++ b/R/annual.R @@ -1,16 +1,27 @@ -#' @title Calculate Annual Summaries +#' @title Calculate Annual Timseries +#' +#' @description +#' `annual()` aggregates the daily timeseries into an annual one. +#' Aggregation is done differently for TMIN, TMAX, and PRCP. +#' +#' @details +#' Aggregation is done as: +#' \describe{ +#' \item{TMAX}{Maximum temperature recorded in the year} +#' \item{TMIN}{Minimum temperature recorded in the year} +#' \item{PRCP}{Total (cumulative) precipitation amount in the year} +#' } #' #' @importFrom dplyr select mutate across distinct_all summarize group_by left_join #' @importFrom tidyselect contains everything all_of #' @importFrom tidyr drop_na #' @importFrom tibble tibble as_tibble #' @importFrom rlang .data -#' #' @export #' #' @param x Object of class `ghcn_daily`. See [daily()] for details. -#' #' @return A tibble with the annual timeseries at the stations. +#' #' @examples #' annual(CA003076680) annual <- function(x) { diff --git a/R/coverage.R b/R/coverage.R index 1bfb62b..d0fbbf5 100644 --- a/R/coverage.R +++ b/R/coverage.R @@ -1,23 +1,33 @@ #' @title Calculate Monthly Coverage #' +#' @description +#' `monthly_coverage()` calculates how many days have been recorded for +#' each month in the time period. +#' +#' @details +#' To calculate the coverage, a full daily time range is full joined to the +#' timeseries. Missing days are set to NA. Coverage is then calculated as +#' the number of values that are not NAs over the number of NAs. +#' #' @importFrom dplyr mutate group_by full_join #' @importFrom tidyr pivot_longer pivot_wider #' @importFrom tidyselect any_of #' @importFrom tibble tibble #' @importFrom rlang .data -#' #' @export #' #' @param x Object of class `ghcn_daily`. See [daily()] for details. +#' @return A table with mothly coverage. #' -#' @details Calculates the monthly coverage of one station. -#' -#' @return A table with mothly coverages. #' @examples #' cleaned <- remove_flagged(CA003076680) #' cover <- monthly_coverage(cleaned) #' cover[cover$year == 2020, ] monthly_coverage <- function(x) { + stopifnot(inherits(x, "ghcn_daily")) + .check_flags(x) + x <- .drop_flags(x) + timespan <- seq.Date(min(x$date), max(x$date), by = "day") x <- tibble(date = timespan) |> @@ -54,25 +64,35 @@ monthly_coverage <- function(x) { #' @title Calculate Annual Coverage #' +#' @description +#' `annual_coverage()` calculates how many days have been recorded for +#' each year in the time period. +#' +#' @details +#' To calculate the coverage, a full daily time range is full joined to the +#' timeseries. Missing days are set to NA. Coverage is then calculated as +#' the number of values that are not NAs over the number of NAs. +#' #' @importFrom dplyr mutate group_by full_join #' @importFrom tidyr pivot_longer pivot_wider #' @importFrom tidyselect any_of #' @importFrom tibble tibble #' @importFrom rlang .data -#' #' @export #' #' @param x Object of class `ghcn_daily`. See [daily()] for details. -#' -#' @details Calculates the annual coverage of one station. -#' #' @return A table with annual coverage. +#' #' @examples #' cleaned <- remove_flagged(CA003076680) #' cover <- annual_coverage(cleaned) #' cover annual_coverage <- function(x) { - timespan <- seq.Date(min(x$date), max(x$date), by = "day") + stopifnot(inherits(x, "ghcn_daily")) + .check_flags(x) + x <- .drop_flags(x) + + timespan <- seq.Date(min(x$date), max(x$date), by = "day") x <- tibble(date = timespan) |> full_join(x, by = "date", multiple = "all") |> @@ -106,28 +126,39 @@ annual_coverage <- function(x) { return (ans) } - #' @title Calculate Period Coverage #' +#' @description +#' `period_coverage()` calculates how many days have been recorded for +#' the whole time period. +#' +#' @details +#' To calculate the coverage, a full daily time range is full joined to the +#' timeseries. Missing days are set to NA. Coverage is then calculated as +#' the number of values that are not NAs over the number of NAs. +#' Period coverage is a constant value for each station in the `ghcn_daily` +#' object. +#' #' @importFrom dplyr mutate group_by full_join #' @importFrom tidyr pivot_longer pivot_wider #' @importFrom tidyselect any_of #' @importFrom tibble tibble #' @importFrom rlang .data -#' #' @export #' #' @param x Object of class `ghcn_daily`. See [daily()] for details. +#' @return A table with period coverage. #' -#' @details Calculates the period coverage of one station. -#' -#' @return A table with coverage across the period. #' @examples #' cleaned <- remove_flagged(CA003076680) #' cover <- period_coverage(cleaned) #' cover period_coverage <- function(x) { - timespan <- seq.Date(min(x$date), max(x$date), by = "day") + stopifnot(inherits(x, "ghcn_daily")) + .check_flags(x) + x <- .drop_flags(x) + + timespan <- seq.Date(min(x$date), max(x$date), by = "day") x <- tibble(date = timespan) |> full_join(x, by = "date", multiple = "all") |> @@ -163,6 +194,18 @@ period_coverage <- function(x) { #' @title Calculate Coverage of Daily Summaries #' +#' @description +#' `coverage()` calculates the temporal coverage of the time series. +#' See also [monthly_coverage()], [annual_coverage()], and [period_coverage()]. +#' +#' @details +#' Returns a table with: +#' \itemize{ +#' \item mothly_coverage The proportion of the days with records in the month +#' \item annual_coverage The proportion of the days with records in the year +#' \item annual_coverage The proportion of the years with records in the reference period +#' } +#' #' @importFrom dplyr mutate group_by group_split select distinct_all left_join bind_cols bind_rows #' @importFrom tibble as_tibble #' @importFrom tidyr pivot_longer @@ -170,22 +213,11 @@ period_coverage <- function(x) { #' @importFrom stats interaction.plot #' @importFrom graphics grid #' @importFrom rlang .data -#' #' @export #' #' @param x Object of class `ghcn_daily`. See [daily()] for details. #' @param graph Logical, if to show a graph of annual coverage. #' -#' @details This function calculates the temporal coverage of stations. -#' It returns a table with: -#' \itemize{ -#' \item mothly_coverage The proportion of the days with records in the month -#' \item annual_coverage The proportion of the days with records in the year -#' \item annual_coverage The proportion of the years with records in the reference period -#' } -#' Important: 'annual_coverage = 1' does not mean that all years have 'annual_coverage = 1', -#' but rather that all years have at least one record. -#' #' @return A table with coverage. #' @examples #' cleaned <- remove_flagged(CA003076680) diff --git a/R/daily.R b/R/daily.R index 317bdc5..d77dc6b 100644 --- a/R/daily.R +++ b/R/daily.R @@ -36,7 +36,7 @@ } if (length(station_id) > 1) station_id <- paste(station_id, collapse = ",") - req <- paste0( + url <- paste0( "https://www.ncei.noaa.gov/access/services/data/v1?", "dataset=daily-summaries&", "stations=", station_id, "&", @@ -47,7 +47,7 @@ "includeAttributes=true&", "format=json" ) - return(req) + return(url) } #' @title Request Daily Summaries diff --git a/man/annual.Rd b/man/annual.Rd index 39fc64f..fd31e73 100644 --- a/man/annual.Rd +++ b/man/annual.Rd @@ -2,7 +2,7 @@ % Please edit documentation in R/annual.R \name{annual} \alias{annual} -\title{Calculate Annual Summaries} +\title{Calculate Annual Timseries} \usage{ annual(x) } @@ -13,7 +13,16 @@ annual(x) A tibble with the annual timeseries at the stations. } \description{ -Calculate Annual Summaries +\code{annual()} aggregates the daily timeseries into an annual one. +Aggregation is done differently for TMIN, TMAX, and PRCP. +} +\details{ +Aggregation is done as: +\describe{ +\item{TMAX}{Maximum temperature recorded in the year} +\item{TMIN}{Minimum temperature recorded in the year} +\item{PRCP}{Total (cumulative) precipitation amount in the year} +} } \examples{ annual(CA003076680)