Skip to content

Commit 11b627f

Browse files
danmcgraw94danmcgraw94
authored
Resolve #4: audit \dontrun{} usage and add missing examples (#33)
* docs(aep2stage, stage2aep): remove \dontrun{}, document tie behavior * docs(aep2stage, stage2aep): remove \dontrun{}, document ties warning (bootstrap_vfc): remove \dontrun{}, clarify GEV/LP3 examples docs(rfa_simulate): fix Expected-mode parameter set, document runtime * docs: resolve #4 (dontrun audit, missing examples, related cleanup) Audit of \dontrun{} usage: - Remove wrappers from aep2stage, stage2aep, bootstrap_vfc, flow_frequency_sampler_expected, hydrograph_setup - Add @details to stage2aep documenting expected approx() ties warning - Add inline GEV/LP3 comments to bootstrap_vfc - Keep wrapper on rfa_simulate with runtime comment Bug fix: rfa_simulate Expected-mode example used jmd_vfc_parameters (single posterior mode row) where Nbin*Mevent rows are required. Swapped to jmd_bf_parameter_sets across all three modes. Missing examples: added example and @return to theme_rfar_conceptual (was rendering blank). Internal helpers (interpolate_aep_matrix, interpolate_stage_matrix, stage_frequency_curve) intentionally left unexposed per @Keywords i
1 parent 35ed1c4 commit 11b627f

21 files changed

Lines changed: 171 additions & 137 deletions

‎DESCRIPTION‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -44,12 +44,10 @@ Depends:
4444
LazyData: true
4545
Suggests:
4646
gt,
47-
ggplot2,
4847
knitr,
4948
rmarkdown,
5049
scales,
5150
testthat (>= 3.0.0),
52-
tidyverse,
5351
dplyr,
5452
tidyr,
5553
kableExtra,
@@ -60,6 +58,7 @@ Imports:
6058
cli,
6159
future,
6260
future.apply,
61+
ggplot2,
6362
lmom,
6463
lubridate,
6564
progressr,

‎R/bootstrap_vfc.R‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,13 +29,15 @@
2929
#' dist = "LP3",
3030
#' ERL = jmd_vfc_parameters$erl)
3131
#'
32+
#' # GEV Example with parent distribution parameters
3233
#' gev_example <- c(3.0, 1.0, -0.1)
3334
#' gev_samples <- bootstrap_vfc(gev_example,
3435
#' dist = "GEV",
3536
#' ERL = 200,
3637
#' Nboots = 5000)
3738
#' hist(gev_samples$params[,1])
3839
#'
40+
#' # LP3 Example with parent distribution parameters
3941
#' lp3_example <- c(3.5, 0.22, 0.1)
4042
#' lp3_samples <- bootstrap_vfc(lp3_example,
4143
#' dist = "LP3",

‎R/data.R‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -206,15 +206,15 @@
206206
#'
207207
#' Inflow hydrograph shape from May 1955 flood event.
208208
#'
209-
#' @format A data frame with 241 rows and 2 columns:
209+
#' @format A data frame with 241 rows and 4 columns:
210210
#' \describe{
211211
#' \item{Ordinate}{Timeseries Ordinate}
212212
#' \item{Date}{Date mm/dd/yyyy}
213213
#' \item{Time}{Time in 00:00}
214214
#' \item{Flow}{Inflow (cfs)}
215215
#' }
216216
#' @examples
217-
#' sapply(jmd_hydro_may1955,class)
217+
#' sapply(jmd_hydro_may1955, class)
218218
#' head(jmd_hydro_may1955)
219219
#' plot(jmd_hydro_may1955$Ordinate, jmd_hydro_may1955$Flow,
220220
#' xlab = "Hour", ylab = "Inflow (cfs)",
@@ -225,15 +225,15 @@
225225
#'
226226
#' Inflow hydrograph shape for Probable Maximum Flood (PMF).
227227
#'
228-
#' @format A data frame with 192 rows and 2 columns:
228+
#' @format A data frame with 192 rows and 4 columns:
229229
#' \describe{
230230
#' \item{Ordinate}{Timeseries Ordinate}
231231
#' \item{Date}{Date mm/dd/yyyy}
232232
#' \item{Time}{Time in 00:00}
233233
#' \item{Flow}{Inflow (cfs)}
234234
#' }
235235
#' @examples
236-
#' sapply(jmd_hydro_pmf,class)
236+
#' sapply(jmd_hydro_pmf, class)
237237
#' head(jmd_hydro_pmf)
238238
#' plot(jmd_hydro_pmf$Ordinate, jmd_hydro_pmf$Flow,
239239
#' xlab = "Hour", ylab = "Inflow (cfs)",
@@ -244,15 +244,15 @@
244244
#'
245245
#' Inflow hydrograph shape for Spillway Design Flood (SDF).
246246
#'
247-
#' @format A data frame with 337 rows and 2 columns:
247+
#' @format A data frame with 337 rows and 4 columns:
248248
#' \describe{
249249
#' \item{Ordinate}{Timeseries Ordinate}
250250
#' \item{Date}{Date mm/dd/yyyy}
251251
#' \item{Time}{Time in 00:00}
252252
#' \item{Flow}{Inflow (cfs)}
253253
#' }
254254
#' @examples
255-
#' sapply(jmd_hydro_sdf,class)
255+
#' sapply(jmd_hydro_sdf, class)
256256
#' head(jmd_hydro_sdf)
257257
#' plot(jmd_hydro_sdf$Ordinate, jmd_hydro_sdf$Flow,
258258
#' xlab = "Hour", ylab = "Inflow (cfs)",

‎R/flow_frequency_sampler.R‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,10 @@
3131
#' params <- c(4.85, 0.39, -0.15)
3232
#' result <- flow_frequency_sampler(params, freq_dist = "LP3",
3333
#' Nbin = 20, Mevent = 500)
34+
#' # Dimensions of result
3435
#' dim(result$flow) # 500 x 20
36+
#'
37+
#' # Distribution of Sampled Flows
3538
#' hist(result$flow)
3639

3740
flow_frequency_sampler <- function(bestfit_params, freq_dist = "LP3",

‎R/interpolation_functions.R‎

Lines changed: 12 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -72,10 +72,8 @@ interpolate_stage_matrix <- function(results_list, target_aeps) {
7272
#' @seealso \code{\link{stage2aep}} for the inverse operation.
7373
#'
7474
#' @examples
75-
#' \dontrun{
76-
#' # Get stage at the 1% and 0.1% AEP
77-
#' aep2stage(curve$AEP, curve$stage, c(0.01, 0.001))
78-
#' }
75+
#' # Get stage at the 1.12% and 0.175% AEP
76+
#' aep2stage(jmd_rfa_expected$AEP, jmd_rfa_expected$Expected, c(0.0112,1.75E-3))
7977
aep2stage <- function(aep, stage, interp_aep) {
8078
z_aep <- qnorm(1 - aep)
8179
interp_stage <- approx(x = z_aep, y = stage,
@@ -90,6 +88,14 @@ aep2stage <- function(aep, stage, interp_aep) {
9088
#' Interpolation is performed in standard normal (z-variate) space for
9189
#' better behavior across orders of magnitude in AEP.
9290
#'
91+
#' @details
92+
#' Stage-frequency curves typically flatten at very rare AEPs once
93+
#' the reservoir reaches the reservoir model discharge capacity.
94+
#' This produces tied stage values.
95+
#' \code{approx()} handles these by averaging the
96+
#' corresponding AEPs, which may emit a "collapsing to unique 'x'
97+
#' values" warning. This is expected behavior.
98+
#'
9399
#' @param aep Numeric vector of annual exceedance probabilities from the
94100
#' known curve.
95101
#' @param stage Numeric vector of stage values corresponding to \code{aep}.
@@ -103,10 +109,8 @@ aep2stage <- function(aep, stage, interp_aep) {
103109
#' @seealso \code{\link{aep2stage}} for the inverse operation.
104110
#'
105111
#' @examples
106-
#' \dontrun{
107-
#' # Get AEP at stage 3850 ft
108-
#' stage2aep(curve$AEP, curve$stage, 3850)
109-
#' }
112+
#' # Get AEP at stage 3862.0-ft and 3872-ft
113+
#' stage2aep(jmd_rfa_expected$AEP, jmd_rfa_expected$Expected, c(3862.0, 3872))
110114
stage2aep <- function(aep, stage, interp_stage) {
111115
z_aep <- qnorm(1 - aep)
112116
z_interp <- approx(x = stage, y = z_aep,

‎R/plotting_utils.R‎

Lines changed: 21 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,26 @@
1-
#' rfaR ggplot theme for conceptual example
1+
#' rfaR ggplot2 Theme for Conceptual Plots
2+
#'
3+
#' A custom \pkg{ggplot2} theme used in the rfaR conceptual realization
4+
#' vignette. Based on \code{\link[ggplot2]{theme_bw}} with tightened text
5+
#' sizes, italic titles, and the legend suppressed. Intended for figures
6+
#' that emphasize curves over annotation density.
7+
#'
8+
#' @return A \pkg{ggplot2} theme object that can be added to a \code{ggplot}
9+
#' via \code{+}.
210
#'
3-
#' custom ggplot2 theme for rfaR-Realization-Conceptual.Rmd
411
#' @export
12+
#'
13+
#' @seealso \code{\link[ggplot2]{theme_bw}}
14+
#'
15+
#' @examples
16+
#' library(ggplot2)
17+
#' ggplot(jmd_rfa_expected, aes(x = AEP, y = Expected)) +
18+
#' geom_line() +
19+
#' scale_x_continuous(transform = c("log10", "reverse")) +
20+
#' labs(title = "JMD Expected Stage-Frequency",
21+
#' subtitle = "Demonstrating theme_rfar_conceptual()",
22+
#' x = "AEP", y = "Stage (ft)") +
23+
#' theme_rfar_conceptual()
524
theme_rfar_conceptual <- function(){
625
ggplot2::theme_bw() +
726
ggplot2::theme(legend.position = "none",

‎R/rfa_simulate.R‎

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -143,6 +143,10 @@
143143
#'
144144
#' @examples
145145
#' \dontrun{
146+
#' # Not run: Expected and Median modes take ~15s; Full uncert
147+
#' # runs ~10,000 parameter realizations and takes 3-4 hours on a
148+
#' # typical machine.
149+
#'
146150
#' # --- Setup ---
147151
#' hydros <- hydrograph_setup(jmd_hydro_apr1999, jmd_hydro_jun1965,
148152
#' jmd_hydro_may1955, jmd_hydro_pmf,
@@ -151,7 +155,7 @@
151155
#' # --- Expected only (default) ---
152156
#' results_exp <- rfa_simulate(
153157
#' sim_type = "expected",
154-
#' bestfit_params = jmd_vfc_parameters,
158+
#' bestfit_params = jmd_bf_parameter_sets,
155159
#' stage_ts = jmd_wy1980_stage,
156160
#' seasonality = jmd_seasonality$relative_frequency,
157161
#' hydrographs = hydros,
@@ -162,7 +166,7 @@
162166
#' # --- Median only ---
163167
#' results_med <- rfa_simulate(
164168
#' sim_type = "median",
165-
#' bestfit_params = jmd_vfc_parameters,
169+
#' bestfit_params = jmd_bf_parameter_sets,
166170
#' stage_ts = jmd_wy1980_stage,
167171
#' seasonality = jmd_seasonality$relative_frequency,
168172
#' hydrographs = hydros,
@@ -173,16 +177,14 @@
173177
#' # --- Full uncertainty (parallelized) ---
174178
#' results_full <- rfa_simulate(
175179
#' sim_type = "full",
176-
#' bestfit_params = jmd_vfc_parameters,
180+
#' bestfit_params = jmd_bf_parameter_sets,
177181
#' stage_ts = jmd_wy1980_stage,
178182
#' seasonality = jmd_seasonality$relative_frequency,
179183
#' hydrographs = hydros,
180184
#' resmodel = jmd_resmodel,
181185
#' Ncores = 4,
182186
#' sim_name = "jmd"
183187
#' )
184-
#'
185-
186188
#' }
187189
rfa_simulate <- function(sim_type = "expected", bestfit_params, dist = "LP3",
188190
stage_ts, seasonality, hydrographs, resmodel,

‎docs/reference/index.html‎

Lines changed: 15 additions & 1 deletion
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎docs/reference/rfa_simulate.html‎

Lines changed: 8 additions & 5 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎docs/reference/theme_rfar_conceptual-1.png‎

51.6 KB
Loading

0 commit comments

Comments
 (0)