Issue 192

DESCRIPTION

@@ -15,8 +15,8 @@ Description: A simple way of fitting detection functions to distance sampling
     supported. Abundance and density estimates can also be calculated (via a
     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://examples.distancesampling.org/> for example analyses.
-Version: 2.0.0.9008
+    methods and <https://distancesampling.org/resources/vignettes.html> for example analyses.
+Version: 2.0.0.9010
 URL: https://github.com/DistanceDevelopment/Distance/
 BugReports: https://github.com/DistanceDevelopment/Distance/issues
 Language: en-GB
@@ -26,7 +26,8 @@ Depends:
 Imports:
     dplyr,
     methods,
-    rlang
+    rlang,
+    Rdpack
 Suggests:
     rmarkdown,
     kableExtra,
@@ -45,3 +46,4 @@ Suggests:
 Encoding: UTF-8
 Roxygen: list(markdown = TRUE)
 RoxygenNote: 7.3.2
+RdMacros: Rdpack

NAMESPACE

@@ -32,6 +32,7 @@ export(summarize_ds_models)
 export(unflatten)
 export(units_table)
 import(mrds)
+importFrom(Rdpack,reprompt)
 importFrom(dplyr,"%>%")
 importFrom(dplyr,across)
 importFrom(dplyr,all_of)

NEWS.md

@@ -6,6 +6,10 @@
 * Truncation distances greater than the largest cutpoint value for binned data are no longer permitted as these cause fitting issues. (Issue #175)
 * print.dht_result now displays estimates for groups as well as individuals by default when group size is present. (Issue #178)
 
+Enhancements
+
+* Warnings and documentation clarification regarding ER variance estimation when there is only a single transect. (Issue #192 and mrds Issue #115)
+
 # Distance 2.0.0
 
 * Requires mrds 3.0.0. mrds is called by ds for fitting detection functions. In mrds there has been a change of optimizer used for CDS detection functions - a constraint solver slsqp now used. This removes the need for external optimizer MCDS.exe in most cases. Other minor changes to optimization have been implemented to improve reliability (see NEWS file of mrds for more info).
@@ -26,7 +30,7 @@
 
 # Distance 1.0.7
 
-* dht2 now requires the object field in flatfile formatted data. The following vignette shows how to add an object field if your data does not have already have one: https://examples.distancesampling.org/Distance-cameratraps/camera-distill.html
+* dht2 now requires the object field in flatfile formatted data. The following vignette shows how to add an object field if your data does not have already have one: https://distancesampling.org/Distance/articles/web-only/CTDS/camera-distill.html
 * Fix bugs when a uniform is fitted with no adjustments
 * Fixed error in dht2 when binned data used distend / distbegin
 
@@ -112,7 +116,7 @@
 * Added lots of example data sets
 * new abundance estimation via dht2! Handles more complex situations.
 * bootstrap variance estimation via bootdht
-* for more examples see http://examples.distancesampling.org
+* for more examples see https://distancesampling.org/resources/vignettes.html
 
 # Distance 0.9.8
 

R/Distance-package.R

@@ -8,7 +8,7 @@
 #' necessary to use `mrds`.
 #'
 #' Examples of distance sampling analyses are available at
-#' <http://examples.distancesampling.org/>.
+#' <https://distancesampling.org/resources/vignettes.html>.
 #'
 #' For help with distance sampling and this package, there is a Google Group
 #' <https://groups.google.com/forum/#!forum/distance-sampling>.
@@ -72,10 +72,11 @@ NULL
 #' observation.
 #'
 #' The example given below was provided by Eric Rexstad. Additional examples
-#' can be found at  <http://examples.distancesampling.org/>.
+#' can be found at  <https://distancesampling.org/resources/vignettes.html>.
 #'
 #' @name flatfile
 #' @docType methods
+#' @importFrom Rdpack reprompt
 #' @examples
 #' \dontrun{
 #' library(Distance)

R/bootdht.R

@@ -107,7 +107,7 @@
 #' in to `bootdht` must be hard coded (otherwise you get back 0 successful 
 #' bootstraps). For a worked example showing this, see the camera trap distance 
 #' sampling online example at 
-#' <https://examples.distancesampling.org/Distance-cameratraps/camera-distill.html>.
+#' <https://distancesampling.org/Distance/articles/web-only/CTDS/camera-distill.html>.
 #'
 #' @importFrom utils txtProgressBar setTxtProgressBar getTxtProgressBar
 #' @importFrom stats as.formula AIC

R/bootdht_Dhat_summarize.R

@@ -6,7 +6,7 @@
 #' estimated density (with stratum labels).
 #'
 #' Further examples of such functions can be found at
-#' <http://examples.distancesampling.org>.
+#' <https://distancesampling.org/resources/vignettes.html>.
 #'
 #' @param ests output from [`dht2`][dht2].
 #' @param fit fitted detection function object (unused).

R/bootdht_Nhat_summarize.R

@@ -6,7 +6,7 @@
 #' estimated abundance (with stratum labels).
 #'
 #' Further examples of such functions can be found at
-#' <http://examples.distancesampling.org>.
+#' <https://distancesampling.org/resources/vignettes.html>.
 #'
 #' @param ests output from [`dht2`][dht2].
 #' @param fit fitted detection function object (unused).

R/dht2.R

@@ -33,17 +33,17 @@
 #' @param ci_width for use with confidence interval calculation (defined as
 #' 1-alpha, so the default 95 will give a 95% confidence interval).
 #' @param innes logical flag for computing encounter rate variance using either
-#' the method of Innes et al (2002) where estimated abundance per transect
+#' the method of \insertCite{innes2002;textual}{mrds} where estimated abundance per transect
 #' divided by effort is used as the encounter rate, vs. (when `innes=FALSE`)
-#' using the number of observations divided by the effort (as in Buckland et
-#' al., 2001)
+#' using the number of observations divided by the effort (as in \insertCite{buckland2001;nobrackets}{mrds})
 #' @param total_area for options `stratification="effort_sum"` and
 #' `stratification="replicate"` the area to use as the total for combined,
 #' weighted final estimates.
 #' @param binomial_var if we wish to estimate abundance for the covered area
 #' only (i.e., study area = surveyed area) then this must be set to be
-#' `TRUE` and use the binomial variance estimator of Borchers et al.
-#' (1998). This is only valid when objects are not clustered. (This situation
+#' `TRUE` and use the negative binomial variance estimator of
+#'  \insertCite{borchers1998;textual}{mrds}. This is only valid when 
+#'  objects are not clustered. (This situation
 #' is rare.)
 #' @return a `data.frame` (of class `dht_result` for pretty printing) with
 #' estimates and attributes containing additional information, see "Outputs"
@@ -129,7 +129,7 @@
 #'  total number of animals, you should use this option.
 #'
 #' A simple example of using `stratification="geographical"` is given below.
-#' Further examples can be found at <http://examples.distancesampling.org/>
+#' Further examples can be found at <https://distancesampling.org/resources/vignettes.html>
 #' (see, e.g., the deer pellet survey).
 #'
 #' @section Variance:
@@ -144,12 +144,12 @@
 #' calculated is given here, though see references for more details.
 #'   * *detection function*: variance from the detection function parameters is
 #'   transformed to variance about the abundance via a sandwich estimator (see
-#'   e.g., Appendix C of Borchers et al (2002)).
+#'   e.g., Appendix C of \insertCite{borchers2002;textual}{Distance}).
 #'   * *encounter rate*: for strata with >1 transect in them, the encounter
-#'   rate estimators given in Fewster et al (2009) can be specified via the
+#'   rate estimators given in \insertCite{fewster2009;textual}{mrds} can be specified via the
 #'   `er_est` argument. If the argument `innes=TRUE` then calculations use the
 #'   estimated number of individuals in the transect (rather than the
-#'   observed), which was give by Innes et al (2002) as a superior estimator.
+#'   observed), which was given by \insertCite{innes2002;textual}{mrds} as a superior estimator.
 #'   When there is only one transect in a stratum, Poisson variance is assumed.
 #'   Information on the Fewster encounter rate variance estimators are given in
 #'   [`varn`][mrds::varn]
@@ -209,27 +209,7 @@
 #'   uncertainty in multipliers
 #'
 #' @references
-#'
-#' Borchers, D.L., S.T. Buckland, P.W. Goedhart, E.D. Clarke, and S.L. Hedley.
-#' 1998. Horvitz-Thompson estimators for double-platform line transect surveys.
-#' *Biometrics* 54: 1221-1237.
-#'
-#' Borchers, D.L., S.T. Buckland, and W. Zucchini. 2002 *Estimating Animal
-#' Abundance: Closed Populations*. Statistics for Biology and Health. Springer
-#' London.
-#'
-#' Buckland, S.T., E.A. Rexstad, T.A. Marques, and C.S. Oedekoven. 2015
-#' *Distance Sampling: Methods and Applications*. Methods in Statistical
-#' Ecology. Springer International Publishing.
-#'
-#' Buckland, S.T., D.R. Anderson, K. Burnham, J.L. Laake, D.L. Borchers, and L.
-#' Thomas. 2001 *Introduction to Distance Sampling: Estimating Abundance of
-#' Biological Populations*. Oxford University Press.
-#'
-#' Innes, S., M. P. Heide-Jorgensen, J.L. Laake, K.L. Laidre, H.J. Cleator, P.
-#' Richard, and R.E.A. Stewart. 2002 Surveys of belugas and narwhals in the
-#' Canadian high arctic in 1996. *NAMMCO Scientific Publications* 4, 169-190.
-#'
+#' \insertAllCited{}
 #' @name dht2
 #' @examples
 #' \dontrun{

R/ds.R

@@ -41,7 +41,7 @@
 #' 1, 2, 3, ... are fitted when `adjustment = "cos"` and order 2, 4, 6, ... 
 #' otherwise. For `key="hn"` or `"hr"` adjustments of order 2, 3, 4, ... are 
 #' fitted when `adjustment = "cos"` and order 4, 6, 8, ... otherwise. See 
-#' Buckland et al. (2001, p. 47) for details.
+#' \insertCite{buckland2001;textual}{mrds} p. 47 for details.
 #' @param order order of adjustment terms to fit. The default value (`NULL`)
 #' results in `ds` choosing the orders to use - see `nadj`. Otherwise a scalar
 #' positive integer value can be used to fit a single adjustment term of the
@@ -92,11 +92,13 @@
 #' @param convert_units conversion between units for abundance estimation, see
 #' "Units", below. (Defaults to 1, implying all of the units are "correct"
 #' already.)
-#' @param er_var encounter rate variance estimator to use when abundance
-#' estimates are required. Defaults to "R2" for line transects and "P2" for
-#' point transects (>= 1.0.9, earlier versions <= 1.0.8 used the "P3" estimator 
-#' by default for points). See [`dht2`][dht2] for more information and if more
-#' complex options are required.
+#' @param er_var specifies which encounter rate estimator to use in the case
+#' that dht_se is TRUE, er_method is either 1 or 2 and there are two or more 
+#' samplers. Defaults to "R2" for line transects and "P2" for point transects 
+#' (>= 1.0.9, earlier versions <= 1.0.8 used the "P3" estimator by default 
+#' for points), both of which assume random placement of transects. For 
+#' systematic designs, alternative estimators may be more appropriate, 
+#' see [`dht2`][dht2] for more information.
 #' @param method optimization method to use (any method usable by
 #' [`optim`][stats::optim] or [`optimx`][optimx::optimx]). Defaults to
 #' `"nlminb"`.
@@ -112,10 +114,13 @@
 #' @param max_adjustments maximum number of adjustments to try (default 5) only
 #' used when `order=NULL`.
 #' @param er_method encounter rate variance calculation: default = 2 gives the
-#' method of Innes et al, using expected counts in the encounter rate. Setting
+#' method of \insertCite{innes2002;textual}{mrds}, using expected counts in the encounter rate. Setting
 #' to 1 gives observed counts (which matches Distance for Windows) and 0 uses
-#' binomial variance (only useful in the rare situation where study area =
-#' surveyed area). See [`dht.se`][mrds::dht.se] for more details.
+#' negative binomial variance (only useful in the rare situation where study area =
+#' surveyed area).
+#' See [`dht.se`][mrds::dht.se] for more details, noting this \code{er_method}
+#' argument corresponds to the \code{varflag} element of the \code{options} 
+#' argument in \code{dht.se}.
 #' @param dht_se should uncertainty be calculated when using `dht`? Safe to
 #' leave as `TRUE`, used in `bootdht`.
 #' @param optimizer By default this is set to 'both'. In this case 
@@ -147,15 +152,15 @@
 #' also be supplied. Note that stratification only applies to abundance
 #' estimates and not at the detection function level. Density and abundance
 #' estimates, and corresponding estimates of variance and confidence intervals,
-#' are calculated using the methods described in Buckland et al. (2001)
+#' are calculated using the methods described in \insertCite{buckland2001;textual}{mrds}
 #' sections 3.6.1 and 3.7.1 (further details can be found in the documentation
 #' for [`dht`][mrds::dht]).
 #'
 #' For more advanced abundance/density estimation please see the
 #' [`dht`][mrds::dht] and [`dht2`][dht2] functions.
 #'
 #' Examples of distance sampling analyses are available at
-#' <http://examples.distancesampling.org/>.
+#' <https://distancesampling.org/resources/vignettes.html>.
 #'
 #' Hints and tips on fitting (particularly optimisation issues) are on the
 #' [`mrds_opt`][mrds::mrds_opt] manual page.
@@ -172,7 +177,7 @@
 #' can often be the cause of model convergence failures. It is recommended that
 #' one plots a histogram of the observed distances prior to model fitting so as
 #' to get a feel for an appropriate truncation distance. (Similar arguments go
-#' for left truncation, if appropriate). Buckland et al (2001) provide
+#' for left truncation, if appropriate). \insertCite{buckland2001;textual}{mrds} provide
 #' guidelines on truncation.
 #'
 #' When specified as a percentage, the largest `right` and smallest `left`
@@ -206,7 +211,8 @@
 #' monotonicity (and is by default for detection functions without covariates).
 #'
 #' Monotonicity constraints are supported in a similar way to that described
-#' in Buckland et al (2001). 20 equally spaced points over the range of the
+#' in \insertCite{buckland2001;textual}{mrds}. 20 equally spaced points over 
+#' the range of the
 #' detection function (left to right truncation) are evaluated at each round
 #' of the optimisation and the function is constrained to be either always
 #' less than it's value at zero (`"weak"`) or such that each value is
@@ -265,14 +271,7 @@
 #' @importFrom stats quantile as.formula
 #' @importFrom methods is
 #' @references
-#' Buckland, S.T., Anderson, D.R., Burnham, K.P., Laake, J.L., Borchers, D.L.,
-#' and Thomas, L. (2001). Distance Sampling. Oxford University Press. Oxford,
-#' UK.
-#'
-#' Buckland, S.T., Anderson, D.R., Burnham, K.P., Laake, J.L., Borchers, D.L.,
-#' and Thomas, L. (2004). Advanced Distance Sampling. Oxford University Press.
-#' Oxford, UK.
-#'
+#' \insertAllCited{}
 #' @examples
 #'
 #' # An example from mrds, the golf tee data.

_pkgdown.yml

@@ -82,12 +82,7 @@ reference:
 navbar:
   bg: primary
   structure:
-    right: [twitter, github]
-  components:
-    twitter:
-      icon: fa-twitter
-      href: https://twitter.com/distancesamp
-      aria-label: Twitter
+    right: [github]
   left:
     - text: Function reference
       href: reference/index.html