update documentation

DESCRIPTION

@@ -12,7 +12,8 @@ Description: Provides a collection of tools that analyze fixed interval precipit
   intensities for various time steps, calculates rainfall erosivity values and 
   creates missing values summaries.
 License: MIT + file LICENSE
-URL: https://github.com/kvantas/hyetor
+URL: https://github.com/kvantas/hyetor,
+  https://kvantas.github.io/hyetor/
 BugReports: https://github.com/kvantas/hyetor/issues             
 Depends: 
     R (>= 3.5.0)

R/hyet_aggregate.R

@@ -1,21 +1,21 @@
-#' @title Aggregate a hyetograph using a time step
+#' @title Aggregate an hyetograph using a predefined time-step
 #'
-#' @description \code{hyet_aggregate} uses a predefined time step value to
-#' aggregate precipitation records in an hyetograph.
+#' @description \code{hyet_aggregate} uses a predefined time-step to
+#' aggregate precipitation records in an hyetograph. Returns an error if
+#' \code{hyet} is not a valid hyetograph.
 #'
-#' @param hyet a hyetograph from \code{hyet_create} function.
-#' @param time_step an integer specifying the time step value of the aggregated
-#' hyetograph.
-#' @param ts_unit a character string specifying the time unit of the aggregated
-#' hyetograph. Valid units are "mins", "hours", "days", "months", "quarter" or
-#' "year".
+#' @param hyet an hyetograph from \code{hyet_create} function.
+#' @param time_step a numeric value that represents the time-step.
+#' @param ts_unit a character string specifying the time unit. Valid values
+#' are "mins", "hours", "days", "months", "quarter" or "year".
 #'
 #' @return a tibble with the aggregated hyetograph.
 #' @export hyet_aggregate
 #'
 #' @examples
 #'
-#' prec30min <- hyet_aggregate(prec5min, 30, "mins")
+#' prec30min <- prec5min %>%
+#'  hyet_aggregate(30, "mins")
 #'
 hyet_aggregate <- function(hyet, time_step, ts_unit) {
 

R/hyet_erosivity.R

@@ -4,9 +4,9 @@
 #' (i.e. from \code{hyet_split}) and computes the rainfall erosivity.
 #'
 #' @param hyet an hyetograph from \code{hyet_create} function. Precipitation
-#' values must be in (mm).
-#' @param time_step hyetograph's time-step in minutes. Must have one of the
-#' values: \code{[5, 10, 15, 30]}.
+#' values must be in millimeters (mm).
+#' @param time_step hyetograph's time-step in minutes. Valid value is on of
+#' \code{[5, 10, 15, 30]}.
 #' @param en_equation a character string specifying the equation to be used
 #' for calculating kinetic energy of rainfall. Must have one of the values:
 #' \code{"brown_foster", "mcgregor_mutch", "wisch_smith"}.
@@ -16,13 +16,13 @@
 #' \itemize{
 #' \item{\emph{Brown and Foster (1987)},
 #'
-#'       \eqn{e = 0.29(1 - 0.72  exp(-0.05i))}}
+#'       \eqn{e = 0.29(1 - 0.72  e^{-0.05i})}}
 #' \item{\emph{McGregor and Mutchler (1976)},
 #'
-#'       \eqn{e = 0.273 + 0.2168exp(-0.048i) - 0.4126exp(-0.072i)}}
+#'       \eqn{e = 0.273 + 0.2168e^{-0.048i} - 0.4126e^{-0.072i}}}
 #' \item{\emph{Wischmeier and Smith (1958)},
 #'
-#'       \eqn{e = 0.119 + 0.0873 * log10(i)},
+#'       \eqn{e = 0.119 + 0.0873log_{10}(i)},
 #'
 #'       with the upper limit of 0.283  MJ/ha/mm if \eqn{i} > 76 mm/h.}
 #' }
@@ -70,7 +70,6 @@
 #' )
 #'
 #' # compute erosivity
-#'
 #' hyet %>%
 #' hyet_erosivity(time_step, en_equation)
 

R/hyet_fill.R

@@ -1,15 +1,17 @@
-#' @title Fill a hyetograph with missing date values
+#' @title Fill an hyetograph with missing date values
 #'
-#' @description  \code{hyet_fill} fills missing date values in a hyetograph
-#' with NA values.  Returns an error if \code{hyet} is not a valid hyetograph or
-#' \code{time_step} is a not a numeric value.
+#' @description  \code{hyet_fill} fills missing date values in an hyetograph
+#' with NA values. This function can be used when missing values in time series
+#' are marked implicitly using missing dates. Returns an error if \code{hyet} is
+#' not a valid hyetograph.
 #'
-#' @param hyet a hyetograph from \code{hyet_create} function
-#' @param time_step an integer that represents hyetograph's time-step.
-#' @param ts_unit a character string specifying a time unit. Valid units are
-#' "mins" and "hours".
+#' @param hyet an hyetograph from \code{hyet_create} function.
+#' @param time_step a numeric value that represents the time-step.
+#' @param ts_unit a character string specifying the time unit. Valid values
+#' are "mins", "hours", "days", "months", "quarter" or "year".
 #'
-#' @return a tibble with the variables \code{date} and \code{prec}
+#' @return a tibble with the variables \code{date} and \code{prec} of the filled
+#' hyetograph.
 #' @export hyet_fill
 #'
 #' @examples
@@ -24,18 +26,19 @@
 #' # create hyetograph
 #' hyet <- hyet_create(prec_date, prec_values)
 #'
-#' # remove some random values from hyetograph
+#' # remove some random values from the hyetograph
 #' hyet_miss <- hyet[-sample(100,30), ]
 #'
 #' # fill hyetograph
-#' hyet_fill(hyet_miss, 5, "mins")
+#' hyet_fill <- hyet_miss %>%
+#'   hyet_fill(5, "mins")
 
 hyet_fill <- function(hyet, time_step = 5, ts_unit = "mins") {
 
   # check parameters
   hyet_check(hyet)
   count_check(time_step)
-  units_check(ts_unit)
+  units_check(ts_unit, minhour = FALSE)
 
   # fill
   util_fill(hyet, time_step, ts_unit)

R/hyet_intensities.R

@@ -2,13 +2,13 @@
 #'
 #' @description \code{hyet_intensities} uses an hyetograph, single or grouped
 #' (i.e. from \code{hyet_split}) and computes characteristic maximum rolling
-#' precipitation intensities.
-#'
-#' @param hyet a hyetograph from \code{hyet_create} function.
-#' @param time_step an integer specifying the time step value of the aggregated
+#' precipitation intensities. Returns an error if \code{hyet} is not a valid
 #' hyetograph.
-#' @param ts_unit a character string specifying the time unit of the aggregated
-#' hyetograph. Valid units are "mins" and "hours"
+#'
+#' @param hyet an hyetograph from \code{hyet_create} function.
+#' @param time_step a numeric value that represents the time-step.
+#' @param ts_unit a character string specifying the time unit. Valid values
+#' are "mins" and "hours".
 #'
 #' @return a tibble with the calculated total precipitation height, duration
 #' and maximum rolling rainfall intensities for 5, 10, 15, 30 minutes and 1, 2,
@@ -39,9 +39,10 @@
 #' # add a dry period
 #' hyet$prec[5:10] <- 0
 #'
-#' # split to storms and calculate intensities
-#' storms <- hyet_split(hyet, time_step, ts_unit)
-#' intens <- hyet_intensities(storms, time_step, ts_unit)
+#' # split to storms and calculate intensities per storm
+#' intens <- hyet %>%
+#'   hyet_split(time_step, ts_unit)
+#'   hyet_intensities(time_step, ts_unit)
 
 hyet_intensities <- function(hyet, time_step, ts_unit) {
 

R/hyet_split.R

@@ -1,15 +1,25 @@
-#' Split an hyetograph to rainstorms using a fixed critical time duration of
-#' no precipitation
+#' Split an hyetograph to independent rainstorms
 #'
-#' @param hyet hyet an hyetograph from \code{hyet_create} function.
-#' @param time_step an integer that represents hyetograph's time-step.
-#' @param ts_unit a character string specifying a time unit. Valid units are
-#' "mins" and "hours".
-#' @param crit_dur an integer or a vector of 12 integers that represent the
-#' critical time duration of no precipitation that is used to separate the
-#' hyetograph to independent rainstorms.
+#' @description \code{hyet_split} uses a predefined vector with monthly values
+#' of fixed critical time duration of no precipitation to split an hyetograph
+#' to independent rainstorms.
+#' Returns an error if \code{hyet} is not a valid hyetograph.
+#'
+#' @param hyet an hyetograph from \code{hyet_create} function.
+#' @param time_step a numeric value that represents the time-step.
+#' @param ts_unit a character string specifying the time unit. Valid values
+#' are "mins" and "hours".
+#' @param crit_dur a vector of 12 numeric values in hours. This vector
+#' represents the monthly critical time duration of no precipitation that is
+#' used to separate the hyetograph to independent rainstorms. Default value for
+#' all months is six hours.
+#'
+#' @return a grouped dataframe with independent rainstorms.
+#'
+#' @references
+#' Restrepo-Posada, Pedro J., and Peter S. Eagleson. "Identification of
+#' independent rainstorms." Journal of Hydrology 55.1-4 (1982): 303-319.
 #'
-#' @return a grouped dataframe
 #' @export hyet_split
 #'
 #' @examples
@@ -31,11 +41,11 @@
 #' hyet$prec[10:23] <- 0
 #' hyet$prec[41:54] <- 0
 #'
-#' # split hyet
-#' storms <- hyet_split(hyet, time_step, ts_unit, crit_dur)
+#' # split hyetograph to storms
+#' storms <- hyet %>%
+#'   hyet_split(time_step, ts_unit, crit_dur)
 #'
-hyet_split <- function(hyet, time_step = 5, ts_unit = "mins",
-                       crit_dur = rep(6, 12)) {
+hyet_split <- function(hyet, time_step, ts_unit, crit_dur = rep(6, 12)) {
 
   # check input values ---------------------------------------------------------
   hyet_check(hyet)

R/hyet_uch.R

@@ -1,20 +1,27 @@
 #' Create Unitless Cumulative Hyetographs (UCH)
 #'
 #' @description \code{hyet_uch} uses an hyetograph, single or grouped
-#' (i.e. from \code{hyet_split}) and creates the corresponding UCHs.
+#' (i.e. from \code{hyet_split}) and creates the corresponding UCHs. Returns an
+#' error if \code{hyet} is not a valid hyetograph.
 #'
-#' @param hyet a hyetograph from \code{hyet_create} function.
-#' @param time_step an integer specifying the time step value of the aggregated
-#' hyetograph.
-#' @param ts_unit a character string specifying the time unit of the aggregated
-#' hyetograph. Valid units are "mins" and "hours"
+#' @param hyet an hyetograph from \code{hyet_create} function.
+#' @param time_step a numeric value that represents the time-step.
+#' @param ts_unit a character string specifying the time unit. Valid values
+#' are "mins" and "hours".
 #'
-#' @return a tibble with every one hundred percent of cumulative precipitation.
+#' @return a tibble with unitless cumulative precipitation for every 1%.
 #'
 #' @note missing date values must be set explicit using the \code{hyet_fill}
 #' function if a single hyetograph is used. \code{hyet_split} returns filled
 #' storms.
 #'
+#' @references
+#'
+#' Bonta, J. V. (2004). Development and utility of Huff curves for
+#' disaggregating precipitation amounts. Applied Engineering in Agriculture,
+#' 20(5), 641.
+#' Huff, F. A. (1967). Time distribution of rainfall in heavy storms. Water
+#' Resources Research, 3(4), 1007-1019.
 #' @export hyet_uch
 #'
 #' @examples
@@ -34,9 +41,9 @@
 #' )
 #'
 #' # create uch
-#'
 #' uch <- hyet %>%
-#' hyet_uch(time_step, ts_unit)
+#'   hyet_uch(time_step, ts_unit)
+#'
 hyet_uch <- function(hyet, time_step, ts_unit) {
 
   # check values

R/hyetor-package.R

@@ -6,7 +6,7 @@
 #'    \item {Aggregate precipitation time series values.}
 #'    \item {Split precipitation records to independent rainstorms.}
 #'    \item {Compile Unitless Cumulative Hyetographs.}
-#'    \item {Find maximum rainfall intensities for various common time steps.}
+#'    \item {Find maximum rainfall intensities for various time steps.}
 #'    \item {Calculate rainfall erosivity values.}
 #'    \item {Create missing values summaries.}
 #'    }
@@ -16,8 +16,8 @@
 #' The data are retrieved from:
 #'  \url{http://www.hydroscope.gr/}
 #'
-#' @name rainstorms
-#' @aliases rainstorms-package
+#' @name hyetor
+#' @aliases hyetor-package
 #' @docType package
 #'
 #' @importFrom rlang .data

R/utils.R

@@ -19,7 +19,7 @@ vector_check <- function(time_step) {
   }
 }
 
-#' return error if units are not hours or minutes
+#' return error if units are valid
 #'
 #' @noRd
 units_check <- function(x, minhour = TRUE) {

_pkgdown.yml

@@ -0,0 +1,25 @@
+title: hyetor
+
+reference:
+  - title: Package
+    desc: Package details
+    contents:
+    - hyetor
+  - title: Preprocessing
+    desc: Functions that can be used to preprocess precipitation timeseries
+    contents:
+    - hyet_create
+    - hyet_fill
+    - hyet_aggregate
+    - hyet_split
+  - title: Analysis
+    desc: Funtions that analyze precipitation timeseries
+    contents:
+    - hyet_erosivity
+    - hyet_intensities
+    - hyet_missing
+    - hyet_uch
+  - title: Datasets
+    desc: The internal datasets of the package
+    contents:
+    - prec5min