update documentation for ssd_hc() and ssd_hp()

closes #271

R/hc.R

@@ -14,28 +14,34 @@
 
 #' Hazard Concentrations for Species Sensitivity Distributions
 #'
-#' Calculates concentration(s) with quantile based bootstrap confidence intervals 
+#' Calculates concentration(s) with bootstrap confidence intervals 
 #' that protect specified percentage(s) of species for 
 #' individual or model-averaged distributions
 #' using parametric or non-parametric bootstrapping.
 #' 
 #' Model-averaged estimates and/or confidence intervals (including standard error) 
-#' can be calculated  by treating the distributions as constituting a single mixture distribution
+#' can be calculated  by treating the distributions as 
+#' constituting a single mixture distribution
 #' versus 'taking the mean'.
+#' When calculating the model averaged estimates treating the
+#' distributions as constituting a single mixture distribution 
+#' ensures that `ssd_hc()` is the inverse of `ssd_hp()`.
 #' 
 #' If treating the distributions as constituting a single mixture distribution
 #' when calculating model average confidence intervals then
 #' `weighted` specifies whether to use the original model weights versus
-#' re-estimating for each bootstrap sample.
-#' Conversely when 'taking the mean' then `weighted` specifies
+#' re-estimating for each bootstrap sample unless 'taking the mean' in which case 
+#' `weighted` specifies
 #' whether to take bootstrap samples from each distribution proportional to 
-#' its weight versus calculating the weighted arithmetic means of the lower 
-#' and upper confidence limits.
+#' its weight (so that they sum to `nboot`) versus 
+#' calculating the weighted arithmetic means of the lower 
+#' and upper confidence limits based on `nboot` samples for each distribution.
 #' 
 #' Based on Burnham and Anderson (2002),
 #' distributions with an absolute AIC difference greater 
-#' than a delta of by default 7 are excluded
-#' prior to calculation of the hazard concentrations.
+#' than a delta of by default 7 are unlikely to influence the calculations and 
+#' are excluded
+#' prior to calculation of the hazard concentrations to reduce the run time.
 #' 
 #' @references
 #' 
@@ -95,20 +101,21 @@ ssd_hc.list <- function(x, percent = 5, ...) {
 ssd_hc.fitdists <- function(
     x, 
     percent = 5, 
+    average = TRUE,
     ci = FALSE, 
     level = 0.95, 
     nboot = 1000,
-    average = TRUE,
-    multi_est = TRUE,
-    delta = 7, 
     min_pboot = 0.99,
-    parametric = TRUE, 
+    multi_est = TRUE,
     multi_ci = TRUE,
     weighted = TRUE,
-    control = NULL,
+    parametric = TRUE, 
+    delta = 7, 
     samples = FALSE,
     save_to = NULL,
-    ...) {
+    control = NULL,
+    ...
+) {
 
   chk_vector(percent)
   chk_numeric(percent)
@@ -154,8 +161,8 @@ ssd_hc.fitburrlioz <- function(
     nboot = 1000,
     min_pboot = 0.99, 
     parametric = FALSE, 
-    save_to = NULL, 
     samples = FALSE, 
+    save_to = NULL, 
     ...) {
   chk_length(x, upper = 1L)
   chk_named(x)

R/hcp.R

@@ -255,8 +255,6 @@ hcp_weighted <- function(hcp, weight, value, method, nboot) {
   method <- if (parametric) "parametric" else "non-parametric"
 
   # TODO: implement hcp_weighted
-  # TODO: perhaps rename average to unweighted
-  # TODO: better yet add weighted column...
   hcp_average(hcp, weight, value, method, nboot)
 }
 

R/hp.R

@@ -36,19 +36,19 @@ ssd_hp <- function(x, ...) {
 ssd_hp.fitdists <- function(
     x, 
     conc = 1, 
+    average = TRUE,
     ci = FALSE, 
     level = 0.95, 
     nboot = 1000,
-    average = TRUE, 
-    multi_est = TRUE,
-    delta = 7, 
     min_pboot = 0.99,
+    multi_est = TRUE,
+    multi_ci = TRUE,
+    weighted = TRUE,
     parametric = TRUE, 
-    multi_ci = TRUE, 
-    control = NULL, 
+    delta = 7, 
     samples = FALSE,
-    save_to = NULL, 
-    weighted = TRUE, 
+    save_to = NULL,
+    control = NULL,
     ...
 ) {
 

R/params.R

@@ -17,7 +17,7 @@
 #' @param all_dists A flag specifying whether all the named distributions must fit successfully.
 #' @param at_boundary_ok A flag specifying whether a model with one or more
 #' parameters at the boundary should be considered to have converged (default = FALSE).
-#' @param average A flag specifying whether to provide model averaged values.
+#' @param average A flag specifying whether to provide model averaged values as opposed to a value for each distribution.
 #' @param breaks A character vector
 #' @param bounds A named non-negative numeric vector of the left and right bounds for
 #' uncensored missing (0 and Inf) data in terms of the orders of magnitude
@@ -30,13 +30,13 @@
 #' @param control A list of control parameters passed to [`stats::optim()`].
 #' @param data A data frame.
 #' @param delta A non-negative number specifying the maximum absolute AIC difference cutoff.
-#' Distributions with an absolute AIC difference greater than delta are excluded.
+#' Distributions with an absolute AIC difference greater than delta are excluded from the calculations.
 #' @param digits A whole number specifying the number of significant figures.
 #' @param dists A character vector of the distribution names.
 #' @param hc A count between 1 and 99 indicating the percent hazard concentration (or NULL).
 #' @param label A string of the column in data with the labels.
 #' @param left A string of the column in data with the concentrations.
-#' @param level A number between 0 and 1 of the confidence level.
+#' @param level A number between 0 and 1 of the confidence level of the interval.
 #' @param linecolor A string of the column in pred to use for the line color.
 #' @param linetype A string of the column in pred to use for the linetype.
 #' @param llocation location parameter on the log scale.
@@ -55,20 +55,20 @@
 #' @param meanlog1 mean on log scale parameter.
 #' @param meanlog2 mean on log scale parameter.
 #' @param min_pboot A number between 0 and 1 of the minimum 
-#' proportion of bootstrap samples that must successfully fit in the sense of returning a likelihood 
-#' in order to report the confidence intervals.
+#' proportion of bootstrap samples that must successfully fit (return a likelihood) 
+#' to report the confidence intervals.
 #' @param min_pmix A number between 0 and 0.5 specifying the minimum proportion in mixture models.
 #' @param all_estimates A flag specifying whether to calculate estimates for all implemented distributions.
-#' @param multi_ci A flag specifying whether to treat the distributions as constituting a single distribution when generating model averaged confidence intervals.
-#' @param multi_est A flag specifying whether to treat the distributions as constituting a single distribution when providing model averaged estimates.
+#' @param multi_ci A flag specifying whether to treat the distributions as constituting a single distribution which is now the recommended approach (as opposed to taking the mean) when calculating model averaged confidence intervals.
+#' @param multi_est A flag specifying whether to treat the distributions as constituting a single distribution (as opposed to taking the mean) when calculating model averaged estimates.
 #' @param na.rm A flag specifying whether to silently remove missing values or 
 #' remove them with a warning.
 #' @param n positive number of observations.
-#' @param nboot A count of the number of bootstrap samples to use to estimate confidence limits. A value of at least 10,000 is recommended for official guidelines.
+#' @param nboot A count of the number of bootstrap samples to use to estimate the confidence limits. A value of 10,000 is recommended for official guidelines.
 #' @param nrow A positive whole number of the minimum number of non-missing rows.
 #' @param nsim A positive whole number of the number of simulations to generate.
 #' @param object The object.
-#' @param parametric A flag specifying whether to perform parametric (as opposed to non-parametric) bootstrapping when `ci = TRUE`.
+#' @param parametric A flag specifying whether to perform parametric bootstrapping as opposed to non-parametrically resampling the original data with replacement.
 #' @param p vector of probabilities.
 #' @param percent A numeric vector of percent values to estimate hazard concentrations for.
 #' @param pmix Proportion mixture parameter.
@@ -82,7 +82,7 @@
 #' @param rescale A flag specifying whether to rescale concentration values by dividing by the geometric mean of the minimum and maximum positive finite values.
 #' @param ribbon A flag indicating whether to plot the confidence interval as a grey ribbon as opposed to green solid lines.
 #' @param right A string of the column in data with the right concentration values.
-#' @param save_to NULL or a string specifying a directory to save the bootstrap datasets and parameter estimates to.
+#' @param save_to NULL or a string specifying a directory to save where the bootstrap datasets and parameter estimates (when successfully converged) to.
 #' @param samples A flag specfying whether to include a numeric vector of the bootstrap samples as a list column in the output. 
 #' @param scale scale parameter.
 #' @param scalelog1 scalelog1 parameter.
@@ -99,7 +99,10 @@
 #' @param silent A flag indicating whether fits should fail silently.
 #' @param size A number for the size of the labels.
 #' @param weight A string of the numeric column in data with positive weights less than or equal to 1,000 or NULL.
-#' @param weighted A flag which when `multi_ci = TRUE` specifies whether to use the original model weights (as opposed to reestimating for each bootstrap sample) or when `multi_ci = FALSE` specifies whether to use the weighted bootstrap (as opposed to generating the same number of bootstrap samples for each model).
+#' @param weighted A flag which specifies whether to use the original model weights (as opposed to re-estimating for each bootstrap sample) unless `multi_ci = FALSE` in which case it specifies
+#' whether to take bootstrap samples from each distribution proportional to 
+#' its weight versus calculating the weighted arithmetic means of the lower 
+#' and upper confidence limits.
 #' @param x The object.
 #' @param xbreaks The x-axis breaks as one of:
 #'   - `NULL` for no breaks

R/predict.R

@@ -31,16 +31,16 @@ stats::predict
 predict.fitdists <- function(
     object, 
     percent = 1:99, 
-    ci = FALSE,
+    average = TRUE,
+    ci = FALSE, 
     level = 0.95, 
     nboot = 1000,
-    average = TRUE, 
-    delta = 7,
     min_pboot = 0.99,
-    parametric = TRUE,
-    multi_ci = TRUE,
     multi_est = TRUE,
+    multi_ci = TRUE,
     weighted = TRUE,
+    parametric = TRUE, 
+    delta = 7, 
     control = NULL,
     ...) {
   chk_unused(...)
@@ -55,6 +55,7 @@ predict.fitdists <- function(
     delta = delta, 
     parametric = parametric,
     multi_ci = multi_ci, 
+    multi_est = multi_est,
     weighted = weighted, 
     control = control
   )