Merge pull request #217 from DistanceDevelopment/Issue_215

Issue 215 - added conf_level and alpha arguments to ds

Author: lenthomas

DESCRIPTION

@@ -16,7 +16,7 @@ Description: A simple way of fitting detection functions to distance sampling
     Horvitz-Thompson-like estimator) if survey area information is provided. See
     Miller et al. (2019) <doi:10.18637/jss.v089.i01> for more information on
     methods and <https://distancesampling.org/resources/vignettes.html> for example analyses.
-Version: 2.0.1
+Version: 2.0.1.9000
 URL: https://github.com/DistanceDevelopment/Distance/
 BugReports: https://github.com/DistanceDevelopment/Distance/issues
 Language: en-GB

NEWS.md

@@ -1,3 +1,7 @@
+# Distance 2.0.2
+
+* Added arguments conf_level and alpha to ds so users can specify level of confidence in computing confidence intervals (Issue #215)
+
 # Distance 2.0.1
 
 * Fixes issue with print dht2 when multipliers are a data.frame (Issue #179)

R/ds.R

@@ -130,6 +130,11 @@
 #' @param winebin If you are trying to use our MCDS.exe optimizer on a
 #'   non-windows system then you may need to specify the winebin. Please 
 #'   see [`mcds_dot_exe`][mrds::mcds_dot_exe] for more details.
+#' @param conf_level level of confidence used in computations of confidence interval width: 
+#'   default 0.95, must be between 0 and 1
+#' @param alpha provides an alternative way to specify `conf_level`.  If `alpha` is specified
+#'   then `conf_level` is set to 1-`alpha`.  (This takes precedence over whatever value is given
+#'   to `conf_level`.)
 #' @param dht.group deprecated, see same argument with underscore, above.
 #' @param region.table deprecated, see same argument with underscore, above.
 #' @param sample.table deprecated, see same argument with underscore, above.
@@ -340,6 +345,8 @@ ds <- function(data, truncation=ifelse(is.null(data$distend),
              initial_values=NULL, max_adjustments=5, er_method=2, dht_se=TRUE,
              optimizer = "both",
              winebin = NULL,
+             conf_level = 0.95,
+             alpha,
              # deprecated below here:
              dht.group,
              region.table,
@@ -531,6 +538,14 @@ ds <- function(data, truncation=ifelse(is.null(data$distend),
     stop("Cannot supply initial values when using AIC term selection")
   }
 
+  # check conf_level
+  if(!((conf_level >= 0) | (conf_level <= 1))) stop("Option conf_level is not in the range 0-1")
+  # set conf_level if alpha specified
+  if(!missing(alpha)){
+    if(!((alpha >= 0) | (alpha <= 1))) stop("Option alpha is not in the range 0-1")
+    conf_level <- 1 - alpha
+  }
+  
   ### Actually fit some models here
 
   # construct the meta data object...
@@ -731,7 +746,8 @@ ds <- function(data, truncation=ifelse(is.null(data$distend),
     dht_options <- list(group         = dht_group,
                         ervar         = er_var,
                         varflag       = er_method,
-                        convert.units = convert_units)
+                        convert.units = convert_units,
+                        ci.width      = conf_level)
 
     # if no obs_table
     if(is.null(obs_table)){