md_optimize: Optimize population sample size and sampling parameters

Description

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

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

Usage

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

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.
minimum_population_sample_size: Integer. Minimum sample size achieving the threshold (or maximum evaluated if sample_size_achieved is FALSE).

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. Error threshold (e.g. 0.05 for 5%) to display as a reference in the plot.
verbose: Logical. If TRUE (default), prints a summary of the convergence check to the console.
trace: Logical; if TRUE (default), prints progress and timing messages 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().
plot: Logical. If TRUE, displays a diagnostic plot of the final results.
...: Additional arguments used internally.

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.

Examples

Run this code

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