Cran 2.3.0

DESCRIPTION

@@ -11,7 +11,7 @@ Description: Animal abundance estimation via conventional, multiple covariate
     fitting is performed via maximum likelihood. Also included are diagnostics
     and plotting for fitted detection functions. Abundance estimation is via a
     Horvitz-Thompson-like estimator.
-Version: 2.2.9
+Version: 2.3.0
 URL: https://github.com/DistanceDevelopment/mrds/
 BugReports: https://github.com/DistanceDevelopment/mrds/issues
 Depends:
@@ -28,6 +28,5 @@ Suggests:
     knitr,
     rmarkdown,
     bookdown
-VignetteBuilder: knitr
 RoxygenNote: 7.2.3
 Encoding: UTF-8

NEWS

@@ -1,3 +1,16 @@
+mrds 2.3.0
+----------
+
+New Features
+
+* The 'P2' estimator is now the default for estimating the encouter rate variance for point transect surveys. (Issue #65)
+
+Bug Fixes
+
+* Re-formatted the format section of the documentation for the book.tee.data (Issue #91)
+* Ensure that the MCDS optimizer is not used for double observer models as this was generating errors. (Issue #89)
+* Improved the documentation on initial values, lower and upper bounds in both the ddf and mrds_opt documentation (mrds_opt was renamed from mrds-opt which was not accessible via ?mrds-opt). (Issue #90)
+
 mrds 2.2.9
 ----------
 

R/ddf.R

@@ -156,10 +156,16 @@
 #'   \item{\code{refit}}{if TRUE the algorithm will attempt multiple
 #'   optimizations at different starting values if it doesn't converge}
 #'   \item{\code{nrefits}}{number of refitting attempts}
-#'   \item{\code{initial}}{a named list of starting values for the parameters
-#'   (e.g. \code{$scale}, \code{$shape}, \code{$adjustment})}
-#'   \item{\code{lowerbounds}}{a vector of lowerbounds for the parameters}
-#'   \item{\code{upperbounds}}{a vector of upperbounds for the parameters}
+#'   \item{\code{initial}}{a named list of starting values for the dsmodel
+#'   parameters (e.g. \code{$scale}, \code{$shape}, \code{$adjustment})}
+#'   \item{\code{lowerbounds}}{a vector of lowerbounds for the dsmodel 
+#'   parameters in the order the ds parameters will appear in the par 
+#'   element of the ddf object, i.e. \code{fit.ddf$par} where \code{fit.ddf} 
+#'   is a fitted ddf model.}
+#'   \item{\code{upperbounds}}{a vector of upperbounds for the dsmodel 
+#'   parameters in the order the ds parameters will appear in the par 
+#'   element of the ddf object, i.e. \code{fit.ddf$par} where \code{fit.ddf} 
+#'   is a fitted ddf model.}
 #'   \item{\code{limit}}{if TRUE restrict analysis to observations with
 #'   \code{detected}=1}
 #'   \item{\code{debug}}{ if TRUE, if fitting fails, return an object with
@@ -181,10 +187,13 @@
 #'   \code{solnp} when fitting a monotonic model. Default 200.}
 #'   \item{\code{silent}}{silences warnings within ds fitting method (helpful
 #'   for running many times without generating many warning/error messages).}
-#'   \item{\code{optimizer}}{By default this is set to 'both'. In this case 
-#'   the R optimizer will be used and if present the MCDS optimizer will also 
-#'   be used. The result with the best likelihood value will be selected. To 
-#'   run only a specified optimizer set this value to either 'R' or 'MCDS'. 
+#'   \item{\code{optimizer}}{By default this is set to 'both' for single 
+#'   observer analyses and 'R' for double observer analyses. For single 
+#'   observer analyses where optimizer = 'both', the R optimizer will be used 
+#'   and if present the MCDS optimizer will also be used. The result with the 
+#'   best likelihood value will be selected. To run only a specified optimizer 
+#'   set this value to either 'R' or 'MCDS'. The MCDS optimizer cannot currently
+#'   be used for detection function fitting with double observer analyses.  
 #'   See \code{\link{mcds_dot_exe}} for more information.}
 #'   \item{\code{winebin}}{Location of the \code{wine} binary used to run
 #'   \code{MCDS.exe}. See \link{mcds_dot_exe} for more information.}
@@ -194,7 +203,7 @@
 #' \url{http://examples.distancesampling.org/}.
 #'
 #' Hints and tips on fitting (particularly optimisation issues) are on the
-#' \code{\link{mrds-opt}} manual page.
+#' \code{\link{mrds_opt}} manual page.
 #'
 #' @param dsmodel distance sampling model specification
 #' @param mrmodel mark-recapture model specification
@@ -209,7 +218,7 @@
 #' @seealso \code{\link{ddf.ds}}, \code{\link{ddf.io}},
 #' \code{\link{ddf.io.fi}}, \code{\link{ddf.trial}},
 #' \code{\link{ddf.trial.fi}}, \code{\link{ddf.rem}}, \code{\link{ddf.rem.fi}},
-#' \code{\link{mrds-opt}}
+#' \code{\link{mrds_opt}}
 #' @references Laake, J.L. and D.L. Borchers. 2004. Methods for incomplete
 #'   detection at distance zero. In: Advanced Distance Sampling, eds. S.T.
 #'   Buckland, D.R.Anderson, K.P. Burnham, J.L. Laake, D.L. Borchers, and L.
@@ -319,6 +328,16 @@ ddf <- function(dsmodel=call(), mrmodel=call(),data, method="ds",
       stop("For method=",method,", mrmodel must be specified")
     }
   }
+  if(method %in% c("io","trial","rem")){
+    # Do not use the MCDS.exe optimiser
+    if(is.null(control$optimizer)){
+      # If the user has not specified quietly change to use only R optimizer
+      control$optimizer <- "R"
+    }else if(control$optimizer == "MCDS"){
+      warning("The MCDS optimizer cannot currently be used with double observer analyses, the R opitimizer will be used instead.", call. = FALSE, immediate. = TRUE)
+      control$optimizer <- "R"
+    }
+  }
 
   # call method specific fitting function
   result <- switch(method,

R/dht.R

@@ -121,9 +121,10 @@
 #' estimator forms given in Fewster et al (2009) for line transects:
 #' \code{"R2"}, \code{"R3"}, \code{"R4"}, \code{"S1"}, \code{"S2"},
 #' \code{"O1"}, \code{"O2"} or \code{"O3"} by specifying the \code{ervar=}
-#' option (default \code{"R2"}). For points estimator \code{"P3"} is the only
-#' option. See \code{\link{varn}} and Fewster et al (2009) for further details
-#' on these estimators.
+#' option (default \code{"R2"}). For points, either the \code{"P2"} or 
+#' \code{"P3"} estimator can be selected (>=mrds 2.3.0 default \code{"P2"},
+#' <= mrds 2.2.9 default \code{"P3"}). See \code{\link{varn}} and Fewster 
+#' et al (2009) for further details on these estimators.
 #'
 #' @param model ddf model object
 #' @param region.table \code{data.frame} of region records. Two columns:
@@ -182,7 +183,7 @@
 #'  length (Default: \code{1})}
 #'  \item{\code{ervar}}{encounter rate variance type (see "Uncertainty" and
 #'  \code{type} argument of \code{\link{varn}}). (Default: \code{"R2"} for
-#'  lines and \code{"P3"} for points)}
+#'  lines and \code{"P2"} for points)}
 #'}
 #'
 #' @author Jeff Laake, David L Miller
@@ -433,7 +434,7 @@ dht <- function(model, region.table, sample.table, obs.table=NULL, subset=NULL,
   # Assign default values to options
   options <- assign.default.values(options, pdelta=0.001, varflag=2,
                                    convert.units=1,
-                                   ervar=ifelse(model$meta.data$point, "P3",
+                                   ervar=ifelse(model$meta.data$point, "P2",
                                                 "R2"),
                                    areas.supplied=FALSE)
 
@@ -483,16 +484,16 @@ dht <- function(model, region.table, sample.table, obs.table=NULL, subset=NULL,
                                    levels=levels(sample.table$Sample.Label))
 
 
-  # P3 can only be used with points
-  if(options$ervar=="P3" & !model$meta.data$point){
-    stop("Encounter rate variance estimator P3 may only be used with point transects, set with options=list(ervar=...)")
+  # P2 and P3 can only be used with points
+  if((options$ervar=="P3" || options$ervar=="P2") && !model$meta.data$point){
+    stop("Encounter rate variance estimator P2 / P3 may only be used with point transects, set with options=list(ervar=...)")
   }
 
-  # switch to the P3 estimator if using points
+  # switch to the P2 estimator if using points
   if(model$meta.data$point){
     if(!(options$ervar %in% c("P2", "P3"))){
-      warning("Point transect encounter rate variance can only use estimators P2 or P3, switching to P3.")
-      options$ervar <- "P3"
+      warning("Point transect encounter rate variance can only use estimators P2 or P3, switching to P2.")
+      options$ervar <- "P2"
     }
   }
 

R/dht.se.R

@@ -45,9 +45,11 @@
 #' estimator forms given in Fewster et al (2009). For line transects:
 #' \code{"R2"}, \code{"R3"}, \code{"R4"}, \code{"S1"}, \code{"S2"},
 #' \code{"O1"}, \code{"O2"} or \code{"O3"} can be used by specifying the
-#' \code{ervar=} option (default \code{"R2"}). For point transects only the
-#' \code{"P3"} estimator may be used. See \code{\link{varn}} and Fewster et al
-#' (2009) for further details on these estimators.
+#' \code{ervar=} option (default \code{"R2"}). For points, either the 
+#' \code{"P2"} or \code{"P3"} estimator can be selected (>=mrds 2.3.0 
+#' default \code{"P2"}, <= mrds 2.2.9 default \code{"P3"}). See 
+#' \code{\link{varn}} and Fewster et al (2009) for further details 
+#' on these estimators.
 #'
 #' Exceptions to the above occur if there is only one sample in a stratum. In
 #' that case it uses Poisson assumption (\eqn{Var(x)=x}) and it assumes a known

R/mrds-package.R

@@ -45,21 +45,47 @@ NULL
 #'
 #' @name book.tee.data
 #' @docType data
-#' @format The format is: List of 4 $ book.tee.dataframe:'data.frame': 324 obs.
-#'   of 7 variables: ..$ object : num [1:324] 1 1 2 2 3 3 4 4 5 5 ...  ..$
-#'   observer: Factor w/ 2 levels "1","2": 1 2 1 2 1 2 1 2 1 2 ...  ..$
-#'   detected: num [1:324] 1 0 1 0 1 0 1 0 1 0 ...  ..$ distance: num [1:324]
-#'   2.68 2.68 3.33 3.33 0.34 0.34 2.53 2.53 1.46 1.46 ...  ..$ size : num
-#'   [1:324] 2 2 2 2 1 1 2 2 2 2 ...  ..$ sex : num [1:324] 1 1 1 1 0 0 1 1 1 1
-#'   ...  ..$ exposure: num [1:324] 1 1 0 0 0 0 1 1 0 0 ...  $ book.tee.region
-#'   :'data.frame': 2 obs. of 2 variables: ..$ Region.Label: Factor w/ 2 levels
-#'   "1","2": 1 2 ..$ Area : num [1:2] 1040 640 $ book.tee.samples
-#'   :'data.frame': 11 obs. of 3 variables: ..$ Sample.Label: num [1:11] 1 2 3
-#'   4 5 6 7 8 9 10 ...  ..$ Region.Label: Factor w/ 2 levels "1","2": 1 1 1 1
-#'   1 1 2 2 2 2 ...  ..$ Effort : num [1:11] 10 30 30 27 21 12 23 23 15 12 ...
-#'   $ book.tee.obs :'data.frame': 162 obs. of 3 variables: ..$ object : int
-#'   [1:162] 1 2 3 21 22 23 24 59 60 61 ...  ..$ Region.Label: int [1:162] 1 1
-#'   1 1 1 1 1 1 1 1 ...  ..$ Sample.Label: int [1:162] 1 1 1 1 1 1 1 1 1 1 ...
+#' @format 
+#'   A list of 4 dataframes, with the list elements named: book.tee.dataframe,
+#'   book.tee.region, book.tee.samples and book.tee.obs. 
+#'   
+#'   \strong{book.tee.dataframe} is the distance sampling data 
+#'   dataframe. Used in the call to fit the detection function in \code{ddf}.
+#'   Contains the following columns:
+#'   
+#'   \describe{
+#'   \item{object}{numeric object id}\item{observer}{factor representing observer
+#'   1 or 2}\item{detected}{numeric 1 if the animal was detected 0 otherwise}
+#'   \item{distance}{numeric value for the distance the animal was detected}
+#'   \item{size}{numeric value for the group size}\item{sex}{numeric value for
+#'   sex of animal}\item{exposure}{numeric value for exposure level 0 or 1}}
+#'   
+#'   \strong{book.tee.region}: is the region table dataframe. Used to
+#'   supply the strata areas to the \code{dht} function. Contains the following
+#'   columns:
+#'   
+#'   \describe{
+#'   \item{Region.Label}{factor giving the strata labels}
+#'   \item{Area}{numeric value giving the strata areas}}
+#'   
+#'   \strong{book.tee.samples} is the samples table dataframe to match 
+#'   the transect ids to the region ids and supply the effort. Used in the 
+#'   \code{dht} function. Contains the following columns:
+#'   
+#'   \describe{
+#'   \item{Sample.Label}{numeric giving the sample / transect labels}
+#'   \item{Region.Label}{factor giving the strata labels}
+#'   \item{Effort}{numeric value giving the sample / transect lengths}}
+#'   
+#'   \strong{book.tee.obs} is the observations table dataframe to match
+#'   the object ids in the distance data to the transect labels. Used in the 
+#'   \code{dht} function. Contains the following columns:
+#'
+#'   \describe{
+#'   \item{object}{numeric value object id}
+#'   \item{Region.Label}{factor giving the strata labels}
+#'   \item{Sample.Label}{numeric giving the sample / transect labels}}
+#'   
 #' @keywords datasets
 NULL
 
@@ -1142,10 +1168,10 @@ NULL
 #'
 #'
 #' @section Initial values:
-#' Initial (or starting) values can be set via the \code{initial} element of
-#' the \code{control} list. \code{initial} is a list itself with elements
-#' \code{scale}, \code{shape} and \code{adjustment}, corresponding to the
-#' associated parameters. If a model has covariates then the \code{scale} or
+#' Initial (or starting) values for the dsmodel can be set via the \code{initial} 
+#' element of the \code{control} list. \code{initial} is a list itself with 
+#' elements \code{scale}, \code{shape} and \code{adjustment}, corresponding to 
+#' the associated parameters. If a model has covariates then the \code{scale} or
 #' \code{shape} elements will be vectors with parameter initial values in the
 #' same order as they are specific in the model formula (using \code{showit} is
 #' a good check they are in the correct order). Adjustment starting values are
@@ -1161,21 +1187,20 @@ NULL
 #' parameter (or intercept in a covariate model) on the exponential scale, so
 #' one must \code{log} this before supplying it to \code{ddf}.
 #'
-#'
 #' @section Bounds:
-#' One can change the upper and lower bounds for the parameters. These specify
-#' the largest and smallest values individual parameters can be. By placing
-#' these constraints on the parameters, it is possible to "temper" the
+#' One can change the upper and lower bounds for the dsmodel parameters. These 
+#' specify the largest and smallest values individual parameters can be. By 
+#' placing these constraints on the parameters, it is possible to "temper" the
 #' optimisation problem, making fitting possible.
 #'
 #' Again, one uses the \code{control} list, the elements \code{upperbounds} and
 #' \code{lowerbounds}. In this case, each of \code{upperbounds} and
 #' \code{lowerbounds} are vectors, which one can think of as each of the
-#' vectors \code{scale}, \code{shape} and \code{adjustment} from the "Initial
+#' vectors \code{shape}, \code{scale} and \code{adjustment} from the "Initial
 #' values" section above, concatenated in that order. If one does not occur
 #' (e.g. no shape parameter) then it is simple omitted from the vector.
 #'
-#' @name mrds-opt
+#' @name mrds_opt
 #' @docType methods
 #' @author David L. Miller <dave@@ninepointeightone.net>
 NULL

R/varn.R

@@ -33,7 +33,7 @@
 #' Default value is \code{"R2"}, shown in Fewster et al. (2009) to have good
 #' performance for completely random designs for lines. For systematic parallel
 #' line transect designs, Fewster et al. recommend \code{"O2"}. For point
-#' transects the default is \code{"P3"} (but \code{"P2"} is also available).
+#' transects the default is \code{"P2"} (but \code{"P3"} is also available).
 #'
 #' For the systematic estimators, pairs are assigned in the order they are
 #' given in the \code{lengths} and \code{groups} vectors.

R/zzz.R

@@ -7,11 +7,13 @@
 
   hello <- paste0("This is mrds ",version,"\nBuilt: ",built)
 
+  varest.info <- "**Change to default variance estimator for point transects. The default encounter rate variance estimator for point transects is now 'P2' (changed from 'P3'). See 'Uncertainty' section of ?dht for more information.**"
+
   mcds.info <- ifelse(system.file("MCDS.exe", package="mrds") == "",
                       "MCDS.exe not detected, single observer analyses will only be run using optimiser in mrds R library. See ?MCDS for details.",
                       "MCDS.exe detected, by default single observer analyses will utilise both the mrds R optimiser and the MCDS.exe fortran optimiser to achieve the best fit. See ?ddf and ?MCDS for details.")
 
-  hello <- paste0(hello, "\n", mcds.info)
+  hello <- paste0(hello, "\n\n", varest.info, "\n\n", mcds.info)
 
   packageStartupMessage(hello)
 }