Skip to contents

Running hierarchical models (with resampling)

Source: R/fct_meta.R
run_meta_resamples.Rd

This function performs meta-analyses on simulated animal tracking data, to estimate key movement metrics, such as mean home range area and/or mean movement speed for a sampled population. The function can also compare these metrics between two groups if specified.

When resampling is enabled, the function repeatedly draws random subsets of individuals from the available population to simulate how parameter estimates behave across varying population sample sizes. This resampling allows users to assess estimate variability as sample size increases or as individuals are resampled. For example, it can reveal if the mean home range area converges as more individuals are added to the sampled population.

This approach helps quantify the robustness and precision of estimated parameters under different sampling scenarios.

The function leverages core methods from the ctmm package:

  • ctmm::akde(): Computes home range areas using the Autocorrelated Kernel Density Estimator (AKDE), which explicitly accounts for the autocorrelation in animal movement data to produce statistically robust space-use estimates.

  • ctmm::speed(): Computes Continuous-Time Speed and Distance (CTSD) estimates, providing biologically meaningful summaries of movement speed, which is proportional to distance traveled. These methods allow for robust comparisons across individuals, groups, and resampling scenarios.

Usage

run_meta_resamples(
  rv,
  set_target = c("hr", "ctsd"),
  subpop = FALSE,
  random = FALSE,
  max_draws = 100,
  iter_step = 2,
  trace = FALSE,
  ...
)

Arguments

rv

A named list containing simulation inputs, settings, and group assignments. Must not be NULL.

set_target

Character vector specifying the target metrics. Options are "hr" (for home range area) and/or "ctsd" (for movement speed). Defaults to c("hr", "ctsd").

subpop

Logical; if TRUE, analyzes population-level inferences by subpopulations/groups (e.g., males vs. females). Requires group assigments in rv.

random

Logical; if TRUE, performs random sampling of individuals using different combinations (up to max_draws).

max_draws

Integer; maximum number of random draws per combination size when random=TRUE. Ignored if random=FALSE.

iter_step

Integer. Step size used to increment the number of individuals sampled in each iteration. For example, if iter_step = 2, the function will evaluate sample sizes of 2, 4, 6, etc., up to the maximum population sample size. Defaults to 2.

trace

Logical; if TRUE, prints progress messages. Default is FALSE.

...

Additional arguments for advanced control:

.only_max_m

Logical. If TRUE, runs the meta-analysis only at the maximum population sample size. Skips all intermediate sample sizes.

.max_m

Integer. Sets a user-defined maximum sample size to use in the resampling sequence. Overrides the default, which uses all available individuals.

.m

Integer. Specifies exact sample size to use. Overrides automatic sequence generation. Accepts a single value.

.automate_seq

Logical. If TRUE, automatically generates an informative and non-redundant sequence of sample sizes for better plot readability and runtime efficiency.

.lists

List (Optional). Supplies precomputed input objects, generated via .build_meta_objects().

Value

A data frame summarizing all outputs for each target, population sample size, sample, and group (if specified). Columns include:

type

Research target, e.g., "hr" or "ctsd".

m

Number of individuals in the sample.

sample

Sample index (for repeated draws).

truth

True value.

est

Point estimate.

lci

Lower confidence interval.

uci

Upper confidence interval.

error

Relative error.

error_lci

Lower CI for relative error.

error_uci

Upper CI for relative error.

ratio_truth

True group ratio (A/B), if subpop=TRUE.

ratio_est

Estimated group ratio.

ratio_lci

Lower CI for estimated group ratio.

ratio_uci

Upper CI for estimated group ratio.

overlaps

Logical; whether estimate overlaps with the truth.

is_grouped

Logical; TRUE if grouped.

group

Group label ("All", "A", "B").

subpop_detected

Logical; was a subpopulation detected?

See also

akde, speed,

Author

Inês Silva i.simoes-silva@hzdr.de

Examples

if(interactive()) {
   run_meta_resamples(rv, set_target = "hr")
}