Resolve #4: audit \dontrun{} usage and add missing examples

DESCRIPTION

@@ -44,12 +44,10 @@ Depends:
 LazyData: true
 Suggests: 
     gt,
-    ggplot2,
     knitr,
     rmarkdown,
     scales,
     testthat (>= 3.0.0),
-    tidyverse,
     dplyr,
     tidyr,
     kableExtra,
@@ -60,6 +58,7 @@ Imports:
     cli,
     future,
     future.apply,
+    ggplot2,
     lmom,
     lubridate,
     progressr,

R/bootstrap_vfc.R

@@ -29,13 +29,15 @@
 #'                                 dist = "LP3",
 #'                                 ERL = jmd_vfc_parameters$erl)
 #'
+#' # GEV Example with parent distribution parameters
 #' gev_example <- c(3.0, 1.0, -0.1)
 #' gev_samples <- bootstrap_vfc(gev_example,
 #'                               dist = "GEV",
 #'                               ERL = 200,
 #'                               Nboots = 5000)
 #' hist(gev_samples$params[,1])
 #'
+#' # LP3 Example with parent distribution parameters
 #' lp3_example <- c(3.5, 0.22, 0.1)
 #' lp3_samples <- bootstrap_vfc(lp3_example,
 #'                               dist = "LP3",

R/data.R

@@ -206,15 +206,15 @@
 #'
 #' Inflow hydrograph shape from May 1955 flood event.
 #'
-#' @format A data frame with 241 rows and 2 columns:
+#' @format A data frame with 241 rows and 4 columns:
 #' \describe{
 #'   \item{Ordinate}{Timeseries Ordinate}
 #'   \item{Date}{Date mm/dd/yyyy}
 #'   \item{Time}{Time in 00:00}
 #'   \item{Flow}{Inflow (cfs)}
 #' }
 #' @examples
-#' sapply(jmd_hydro_may1955,class)
+#' sapply(jmd_hydro_may1955, class)
 #' head(jmd_hydro_may1955)
 #' plot(jmd_hydro_may1955$Ordinate, jmd_hydro_may1955$Flow,
 #'      xlab = "Hour", ylab = "Inflow (cfs)",
@@ -225,15 +225,15 @@
 #'
 #' Inflow hydrograph shape for Probable Maximum Flood (PMF).
 #'
-#' @format A data frame with 192 rows and 2 columns:
+#' @format A data frame with 192 rows and 4 columns:
 #' \describe{
 #'   \item{Ordinate}{Timeseries Ordinate}
 #'   \item{Date}{Date mm/dd/yyyy}
 #'   \item{Time}{Time in 00:00}
 #'   \item{Flow}{Inflow (cfs)}
 #' }
 #' @examples
-#' sapply(jmd_hydro_pmf,class)
+#' sapply(jmd_hydro_pmf, class)
 #' head(jmd_hydro_pmf)
 #' plot(jmd_hydro_pmf$Ordinate, jmd_hydro_pmf$Flow,
 #'      xlab = "Hour", ylab = "Inflow (cfs)",
@@ -244,15 +244,15 @@
 #'
 #' Inflow hydrograph shape for Spillway Design Flood (SDF).
 #'
-#' @format A data frame with 337 rows and 2 columns:
+#' @format A data frame with 337 rows and 4 columns:
 #' \describe{
 #'   \item{Ordinate}{Timeseries Ordinate}
 #'   \item{Date}{Date mm/dd/yyyy}
 #'   \item{Time}{Time in 00:00}
 #'   \item{Flow}{Inflow (cfs)}
 #' }
 #' @examples
-#' sapply(jmd_hydro_sdf,class)
+#' sapply(jmd_hydro_sdf, class)
 #' head(jmd_hydro_sdf)
 #' plot(jmd_hydro_sdf$Ordinate, jmd_hydro_sdf$Flow,
 #'      xlab = "Hour", ylab = "Inflow (cfs)",

R/flow_frequency_sampler.R

@@ -31,7 +31,10 @@
 #' params <- c(4.85, 0.39, -0.15)
 #' result <- flow_frequency_sampler(params, freq_dist = "LP3",
 #'                                  Nbin = 20, Mevent = 500)
+#' # Dimensions of result
 #' dim(result$flow)  # 500 x 20
+#'
+#' # Distribution of Sampled Flows
 #' hist(result$flow)
 
 flow_frequency_sampler <- function(bestfit_params, freq_dist = "LP3",

R/interpolation_functions.R

@@ -72,10 +72,8 @@ interpolate_stage_matrix <- function(results_list, target_aeps) {
 #' @seealso \code{\link{stage2aep}} for the inverse operation.
 #'
 #' @examples
-#' \dontrun{
-#' # Get stage at the 1% and 0.1% AEP
-#' aep2stage(curve$AEP, curve$stage, c(0.01, 0.001))
-#' }
+#' # Get stage at the 1.12% and 0.175% AEP
+#' aep2stage(jmd_rfa_expected$AEP, jmd_rfa_expected$Expected, c(0.0112,1.75E-3))
 aep2stage <- function(aep, stage, interp_aep) {
   z_aep <- qnorm(1 - aep)
   interp_stage <- approx(x = z_aep, y = stage,
@@ -90,6 +88,14 @@ aep2stage <- function(aep, stage, interp_aep) {
 #' Interpolation is performed in standard normal (z-variate) space for
 #' better behavior across orders of magnitude in AEP.
 #'
+#' @details
+#' Stage-frequency curves typically flatten at very rare AEPs once
+#' the reservoir reaches the reservoir model discharge capacity.
+#' This produces tied stage values.
+#' \code{approx()} handles these by averaging the
+#' corresponding AEPs, which may emit a "collapsing to unique 'x'
+#' values" warning. This is expected behavior.
+#'
 #' @param aep Numeric vector of annual exceedance probabilities from the
 #'   known curve.
 #' @param stage Numeric vector of stage values corresponding to \code{aep}.
@@ -103,10 +109,8 @@ aep2stage <- function(aep, stage, interp_aep) {
 #' @seealso \code{\link{aep2stage}} for the inverse operation.
 #'
 #' @examples
-#' \dontrun{
-#' # Get AEP at stage 3850 ft
-#' stage2aep(curve$AEP, curve$stage, 3850)
-#' }
+#' # Get AEP at stage 3862.0-ft and 3872-ft
+#' stage2aep(jmd_rfa_expected$AEP, jmd_rfa_expected$Expected, c(3862.0, 3872))
 stage2aep <- function(aep, stage, interp_stage) {
   z_aep <- qnorm(1 - aep)
   z_interp <- approx(x = stage, y = z_aep,

R/plotting_utils.R

@@ -1,7 +1,26 @@
-#' rfaR ggplot theme for conceptual example
+#' rfaR ggplot2 Theme for Conceptual Plots
+#'
+#' A custom \pkg{ggplot2} theme used in the rfaR conceptual realization
+#' vignette. Based on \code{\link[ggplot2]{theme_bw}} with tightened text
+#' sizes, italic titles, and the legend suppressed. Intended for figures
+#' that emphasize curves over annotation density.
+#'
+#' @return A \pkg{ggplot2} theme object that can be added to a \code{ggplot}
+#'   via \code{+}.
 #'
-#' custom ggplot2 theme for rfaR-Realization-Conceptual.Rmd
 #' @export
+#'
+#' @seealso \code{\link[ggplot2]{theme_bw}}
+#'
+#' @examples
+#' library(ggplot2)
+#' ggplot(jmd_rfa_expected, aes(x = AEP, y = Expected)) +
+#'   geom_line() +
+#'   scale_x_continuous(transform = c("log10", "reverse")) +
+#'   labs(title = "JMD Expected Stage-Frequency",
+#'        subtitle = "Demonstrating theme_rfar_conceptual()",
+#'        x = "AEP", y = "Stage (ft)") +
+#'   theme_rfar_conceptual()
 theme_rfar_conceptual <- function(){
   ggplot2::theme_bw() +
     ggplot2::theme(legend.position = "none",

R/rfa_simulate.R

@@ -143,6 +143,10 @@
 #'
 #' @examples
 #' \dontrun{
+#' # Not run: Expected and Median modes take ~15s; Full uncert
+#' # runs ~10,000 parameter realizations and takes 3-4 hours on a
+#' # typical machine.
+#'
 #' # --- Setup ---
 #' hydros <- hydrograph_setup(jmd_hydro_apr1999, jmd_hydro_jun1965,
 #'                            jmd_hydro_may1955, jmd_hydro_pmf,
@@ -151,7 +155,7 @@
 #' # --- Expected only (default) ---
 #' results_exp <- rfa_simulate(
 #'   sim_type       = "expected",
-#'   bestfit_params = jmd_vfc_parameters,
+#'   bestfit_params = jmd_bf_parameter_sets,
 #'   stage_ts       = jmd_wy1980_stage,
 #'   seasonality    = jmd_seasonality$relative_frequency,
 #'   hydrographs    = hydros,
@@ -162,7 +166,7 @@
 #' # --- Median only ---
 #' results_med <- rfa_simulate(
 #'   sim_type       = "median",
-#'   bestfit_params = jmd_vfc_parameters,
+#'   bestfit_params = jmd_bf_parameter_sets,
 #'   stage_ts       = jmd_wy1980_stage,
 #'   seasonality    = jmd_seasonality$relative_frequency,
 #'   hydrographs    = hydros,
@@ -173,16 +177,14 @@
 #' # --- Full uncertainty (parallelized) ---
 #' results_full <- rfa_simulate(
 #'   sim_type       = "full",
-#'   bestfit_params = jmd_vfc_parameters,
+#'   bestfit_params = jmd_bf_parameter_sets,
 #'   stage_ts       = jmd_wy1980_stage,
 #'   seasonality    = jmd_seasonality$relative_frequency,
 #'   hydrographs    = hydros,
 #'   resmodel       = jmd_resmodel,
 #'   Ncores         = 4,
 #'   sim_name       = "jmd"
 #' )
-#'
-
 #' }
 rfa_simulate <- function(sim_type = "expected", bestfit_params, dist = "LP3",
                          stage_ts, seasonality, hydrographs, resmodel,