Optimize sampling parameters and population sample size

Repeatedly simulates movement datasets across a range of candidate population sample sizes to identify the minimal sample size and associated sampling parameters (i.e., duration, sampling interval) needed to achieve estimates for key movement and space-use metrics (e.g., home range area, speed) within the specified relative error threshold.

The function quantifies estimation error for each metric and sample size, evaluating which population sample size reliably meet target thresholds, and reports final recommendations.

Usage

md_optimize(
  obj,
  n_replicates = 10,
  error_threshold = 0.05,
  plot = FALSE,
  verbose = TRUE,
  parallel = FALSE,
  ncores = parallel::detectCores(),
  trace = TRUE,
  ...
)

Arguments

obj: A movement design input object (see md_prepare() or md_configure()).
n_replicates: Integer. Number of simulation replicates at each candidate sample size.
error_threshold: Numeric. Upper limit of the relative error in estimation (e.g., 0.05 for 5%) deemed acceptable by the user. The function will attempt to find sampling parameters and sample sizes that keep errors below this threshold.
plot: Logical. If TRUE, displays a diagnostic plot of the final results.
verbose: Logical. If TRUE (default), prints a summary of the convergence check to the console.
parallel: Logical; if TRUE, enables parallel processing. Default is FALSE.
ncores: Integer; number of CPU cores to use for parallel processing. Defaults to all available cores detected by parallel::detectCores().
trace: Logical; if TRUE (default), prints progress and timing messages to the console.
...: Reserved for internal use.

Value

A list of class movedesign_report containing:

summary: Data frame of summary statistics for each replicate, sample size, and metric.
error_threshold: Numeric. The error threshold used.
sampling_duration: Character string. Final sampling duration.
sampling_interval: Character string. Final sampling interval.
sample_size_achieved: Logical. Indicates if convergence was achieved and the threshold met.
init_m: Integer. Maximum sample size evaluated.
minimum_m: Integer. Minimum sample size achieving the threshold.

Details

The function iteratively runs movement design simulations for increasing population sample sizes (m), evaluating error for each replicate and metric via meta-analyses. Convergence is checked using the error threshold and stability of cumulative mean error. The function stops when a sample size meets all criteria or the maximum population sample size is reached. Results can be visualized using if plot = TRUE.

Note

Some biologgers inherently involve a trade-off between fix frequency and battery life. Shorter intervals between location fixes offer higher temporal resolution but reduce deployment duration due to increased power consumption. In contrast, longer deployments require less frequent sampling to conserve battery.

This trade-off makes it challenging to estimate multiple metrics with differing data needs: high-resolution data (shorter intervals) improve speed estimation, while extended deployments (longer durations) are vital for accurate home range area estimates. A sampling design that minimizes error for one metric may increase error for another.

Researchers facing these constraints should consider prioritizing a single research target (e.g., either home range area or speed), or use stratified designs to balance data needs across individuals.

Examples

if(interactive()) {
  obj <- md_configure(data = buffalo,
                      models = models)
                      
  out <- md_optimize(tmp,
                     error_threshold = 0.05,
                     plot = TRUE)
}