Distance (version 1.0.3)

bootdht: Bootstrap uncertainty estimation for distance sampling models

Description

Performs a bootstrap for simple distance sampling models using the same data structures as dht. Note that only geographical stratification as supported in dht is allowed.

Usage

bootdht(
  model,
  flatfile,
  resample_strata = FALSE,
  resample_obs = FALSE,
  resample_transects = TRUE,
  nboot = 100,
  summary_fun = bootdht_Nhat_summarize,
  convert.units = 1,
  select_adjustments = FALSE,
  sample_fraction = 1,
  progress_bar = "base",
  cores = 1
)

Arguments

model

a model fitted by ds or a list of models

flatfile

Data provided in the flatfile format. See flatfile for details.

resample_strata

should resampling happen at the stratum (Region.Label) level? (Default FALSE)

resample_obs

should resampling happen at the observation (object) level? (Default FALSE)

resample_transects

should resampling happen at the transect (Sample.Label) level? (Default TRUE)

nboot

number of bootstrap replicates

summary_fun

function that is used to obtain summary statistics from the bootstrap, see Summary Functions below. By default bootdht_Nhat_summarize is used, which just extracts abundance estimates.

convert.units

conversion between units for abundance estimation, see "Units", below. (Defaults to 1, implying all of the units are "correct" already.) This takes precedence over any unit conversion stored in model.

select_adjustments

select the number of adjustments in each bootstrap, when FALSE the exact detection function specified in model is fitted to each replicate. Setting this option to TRUE can significantly increase the runtime for the bootstrap. Note that for this to work model must have been fitted with adjustment!=NULL.

sample_fraction

what proportion of the transects was covered (e.g., 0.5 for one-sided line transects).

progress_bar

which progress bar should be used? Default "base" uses txtProgressBar, "none" suppresses output, "progress" uses the progress package, if installed.

cores

number of CPU cores to use to compute the estimates. See "Parallelization" below.

Summary Functions

The function summary_fun allows the user to specify what summary statistics should be recorded from each bootstrap. The function should take two arguments, ests and fit. The former is the output from dht2, giving tables of estimates. The latter is the fitted detection function object. The function is called once fitting and estimation has been performed and should return a data.frame. Those data.frames are then concatenated using rbind. One can make these functions return any information within those objects, for example abundance or density estimates or the AIC for each model. See Examples below.

Model selection

Model selection can be performed on a per-replicate basis within the bootstrap. This has three variations:

1. when select_adjustments is TRUE then adjustment terms are selected by AIC within each bootstrap replicate (provided that model had the order and adjustment options set to non-NULL.

2. if model is a list of fitted detection functions, each of these is fitted to each replicate and results generated from the one with the lowest AIC.

3. when select_adjustments is TRUE and model is a list of fitted detection functions, each model fitted to each replicate and number of adjustments is selected via AIC. This last option can be extremely time consuming.

Parallelization

If cores>1 then the parallel/doParallel/foreach packages will be used to run the computation over multiple cores of the computer. To use this component you need to install those packages using: install.packages(c("foreach", "doParallel")) It is advised that you do not set cores to be greater than one less than the number of cores on your machine.

It is also hard to debug any issues in summary_fun so it is best to run a small number of bootstraps first in parallel to check that things work. On Windows systems summary_fun does not have access to the global environment when running in parallel, so all computations must be made using only its ests and fit arguments (i.e., you can not use R objects from elsewhere in that function, even if they are available to you from the console).

See Also

summary.dht_bootstrap for how to summarize the results, bootdht_Nhat_summarize for an example summary function.

Examples

# NOT RUN {
# fit a model to the minke data
data(minke)
mod1 <- ds(minke)

# summary function to save the abundance estimate
Nhat_summarize <- function(ests, fit) {
  return(data.frame(Nhat=ests$individuals$N$Estimate))
}

# perform 5 bootstraps
bootout <- bootdht(mod1, flatfile=minke, summary_fun=Nhat_summarize, nboot=5)

# obtain basic summary information
summary(bootout)
# }