md_optimize: Optimize population sample size and sampling parameters

In movedesign: Study Design Toolbox for Movement Ecology Studies

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,
  ...
)

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.

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).

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.

See Also

md_prepare(), md_configure()

Examples

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

movedesign documentation built on Aug. 8, 2025, 6:47 p.m.