Performs hierarchical meta-analyses on animal movement simulation outputs 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 (via ratios) if specified.
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.
Optionally, the function performs resampling by randomly drawing multiple sets of individuals from the population, allowing assessment of estimate variability as sample size increases or as individuals are resampled. This approach helps quantify the precision and reliability of estimates under different sampling scenarios.
Internally, this function wraps run_meta_resamples() to fit
hierarchical models without resampling for initial evaluation.
run_meta(
rv,
set_target = c("hr", "ctsd"),
subpop = FALSE,
trace = FALSE,
iter_step = 2,
...
)A data frame summarizing all outputs for each target, population sample size, and group (if specified) for a single draw (sample). Columns include:
Research target, e.g., hr and/or ctsd.
Number of individuals in the sample.
Sample index (for repeated draws).
True, expected value.
Point estimate.
Lower confidence interval.
Upper confidence interval.
Relative error.
Lower CI for relative error.
Upper CI for relative error.
True group ratio (A/B), if subpop=TRUE.
Estimated group ratio.
Lower CI for estimated group ratio.
Upper CI for estimated group ratio.
Logical; whether estimate overlaps with the truth.
Logical; TRUE if grouped.
Group label (All, A, B).
Logical; was a subpopulation detected?
A named list containing simulation inputs, settings, and group assignments. Must not be NULL.
Character vector specifying the target metrics. Options are "hr" (for home range area) and/or "ctsd" (for movement speed). Defaults to c("hr", "ctsd").
Logical; if TRUE, analyzes population-level inferences
by subpopulations/groups (e.g., males vs. females). Requires group
assigments in rv.
Logical; if TRUE, prints progress messages. Default is FALSE.
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.
Additional arguments for advanced control:
Logical. If TRUE, runs the meta-analysis
only at the maximum population sample size. Skips all
intermediate sample sizes.
Integer. Sets a user-defined maximum sample size to use in the resampling sequence. Overrides the default, which uses all available individuals.
Integer. Specifies exact sample size to use. Overrides automatic sequence generation. Accepts a single value.
Logical. If TRUE, automatically generates
an informative and non-redundant sequence of sample sizes
for better plot readability and runtime efficiency.
List (Optional). Supplies precomputed input
objects, generated via .build_meta_objects().
run_meta_resamples(),
ctmm::akde(),
ctmm::speed()