Title:	Study Design Toolbox for Movement Ecology Studies
Version:	0.3.2
Maintainer:	Inês Silva <i.simoes-silva@hzdr.de>
Description:	Toolbox and 'shiny' application to help researchers design movement ecology studies, focusing on two key objectives: estimating home range areas, and estimating fine-scale movement behavior, specifically speed and distance traveled. It provides interactive simulations and methodological guidance to support study planning and decision-making. The application is described in Silva et al. (2023) <doi:10.1111/2041-210X.14153>.
License:	GPL (≥ 3)
URL:	https://ecoisilva.github.io/movedesign/, https://ecoisilva.r-universe.dev/movedesign
BugReports:	https://github.com/ecoisilva/movedesign/issues
Depends:	R (≥ 3.5.0)
Imports:	bayestestR, bsplus, combinat, config (≥ 0.3.1), crayon, ctmm (≥ 0.6.1), data.table, dplyr, fontawesome, gdtools, ggiraph, ggplot2, ggpubr, ggtext, golem (≥ 0.3.2), grDevices, gsl, lubridate, parallel, parsedate, quarto, reactable, rintrojs, rlang, scales, shiny (≥ 1.7.1), shinyalert, shinybusy, shinydashboard, shinydashboardPlus, shinyFeedback, shinyjs, shinyWidgets, stats, stringr, terra, tidyr, utils, viridis
Suggests:	knitr, rmarkdown, shinytest2
VignetteBuilder:	knitr, quarto
Config/testthat/edition:	3
Encoding:	UTF-8
Language:	en-US
LazyData:	true
RoxygenNote:	7.3.2
NeedsCompilation:	no
Packaged:	2025-07-29 15:22:03 UTC; simoes48
Author:	Inês Silva [cre, aut, cph]
Repository:	CRAN
Date/Publication:	2025-07-30 16:30:09 UTC

movedesign: Study design of movement ecology studies

Description

The movedesign package contains an R shiny application that assists researchers in designing movement ecology studies.

Author(s)

Maintainer: Inês Silva i.simoes-silva@hzdr.de (ORCID) [copyright holder]

See Also

Useful links:

• https://ecoisilva.github.io/movedesign/

• https://ecoisilva.r-universe.dev/movedesign

• Report bugs at https://github.com/ecoisilva/movedesign/issues

Estimate home range from simulated movement data

Description

Estimates home range areas for each simulated movement dataset using the Autocorrelated Kernel Density Estimator (AKDE) via ctmm::akde(). This function is intended for use within simulation workflows where home range calculations are needed for each simulated individual.

Usage

estimate_hr(rv)

Arguments

Value

A named list of ctmm objects, each representing an AKDE home range estimate for the corresponding simulation. If AKDE estimation fails for a simulation (e.g., due to poor model fit or data issues), the result for that simulation will be NULL.

Note

This function is intended for internal use and may assume inputs follow specific structure and constraints not referenced explicitly.

See Also

ctmm::akde() for details on home range estimation.

Estimate movement speed for simulated movement data

Description

Calculates continuous-time speed and distance (CTSD) for each simulated movement dataset using its corresponding fitted movement model with ctmm::speed(). This function is designed for simulation workflows where speed metrics are required for each simulated individual.

Usage

estimate_speed(rv)

Arguments

Value

A named list of speed estimates (ctmm objects), with one entry per simulation.For any simulation where speed estimation fails (e.g., due to model fitting issues or incompatible data), NULL is returned for that entry and omitted from the final output.

Note

This function is intended for internal use and may assume inputs follow specific structure and constraints not referenced explicitly.

See Also

ctmm::speed() for details on speed estimation.

Fit continuous-time movement models

Description

This function fits continuous-time movement models to simulated location data using the ctmm package. It estimates movement parameters for each simulated trajectory, optionally running in parallel for efficiency. It supports both home range and speed estimation workflows.

Usage

fitting_model(obj, set_target = c("hr", "ctsd"), ...)

Arguments

Details

The function generates initial parameter estimates for each dataset using ctmm::ctmm.guess(). If the data includes simulated location error, it uses an error model accordingly. When .check_sampling is TRUE, it compares the sampling duration and interval against optimal thresholds derived from the provided autocorrelation timescales. Models are fitted using ctmm::ctmm.select(), which performs model selection to find the best-fit movement process. If .rerun is enabled, the function identifies simulations with effective sample sizes below 0.1 and attempts to reselect models for those. Finally, all fitted models are recentered to (⁠0, 0⁠) for downstream consistency.

The following arguments can be supplied via ...:

• .dur: A list with elements value (numeric) and unit (string), specifying the maximum study duration. Example: list(value = 2, unit = "months").

• .dti: A list with elements value (numeric) and unit (string), specifying the intended sampling interval. Example: list(value = 1, unit = "day").

• .tau_p: A list of position autocorrelation timescales. Optional, but required if .check_sampling = TRUE.

• .tau_v: A list of velocity autocorrelation timescales. Optional, but required if .check_sampling = TRUE.

• .error_m: A numeric value specifying location error in meters (used for simulation).

• .check_sampling: Logical; if TRUE, checks whether the sampling schedule meets minimum requirements for reliable model fitting via ctmm::ctmm.fit(). This feature is experimental and may change in future versions.

• .rerun: Logical; if TRUE, re-runs model selection when simulations result in very low effective sample sizes, to avoid convergence issues.

• .parallel: Logical; if TRUE, enables parallel computation.

• .trace: Logical; if TRUE, print progress and timing messages to the console.

Value

A list of fitted movement models (class ctmm), one per simulation. Each model is recentered to the origin (x = 0, y = 0).

Note

This function is intended for internal use and may assume inputs follow specific structure and constraints not referenced explicitly.

See Also

ctmm::ctmm.guess(), ctmm::ctmm.select()

Fix rates of animal tracking devices.

Description

A dataset listing typical GPS fix rates for animal tracking devices. Useful for selecting typical sampling schedules in wildlife tracking projects.

Usage

fixrates

Format

A data.frame with 40 rows and 7 variables:

dti_notes

Human-readable fix schedule, e.g., "1 fix every month". Helps interpret sampling intervals in practical terms.

dti

Sampling interval in seconds, i.e., time between consecutive location fixes.

frq

Sampling frequency in seconds, i.e., how often a fix occurs (inverse of dti).

frq_hrs

Sampling frequency in hours, offering a more intuitive unit for comparison.

highlighted

Logical. TRUE if the fix rate is commonly used in animal tracking studies. Useful for identifying standard settings.

...

Assess output convergence in simulation outputs

Description

Evaluates whether the cumulative mean of a tracked error metric in simulation outputs has stabilized, indicating convergence. This function helps determine if repeated simulations or resampling have produced stable estimates, which is critical for reliable inference in animal movement projects.

Use this function after running md_run() or md_replicate() to check the reliability of outputs before further interpretation or reporting.

Usage

md_check(
  obj,
  m = NULL,
  tol = 0.05,
  n_converge = 10,
  plot = TRUE,
  pal = c("#007d80", "#A12C3B")
)

Arguments

Details

The cumulative mean of error is calculated, and the absolute changes over the last n_converge steps are inspected. If all are below the specified tolerance, convergence is declared.

If plot = TRUE, a plot is shown of absolute stepwise change in the cumulative mean, with a shaded region indicating the convergence threshold, aiding visual assessment.

Value

An object of class "movedesign_check" with the following elements:

has_converged

Logical scalar indicating whether convergence was achieved.

recent_deltas

Numeric vector of absolute changes in cumulative mean over the last n_converge steps.

max_delta

Maximum absolute change among the last steps.

tolerance

Numeric, the input tolerance tol.

n_converge

Integer, the input n_converge.

variable

Character. Name of the variable checked.

recent_cummean

Numeric vector. The last cumulative means checked.

See Also

md_run(), md_replicate()

Examples

if(interactive()) {
  # After running a simulation or resampling:
  md_check(output, tol = 0.05, n_converge = 10)
}

Interactively configure movement design setup

Description

Guides the user to assign each argument required for a movement design workflow, including species label and key simulation settings. Users may choose to set a specific population sample size (number of animals tagged/to be tagged) or optimize the population sample size considering a specific analytical target.

Usage

md_configure(data, models = NULL)

Arguments

Details

The argument data is required and must be supplied directly (as a list of telemetry objects, obtained from ctmm::as.telemetry()). The argument models is optional, and if omitted, models will be fitted automatically.

Value

An object of class movedesign_input (and movedesign). This is a structured S3 list containing all validated inputs, model fits, and derived parameters for the study design workflow.

See Also

md_prepare()

Examples

if(interactive()) {
  data(buffalo)
  md_params <- md_configure(data = buffalo)
}

Merge multiple simulation outputs

Description

Merges the results of multiple simulation runs, each produced by md_run(), into a single unified movedesign_output object. This is especially useful when running replicate simulations for power analyses, sensitivity testing, or batch processing. Merging allows you to aggregate all simulated individuals, outputs, and related metadata, enabling streamlined downstream analyses.

Usage

md_merge(...)

Arguments

Value

A single movedesign_output object that contains all merged simulation outputs and inherits metadata from the first input object. The output includes:

• Merged list of simulated individuals (simList),

• Merged list of fitted models (simfitList),

• Merged list of seeds used for each simulation replicate (seedList),

• Optionally, merged home range (akdeList) and speed (ctsdList) outputs,

• Relevant metadata describing the study design parameters.

See Also

md_prepare, md_run

Examples

if (interactive()) {
  input <- md_prepare(
    data = buffalo,
    models = models,
    species = "buffalo",
    n_individuals = 5,
    dur = list(value = 1, unit = "month"),
    dti = list(value = 1, unit = "day"),
    add_individual_variation = TRUE,
    grouped = FALSE,
    set_target = "hr",
    which_meta = "mean"
  )

  output1 <- md_run(input)
  output2 <- md_run(input)

  merged <- md_merge(output1, output2)
}

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

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

Visualize study design outputs

Description

Produces a publication-ready density plot showing the distribution of relative error estimates from study design simulations. The plot highlights the mean and a shaded credible interval (CI) region, following the computation of credible intervals as implemented in bayestestR::ci(). If groups are present, density curves for each group are overlaid for comparison, using customizable colors.

This function is typically used after running md_replicate(), providing a visual diagnostic of simulation results.

Usage

md_plot(
  obj,
  ci = 0.95,
  method = "HDI",
  pal = c("#007d80", "#A12C3B"),
  m = NULL
)

Arguments

Details

This plot helps users assess the reliability of simulation outputs by visualizing the distribution of relative errors. When multiple groups are simulated, the plot enables direct visual comparison of performance across groups. If credible intervals cannot be calculated, a warning is issued and only the density curves are displayed.

It is strongly recommended to use md_check() to assess whether the distributions shown here have stabilized. Checking for convergence ensures that the summary statistics and uncertainty estimates depicted in the plot are reliable and not unduly influenced by too few replicates or ongoing variability. Running md_check() helps you determine if additional simulation replicates are needed to achieve stable inference in your design evaluation.

Value

A ggplot object showing:

• Density curve(s) of the relative error distribution.

• Shaded region for the central credible interval.

• Vertical dashed lines at mean(s).

• Overlaid densities if multiple groups are present.

• Percent-formatted x-axis for interpretation.

This object can be further customized with additional ggplot2 layers if needed.

See Also

md_replicate(), md_check() for convergence diagnostics, and refer to bayestestR::ci() for details on credible interval computation and interpretation.

Examples

if (interactive()) {
  input <- md_prepare(
    data = buffalo,
    models = models,
    species = "buffalo",
    n_individuals = 5,
    dur = list(value = 1, unit = "month"),
    dti = list(value = 1, unit = "day"),
    add_individual_variation = TRUE,
    grouped = TRUE,
    set_target = "hr",
    which_meta = "mean"
  )

  output <- md_replicate(input, n_replicates = 20)

  # Plot with 80% credible intervals:
  md_plot(output, ci = 0.80, method = "HDI")
}

Preview plot for movedesign workflow outputs (single replicate)

Description

Generates a quick visualization of relative error for home range or movement speed estimation from a single replicate of a movedesign workflow. This functions shows preliminary outputs only and should not be used to evaluate study design.

Use the output of md_run() (a movedesign_preprocess object). Users should run md_replicate() for a full assessment.

Usage

md_plot_preview(obj, error_threshold = 0.05, pal = c("#007d80", "#A12C3B"))

Arguments

Details

For robust results and credible intervals, use md_replicate().

Value

A ggplot object displaying relative error by population sample size, with point estimate and confidence intervals for mean estimates, and horizontal error threshold lines.

See Also

md_run(), md_replicate()

Examples

if (interactive()) {
  input <- md_prepare(
    data = buffalo,
    models = models,
    species = "buffalo",
    n_individuals = 5,
    dur = list(value = 1, unit = "month"),
    dti = list(value = 1, unit = "day"),
    add_individual_variation = TRUE,
    grouped = TRUE,
    set_target = "hr",
    which_meta = "mean"
  )

  output <- md_run(input)
  md_plot_preview(output, error_threshold = 0.05)
}

Prepare movement study design inputs

Description

Prepares, validates, and organizes all required inputs and parameters for evaluating the study design of animal movement projects. This function checks data inputs, fits or verifies movement models, extracts key parameters, and consolidates all settings in a structured object for easy and reproducible downstream use.

Usage

md_prepare(
  species = NULL,
  data,
  models = NULL,
  n_individuals = NULL,
  dur = NULL,
  dti = NULL,
  set_target = c("hr", "ctsd"),
  which_meta = "mean",
  add_individual_variation = FALSE,
  groups = NULL,
  parallel = FALSE
)

Arguments

Details

This function is designed to streamline and standardize the preparation of input data and study design parameters for simulation-based movement ecology analyses. It performs the following key steps:

• Validates that data is a non-empty list of telemetry objects with metadata and location records.

• Fits movement models to each individual if not supplied.

• Checks supplied movement models for validity.

• Extracts parameters (e.g., sigma, tau_p, tau_v) for simulation.

• Gathers settings (sample size, duration, sampling, grouping) into a single object.

Value

An object of class movedesign_input (and movedesign). This is a structured S3 list containing all validated inputs, model fits, and derived parameters for the study design workflow.

The returned object includes:

• design: A movedesign object with all study settings and metadata.

• data: The original or validated list of telemetry objects.

• fitList: List of fitted movement models for each individual.

• meanfitList: List of population or group-level mean models.

• sigma, tau_p, tau_v: Movement parameters extracted from data provided for downstream simulations.

• mu: List of mean locations.

• groups: Group structure if specified, otherwise NULL.

• Other slots describing population sample size, sampling duration, sampling interval, targets, and workflow options.

This object is ready for use in downstream movedesign output and diagnostic functions.

Examples

if(interactive()) {
  data(buffalo)
  input <- md_prepare(
    data = buffalo,
    models = models,
    species = "buffalo",
    n_individuals = 5,
    dur = list(value = 1, unit = "month"),
    dti = list(value = 1, unit = "day"),
    add_individual_variation = TRUE,
    set_target = "hr",
    which_meta = "mean")
 summary(input)
}

Replicate study design and aggregate simulation outputs

Description

Runs the specified movement study design multiple times and aggregates outputs and summary statistics across independent replicates. This enables sensitivity analyses and quantifies variability arising from random sampling, especially when individual-level variation is enabled (i.e., add_individual_variation = TRUE in md_prepare()). Replication helps assess how stochasticity and design choices impact simulation inference.

Usage

md_replicate(
  obj,
  n_replicates,
  verbose = FALSE,
  trace = TRUE,
  parallel = FALSE,
  ncores = parallel::detectCores()
)

Arguments

Details

Each replicate runs independently using the same study design object but with a unique random seed to ensure independence. Results from all replicates are merged using md_merge(), and summary statistics combine into a single data.table for convenient downstream analyses and evaluation. Parallel processing can significantly reduce runtime when running many replicates; use ncores to specify the number of CPU cores used. If function is interrupted (e.g., Ctrl+C), it returns results from all completed replicates up to that point.

Value

A list of class movedesign_output with two elements:

• data: A list containing merged simulation outputs from all replicates.

• summary: A data.table summarizing key statistics for each replicate.

See Also

md_prepare(), md_run(), md_merge()

Examples

if (interactive()) {
  input <- md_prepare(
    data = buffalo,
    models = models,
    species = "buffalo",
    n_individuals = 5,
    dur = list(value = 1, unit = "month"),
    dti = list(value = 1, unit = "day"),
    add_individual_variation = TRUE,
    grouped = FALSE,
    set_target = "hr",
    which_meta = "mean"
  )

  output <- md_replicate(input, n_replicates = 5)
}

Run study design workflow

Description

Executes a complete simulation and analysis workflow for an animal movement study design prepared using md_prepare(). This function simulates telemetry data, fits movement models, estimates home ranges and/or movement speeds, and stores all results in the returned object. Progress and timing messages are printed by default.

Usage

md_run(design, trace = TRUE)

Arguments

Details

This function ensures reproducibility by saving all random seeds and intermediate results. Progress and timing messages help track the simulation workflow.

Typical workflow:

• Prepare a study design with md_prepare().

• Run all simulations and analyses with md_run().

• Summarize or plot outputs from the returned object.

Value

An updated movedesign object (subclass movedesign_preprocess) containing all simulation and outputs components:

• simList: List of simulated telemetry datasets, one per individual.

• seedList: List of random seeds used for reproducibility.

• simfitList: List of fitted movement models for each simulation.

• akdeList: List of home range (AKDE) estimates, present if the hr target was listed in set_target.

• ctsdList: List of continuous-time speed and distance (CTSD) estimates, present if the ctsd target was listed in set_target.

See Also

md_prepare(), md_replicate(), md_check(), md_plot()

Examples

if(interactive()) {
input <- md_prepare(
  data = buffalo,
  models = models,
  species = "buffalo",
  n_individuals = 5,
  dur = list(value = 1, unit = "month"),
  dti = list(value = 1, unit = "day"),
  add_individual_variation = TRUE,
  set_target = "hr",
  which_meta = "mean"
)
output <- md_run(input)
}

Create a movedesign_input object for simulation workflows

Description

Constructs an S3 object of class movedesign_input, encapsulating all parameters and metadata required for a simulation-based study design. This object includes elements such as number of individuals (population sample size), study duration, sampling interval, movement models, grouping structure (if specified), and estimation targets. The standardized movedesign_input object is the expected input for downstream movedesign functions.

Use md_prepare() to construct a complete study design input object, which can then be passed to functions like md_run() and md_replicate().

Usage

movedesign_input(design)

Arguments

Value

An object of class movedesign_input and movedesign, which contains all input parameters and metadata required for a movedesign workflow.

See Also

md_prepare()

Create a movedesign_output object to store simulation outputs

Description

Constructs an S3 object of class movedesign_output that stores the outputs and summaries from a specific simulation workflow. The resulting object bundles all relevant metadata from the original study design (inputs), simulation outputs (e.g., home range or speed estimates), and post-processing summaries (e.g., errors, credible intervals).

The movedesign_output object is returned by simulation functions like md_run() or md_replicate(), and acts as the primary data structure for downstream analyses and visualization via functions such as md_plot() or md_check().

Usage

movedesign_output(input)

Value

An S3 object of class movedesign_output containing simulation outputs, summaries, and associated metadata.

See Also

md_run(), md_replicate(), md_check(), md_plot()

Create a movedesign_preprocess object for preprocessed results

Description

Creates an S3 object of class movedesign_preprocess to store preprocessing steps or outputs during a movedesign workflow.

Usage

movedesign_preprocess(input)

Arguments

Value

An object of class movedesign_preprocess and movedesign.

See Also

md_run()

Table of movement processes.

Description

Lists all continuous-time movement process models in ctmm. Each row is a different movement model applicable for animal movement.

Usage

movmods

Format

A data.frame with 5 rows and 6 variables:

name

Full descriptive name of the model (e.g., "Ind. Ident. Distr. (IID)"). Used throughout ctmm. See reference for more details on each model and their properties.

name_short

Abbreviated name, used where space is limited.

tau_p

Logical. TRUE if the model includes the position autocorrelation timescale (i.e., home range crossing time).

tau_v

Logical. TRUE if the model includes the velocity autocorrelation timescale (i.e., directional persistence).

hrange

Logical; TRUE if the model supports range residency, meaning the animal is likely to remain within a bounded area or "home range" instead of expanding indefinitely.

pars

Character string summarizing which autocorrelation parameters (e.g., tau_p, tau_v) the model estimates. Shown in HTML for documentation.

...

References

• Calabrese et al. (2016). ctmm: an R package for analyzing animal relocation data as a continuous-time stochastic process. Methods in Ecology and Evolution, 7(9), 1124-1132 doi:10.1111/2041-210X.12559.

• Silva et al. (2022). Autocorrelation‐informed home range estimation: A review and practical guide. Methods in Ecology and Evolution, 13(3), 534-544 <10.1111/2041-210X.13786>.

Construct a movedesign S3 object

Description

A generic internal constructor for creating S3 objects representing different stages of a "movedesign" workflow, such as input, preprocessing, simulation, output, diagnostics, and plots.

Usage

new_movedesign(x, subclass, ...)

Arguments

Value

An object of class subclass and movedesign.

Print method for movedesign_check objects

Description

Print method for movedesign_check objects

Usage

## S3 method for class 'movedesign_check'
print(x, ...)

Arguments

Print method for movedesign_input

Description

Print method for movedesign_input

Usage

## S3 method for class 'movedesign_input'
print(x, ...)

Arguments

Print method for movedesign_output

Description

Print method for movedesign_output

Usage

## S3 method for class 'movedesign_output'
print(x, ...)

Arguments

Print method for movedesign_preprocess

Description

Print method for movedesign_preprocess

Usage

## S3 method for class 'movedesign_preprocess'
print(x, ...)

Arguments

Print method for movedesign_report objects

Description

Print method for movedesign_report objects

Usage

## S3 method for class 'movedesign_report'
print(x, ...)

Arguments

Run movedesign R Shiny application

Description

Run movedesign R Shiny application

Usage

run_app(
  onStart = NULL,
  options = list(),
  enableBookmarking = NULL,
  uiPattern = "/",
  ...
)

Arguments

Value

No return value. This function is called for its side effects.

Running hierarchical models

Description

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.

Usage

run_meta(
  rv,
  set_target = c("hr", "ctsd"),
  subpop = FALSE,
  trace = FALSE,
  iter_step = 2,
  ...
)

Arguments

Value

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

type

Research target, e.g., hr and/or ctsd.

m

Number of individuals in the sample.

sample

Sample index (for repeated draws).

truth

True, expected 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?

Note

This function is intended for internal use and may assume inputs follow specific structure and constraints not referenced explicitly.

See Also

run_meta_resamples(), ctmm::akde(), ctmm::speed()

Running LOOCV on hierarchical model outputs

Description

Performs Leave-One-Out Cross-Validation (LOOCV) on hierarchical model outputs to assess the influence of individual simulated animals on population-level estimates. Supports analyses with or without groups.

In each iteration, the function removes one individual, refits the hierarchical model to the remaining dataset, and recalculates the target population-level estimates. This process is repeated until every individual has been excluded once.

This approach provides insight into how sensitive overall conclusions are to specific individuals. This helps identify influential individuals and assess robustness.

Usage

run_meta_loocv(
  rv,
  set_target = c("hr", "ctsd"),
  subpop = FALSE,
  trace = FALSE,
  ...
)

Arguments

Value

A data frame containing summarized simulation outputs.

Author(s)

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

Examples

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

Running hierarchical models (with resampling)

Description

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

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?

Author(s)

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

See Also

akde, speed,

Examples

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

Simulate movement data from continuous-time movement models

Description

Generates simulated animal movement tracks based on continuous-time movement models using ctmm::simulate(). Supports both single-group and grouped simulations, as determined by study design and data parameters. Used within the movedesign application workflows to create synthetic data for simulation studies and to evaluate study design.

Usage

simulating_data(rv, seed)

Arguments

Details

This function simulates animal movement tracks based on the selected mode and design settings. It first constructs a time sequence using the specified duration and interval. Depending on the simulation mode (data_type), it either retrieves movement models from modList (for simulated data) or uses meanfitList or raw movement parameters to build models (for uploaded or selected data). If a group comparison is requested, models are prepared for both groups. Tracks are then simulated using ctmm::simulate() and subsequently pseudonymized.

Value

A list of simulated movement datasets:

• If grouped = FALSE, a list with a single simulated track.

• If grouped = TRUE, a list with two tracks (from groups A and B).

Note

This function is intended for internal use and may assume inputs follow specific structure and constraints not referenced explicitly.

Summary method for movedesign_check objects

Description

Summary method for movedesign_check objects

Usage

## S3 method for class 'movedesign_check'
summary(object, ...)

Arguments

Summary method for movedesign_input

Description

Summary method for movedesign_input

Usage

## S3 method for class 'movedesign_input'
summary(object, ...)

Arguments

Summary method for movedesign_output

Description

Summary method for movedesign_output

Usage

## S3 method for class 'movedesign_output'
summary(object, ...)

Arguments

Summary method for movedesign_preprocess

Description

Summary method for movedesign_preprocess

Usage

## S3 method for class 'movedesign_preprocess'
summary(object, ...)

Arguments

Summary method for movedesign_report objects

Description

Summary method for movedesign_report objects

Usage

## S3 method for class 'movedesign_report'
summary(object, ...)

Arguments