Package {movedesign}

Title:	Study Design Toolbox for Movement Ecology Studies
Version:	0.3.3
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 (≥ 4.1.0)
Imports:	bayestestR, bsplus, config (≥ 0.3.1), crayon, ctmm (≥ 0.6.1), data.table, dplyr, fontawesome, gdtools, gfonts, ggiraph, ggplot2, ggtext, golem (≥ 0.3.2), grDevices, lubridate, parallel, parsedate, patchwork, quarto, reactable, rintrojs, rlang, scales, shiny (≥ 1.7.1), shinyalert, shinybusy, shinydashboard, shinydashboardPlus, shinyFeedback, shinyjs, shinyWidgets, stats, stringr, terra, tidyr, tools, utils, viridis
Suggests:	knitr, rmarkdown, shinytest2
VignetteBuilder:	knitr, quarto
Config/testthat/edition:	3
Encoding:	UTF-8
Language:	en-US
LazyData:	true
Config/roxygen2/version:	8.0.0
NeedsCompilation:	no
Packaged:	2026-05-27 09:35:19 UTC; simoes48
Author:	Inês Silva [cre, aut, cph]
Repository:	CRAN
Date/Publication:	2026-05-27 10:40:02 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]

Authors:

• 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, stop_on_error = FALSE)

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, allowing for parallel execution. It currently supports both home range and speed estimation workflows.

Usage

fitting_models(
  obj,
  set_target = c("hr", "ctsd"),
  parallel = FALSE,
  trace = FALSE,
  ncores = parallel::detectCores(),
  ...
)

Arguments

Details

The function generates initial parameter estimates for each dataset using ctmm::ctmm.guess(). If the data includes simulated location error, it adds an error model accordingly. Models are fitted using ctmm::ctmm.select(), which performs model selection to find the best-fit movement process. Finally, all fitted models are recentered to (⁠0, 0⁠) for downstream consistency.

Value

A list of fitted movement models, all recentered to the origin.

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 = 9,
  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()) {
 
  output <- md_replicate(input, n_replicates = 20)
  md_check(output, tol = 0.05, n_converge = 10)
 
}

Compare estimation error across study design workflows

Description

The final step in the movedesign workflow. Takes replicated outputs from two or more study designs, ranks them by estimation performance, identifies the best-performing design, and produces a density plot of relative error across replicates.

Use this function after running md_replicate() for each design and confirming convergence with md_check(). For a quick visual comparison before full replication, use md_compare_preview() instead.

Usage

md_compare(
  x,
  stat = c("mean", "median"),
  ci = 0.8,
  method = "HDI",
  pal = c("#007d80", "#A12C3B"),
  m = NULL,
  show_text = TRUE
)

Arguments

Details

Designs are ranked separately for each target metric (home range, speed) and group (if present). The ranking criterion combines absolute relative error and distance of the credible interval from zero: designs with lower error and tighter intervals closer to zero rank higher. A design is identified as the overall winner only if it ranks first across all groups for a given target.

The function prints a density plot showing the full distribution of relative error across replicates for each design. The centre statistic (stat) and credible interval (ci) are overlaid. When groups are present, density curves for each group are shown side by side using the colors in pal.

Recommended workflow

This function is designed to be called at the end of the movedesign workflow:

1. Build each design with md_prepare().

2. Run md_replicate() for each design.

3. Confirm convergence with md_check().

4. Compare and rank designs with md_compare().

Value

An object of class movedesign_report. A density plot of relative error is printed as a side effect; to reproduce it later, call md_plot() on any of the input designs.

This object contains:

ranking

Data frame with one row per design per target (and per group if grouping is used). Columns include the centre error statistic (error), credible interval bounds (error_lci, error_uci), CI width, distance from zero error, and rank. Lower rank indicates better performance.

winners

Data frame identifying designs that rank first across all groups for each target. A design is a winner when it has the lowest absolute error and the credible interval closest to zero across every group. Returns empty if no single design dominates.

See Also

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

Other workflow_steps: md_prepare(), md_replicate(), md_run(), md_simulate()

Examples

if (interactive()) {

  data(buffalo)
  inputA <- 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")
  
  inputB <- md_prepare(
    data = buffalo,
    models = models,
    species = "buffalo",
    n_individuals = 5,
    dur = list(value = 10, unit = "days"),
    dti = list(value = 1, unit = "day"),
    add_individual_variation = TRUE,
    grouped = TRUE,
    set_target = "hr",
    which_meta = "mean")
  
  outputA <- md_replicate(inputA, n_replicates = 20)
  outputB <- md_replicate(inputB, n_replicates = 20)
  
  # Plot with 80% credible intervals:
  md_compare(list(outputA, outputB), ci = 0.80, method = "HDI")
  
}

Compare estimation error across designs (single replicate)

Description

Plots estimation error of the chosen targets for two or more study designs, each represented by a single md_run() output. Use this function to quickly compare how design choices affect estimation performance before committing to a full replication with md_replicate().

Because each design is represented by a single stochastic run, results are preliminary. For robust, publication-ready comparisons, run md_replicate() for each design and compare with md_compare().

Usage

md_compare_preview(
  ...,
  n_resamples = NULL,
  error_threshold = 0.05,
  pal = c("#007d80", "#A12C3B")
)

Arguments

Details

If n_resamples is not NULL, the function draws n_resamples random combinations of individuals at each population sample size and computes a population-level estimate for each. This step

Each design is represented by a single stochastic run. Apparent differences between designs may reflect random variation rather than genuine performance differences. Use md_replicate() to generate robust, replicated results for each design, and md_compare() to compare multiple designs.

Value

A ggplot object. Displays relative error as a function of population sample size, with one panel (or two if two target) per design. Point estimates, confidence intervals, and a horizontal reference line at error_threshold.

See Also

md_run() to generate each input object. md_plot_preview() for a single-design equivalent. md_replicate() for robust multi-replicate outputs per design. md_check() to assess convergence across replicates.

Examples

if (interactive()) {

  data(buffalo)
  inputA <- 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 = FALSE,
    grouped = TRUE,
    set_target = "hr",
    which_meta = "mean")
  
  inputB <- md_prepare(
    data = buffalo,
    models = models,
    species = "buffalo",
    n_individuals = 5,
    dur = list(value = 10, unit = "days"),
    dti = list(value = 1, unit = "day"),
    add_individual_variation = TRUE,
    grouped = TRUE,
    set_target = "hr",
    which_meta = "mean")
  
  outputA <- md_run(inputA)
  outputB <- md_run(inputB)
  md_compare_preview(list(outputA,
                          outputB), error_threshold = 0.05)
}

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, parallel = FALSE)

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

Pools two or more md_run() outputs into a single movedesign_processed object by concatenating all simulated individuals, fitted models, and seeds. The merged object behaves exactly as if all individuals had been simulated in one call: if each input contains 5 individuals, the merged output contains 10.

The distinction from md_stack() is important. md_merge() treats all inputs as parts of one larger dataset; replicate identity is lost and individual counts accumulate. md_stack() instead assigns a replicate ID to each md_run() output and aggregates population-level inference across them, keeping each run as a separate replicate.

Call md_merge() directly only when you have run md_run() separately and need to pool the raw outputs before downstream analyses.

Usage

md_merge(x, ...)

Arguments

Details

Before merging, all inputs are checked for consistent metadata (e.g. dur, dti, set_target). Movement timescale parameters (tau_p, tau_v) are compared after rounding to one decimal place, to tolerate minor numerical differences arising from separate model fitting runs. If any field mismatches are found, the function stops with an informative message listing the affected fields.

Value

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

See Also

md_prepare, md_run

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 = FALSE,
    set_target = "hr",
    which_meta = "mean")

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

  # Both of the following are equivalent:

  md_merge(output1, output2)
  md_merge(list(output1, output2))
  
}

Optimize sampling parameters and population sample size

Description

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

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

Usage

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

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.

• init_m: Integer. Maximum sample size evaluated.

• minimum_m: Integer. Minimum sample size achieving the threshold.

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,
                     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(
  x,
  stat = c("mean", "median"),
  ci = 0.8,
  method = "HDI",
  pal = c("#007d80", "#A12C3B"),
  m = NULL,
  show_text = TRUE,
  ...
)

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. The plot can display either the estimates from that replicate for a random combination of individuals, or, when resampling is enabled, summaries derived from repeated draws of individuals at each population sample size (based on the specified number of resamples).

This functions shows preliminary outputs for a single stochastic run from md_run() (a movedesign_processed object) and should not be used to evaluate study design by itself. Instead, users should run md_replicate() and check for convergence with md_check().

Usage

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

Arguments

Details

This plot summarizes a single replicate, so it is subject to stochastic variation. The plot shown here may look very different with another run of the same design. Use md_replicate() to aggregate results across many independent runs, and md_check() to confirm that estimates have stabilised before drawing conclusions.

Value

A ggplot object. Displays relative error as a function of population sample size, with point estimates, confidence intervals, and a horizontal reference line at error_threshold.

See Also

md_run() to generate the input object. md_replicate() for robust outputs based on multiple replicates. md_check() to assess convergence across replicates.

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 = FALSE,
    grouped = TRUE,
    set_target = "hr",
    which_meta = "mean")
  
  output <- md_run(input)
  md_plot_preview(output, error_threshold = 0.05)
}

Plot estimation error, replicates and confidence intervals

Description

This function produces two complementary visualizations of replicate performance across a range of population sample sizes m, up to the maximum number of individuals requested. It summarizes and plots relative errors regarding the estimation of a set target (e.g., home range or speed estimation), and classified by whether the error falls within a user-defined acceptable threshold.

"Estimation error (for a single random replicate)"

Error for one randomly-selected replicate, rendered as point estimates with confidence interval bars. Reflects the outcome a researcher would observe from a single empirical study.

"Mean estimation error across all replicates"

Mean error collapsed across all replicates (with confidence intervals as a narrow bar, and prediction intervals as a wide shaded band), with per-replicate jitter in the background. Conveys the full distribution of outcomes with the set sampling parameters and population sample size.

Both panels share a common color palette (within/outside the acceptable error threshold) and, when two groups are present, a common shape scale. By default, the function plots only the second item listed above.

Usage

md_plot_replicates(
  obj,
  ci = 0.95,
  view = "summary_only",
  pal = c("#007d80", "#A12C3B"),
  ...
)

Arguments

Value

A patchwork / ggplot object containing:

• Top plot: A ggplot object displaying the results from a single randomly selected replicate, showing individual error estimates and their confidence intervals.

• Bottom plot: A ggplot object summarizing mean relative error across all replicates, with aggregated estimates in the foreground and individual replicates shown in lighter tones in the background.

See Also

md_plot() for the density plot for the maximum m.
md_replicate() to produce a movedesign_output.
md_optimize() to produce a movedesign_optimized.

Examples

if(interactive()) {
  
  obj <- md_replicate(...)
  
  # Default: both panels
  md_plot_replicates(obj)
  
  # Summary panel, custom palette, 80% CI:
  md_plot_replicates(
    obj,
    ci = 0.90,
    view = "summary_only",
    pal = c("#1e2a38", "#9e3419"))

}

Prepare movement study design inputs

Description

Prepares and validates all inputs needed to evaluate the study design of animal movement projects using parameters derived from empirical tracking data. The function checks data integrity, fits or verifies movement models, extracts key parameters, and consolidates all settings into a structured object for reproducible and streamlined downstream analyses.

If you do not have empirical data, use md_simulate() instead, which builds inputs from user-specified parameters.

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,
  .seed = NULL
)

Arguments

list(
  A = c("Animal_01", "Animal_02"),
  B = c("Animal_03", "Animal_04")
)

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.

• Fits movement models to each individual if not supplied.

• Checks supplied movement models for validity.

• Extracts parameters (tau_p, tau_v, sigma) from fitted models for use in downstream simulations.

• Consolidates all settings, parameters, and model objects into a single structured object.

By default (add_individual_variation = FALSE), all simulated animals share the same movement parameters, estimated from the population mean. Setting add_individual_variation = TRUE instead randomly draws parameters from the population distribution for each individual, which better reflects natural variability but increases uncertainty in downstream estimates.

Value

An object of class movedesign_input, accepted by all downstream functions such as md_run() and md_replicate(). Contains the validated inputs, fitted models, extracted movement parameters, and all metadata needed for study design evaluation.

See Also

md_simulate() to build inputs from directly specified parameters rather than empirical data, md_run(), md_replicate().

Other workflow_steps: md_compare(), md_replicate(), md_run(), md_simulate()

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"),
    set_target = "hr",
    which_meta = "mean")
    
 summary(input)
}

Replicate study design workflow and aggregate outputs

Description

Runs the full movedesign workflow multiple times and aggregates outputs across independent replicates. Use this function after md_run() to quantify how stochasticity and design choices affect estimation performance, and to produce the robust, replicated results needed for a reliable design evaluation. Use md_check() afterwards to assess whether enough replicates have been run for stable inference.

Can also extend a previous run of md_replicate(): passing an existing movedesign_output object appends new replicates to the existing outputs rather than starting over.

Usage

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

Arguments

Details

Each replicate calls md_run() with a unique random seed, ensuring results are statistically independent. If the function is interrupted, it returns all results completed up to that point rather than discarding them. This makes it safe to stop a long run early and still retrieve partial results.

Parallel processing

Setting parallel = TRUE can substantially reduce runtime for large replication runs.

Appending replicates

Passing a movedesign_output object as obj adds new replicates to the existing results. This is useful when an initial run needs more replicates for stable inference without discarding completed work.

Assessing convergence

There is no universal rule for how many replicates are sufficient. After an initial run, use md_check() to evaluate whether the cumulative mean of the tracked error metric has stabilised across replicates. If convergence has not been reached, pass the returned movedesign_output object back to md_replicate() to append more replicates without discarding completed work. Repeat until md_check() confirms convergence.

Value

An object of class movedesign_output, accepted by md_check(), md_plot(), and md_plot_replicates().

See Also

md_prepare() and md_simulate() to build the input object. md_run() for a single exploratory run before committing to full replication. md_check() to assess whether cumulative estimation error has stabilised across replicates (the recommended criterion for deciding when enough replicates have been run). md_plot() and md_plot_replicates() to visualize outputs.

Other workflow_steps: md_compare(), md_prepare(), md_run(), md_simulate()

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,
    grouped = FALSE,
    set_target = "hr",
    which_meta = "mean")
  
  output <- md_replicate(input, n_replicates = 5)
  md_check(output)
  
  # Append more replicates to an existing result:
  output <- md_replicate(output, n_replicates = 10)
}

Run study design workflow

Description

The main workhorse of the movedesign workflow. Runs one full round of simulation and analyses to evaluate whether the design meets its estimation targets. #' Call this function once your design has been built using md_prepare() for empirical data, or md_simulate() for user-specified parameters.

Because a single run is subject to stochastic variation, treat outputs from md_run() as exploratory, and use md_replicate() for more robust inferences (as it aggregates results across multiple replicates).

Usage

md_run(design, trace = TRUE, .seeds = NULL)

Arguments

Details

Progress messages are printed by default. Every individual simulation is assigned a unique random seed, stored in ⁠$seedList⁠ of the returned object. Passing that list to .seeds in a subsequent call reproduces the run exactly. This is particularly useful when replicating a result first produced in the Shiny app.

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 object of class movedesign_processed, accepted by downstream functions such as md_plot_preview(), or md_compare_preview().

See Also

md_prepare() and md_simulate() to build the input object. md_replicate() to run the workflow multiple times and aggregate results, which is recommended over a single md_run() call for any final design evaluation. md_plot_preview() and md_compare_preview() to inspect or compare these preliminary outputs.

Other workflow_steps: md_compare(), md_prepare(), md_replicate(), md_simulate()

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 = FALSE,
  set_target = "hr",
  which_meta = "mean")
  
output <- md_run(input)
}

Simulate movement data from species parameters

Description

Simulates continuous-time movement trajectories based on user-specified movement parameters. The function is designed to support study design workflows by generating synthetic tracking data under specified the movement, sampling, and analytical assumptions.

Use this function when you do not have empirical data available. For workflows grounded in real data, use md_prepare() instead, which extracts movement parameters directly from fitted models.

Usage

md_simulate(
  n_individuals = NULL,
  tau_p,
  tau_v,
  sigma,
  dur = NULL,
  dti = NULL,
  set_target = c("hr", "ctsd"),
  which_meta = "mean",
  grouped = FALSE,
  parallel = FALSE,
  seed = NULL
)

Arguments

list(
  A = list(value = 6,  unit = "hours"),
  B = list(value = 12, unit = "hours")
)

Details

Each simulated trajectory represents a single continuously-tracked animal, generated from a continuous-time movement model with the parameters you supply. The time vector is constructed from dur and dti, and then one trajectory per individual is drawn from that model.

Simulated data are immediately passed through the full movedesign workflow (model fitting, aggregation, and estimation of the target metrics) so the returned object is ready for study design evaluation without further steps.

When grouped = TRUE, simulations are generated independently for each using their own movement parameters but currently share the same sampling parameters (dur and dti). Group structure only affects downstream inference when which_meta = "ratio".

Value

An object of class movedesign_input. This is the standard input object for the movedesign workflow and can be passed directly to downstream functions such as md_run() or md_replicate(). It contains the simulated trajectories, fitted movement models, and all metadata needed for study design evaluation.

Note

Results are only as informative as the parameters you provide. Where possible, derive parameters from real tracking data using md_prepare(). Simulations based on arbitrary or weakly justified parametersvalues may be useful for exploration purposes, but should be interpreted with caution in any design or inference context.

See Also

md_prepare() to derive parameters from real tracking data.

Other workflow_steps: md_compare(), md_prepare(), md_replicate(), md_run()

Examples

if(interactive()) {

# Single group:
# (simulate 10 individuals over 3 months with fixes every 2 hours)

input <- md_simulate(
  n_individuals = 4,
  tau_p = list(value = 6, unit = "hours"),
  tau_v = list(value = 30, unit = "minutes"),
  sigma = list(value = 1, unit = "km^2"),
  dur = list(value = 1, unit = "month"),
  dti = list(value = 2, unit = "hours"))

# Two groups with different parameters:

input_grouped <- md_simulate(
  n_individuals = 10,
  tau_p  = list(
    A = list(value = 6,  unit = "hours"),
    B = list(value = 12, unit = "hours")
  ),
  tau_v  = list(
    A = list(value = 0.5, unit = "hours"),
    B = list(value = 1,   unit = "hours")
  ),
  sigma  = list(
    A = list(value = 1, unit = "km^2"),
    B = list(value = 2, unit = "km^2")
  ),
  dur = list(value = 3, unit = "months"),
  dti = list(value = 2, unit = "hours"),
  grouped = TRUE,
  which_meta = "ratio")
  
}

Stack simulation outputs as replicates

Description

Assigns a replicate ID to each md_run() output, re-runs population-level resampling for each, and aggregates inference results into a unified output. Calling md_stack() on a list of n md_run() outputs produces the same result as calling md_replicate() with n_replicates = n.

Use this function when the md_run() calls have already been made; for example, when runs were executed in parallel outside the standard workflow, or recovered after an interruption.

The distinction from md_merge() is important. md_merge() pools all inputs into one larger dataset (e.g., if each run has 5 individuals, the output has 10, and the design corresponds to a single replicate. md_stack() assigns each run a separate replicate ID: number of individuals does not accumulate, and population-level inference is aggregated across replicates.

Usage

md_stack(obj, error_threshold = 0.05, ...)

Arguments

Value

A list of class movedesign_output.

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_processed object for preprocessed results

Description

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

Usage

movedesign_processed(input)

Arguments

Value

An object of class movedesign_processed 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 https://doi.org/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.

Plot movedesign report outputs

Description

S3 method for plotting a movedesign_optimized object. Returns the precomputed ggplot stored in the object.

Usage

## S3 method for class 'movedesign_optimized'
plot(x, ...)

Arguments

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_optimized objects

Description

Print a structured summary of a movedesign_optimized object produced by md_optimize(). This includes study design details, replication settings, estimation performance per target metric, and an optional convergence assessment.

Usage

## S3 method for class 'movedesign_optimized'
print(
  x,
  verbose = TRUE,
  m = NULL,
  ci = 0.95,
  tol = 0.05,
  n_converge = 9,
  plot = TRUE,
  pal = c("#007d80", "#A12C3B"),
  ...
)

Arguments

Print method for movedesign_output

Description

Print method for movedesign_output

Usage

## S3 method for class 'movedesign_output'
print(
  x,
  verbose = FALSE,
  m = NULL,
  ci = 0.95,
  tol = 0.05,
  n_converge = 9,
  plot = TRUE,
  pal = c("#007d80", "#A12C3B"),
  ...
)

Arguments

Print method for movedesign_processed

Description

Print method for movedesign_processed

Usage

## S3 method for class 'movedesign_processed'
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

Read a movedesign session file

Description

Reads a .rds file exported from the movedesign Shiny application, validates its structure, and reconstitutes each component to its corresponding movedesign class.

The returned list always contains:

design_input

A movedesign_input object: sampling design parameters as specified by the user.

design_processed

A movedesign_processed object: results from a single simulation replicate.

(Optional) If multiple replicates have been run:

design_output

A movedesign_output object: aggregated results across all simulation replicates.

Usage

read_md(filepath)

Arguments

Value

A named list of three movedesign objects.

Examples

## Not run: 
md_objects <- read_md("path/to/my_file.rds")

md_objects$design_input      # movedesign_input object
md_objects$design_processed  # movedesign_processed object
md_objects$design_output     # movedesign_output (if available)

## End(Not run)

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.

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,
  randomize = 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?

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, verbose = FALSE, ...)

Arguments

Summary method for movedesign_input

Description

Summary method for movedesign_input

Usage

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

Arguments

Summarise a study design optimization

Description

Print a structured summary of a movedesign_optimized object produced by md_optimize(). The summary reports the study design, replication settings, estimation performance for each target metric, and a convergence assessment.

This method runs automatically when calling summary(output) on a movedesign_optimized object.

Usage

## S3 method for class 'movedesign_optimized'
summary(
  object,
  verbose = FALSE,
  error_threshold = NULL,
  m = NULL,
  ci = 0.95,
  tol = 0.05,
  n_converge = 9,
  plot = TRUE,
  pal = c("#007d80", "#A12C3B"),
  ...
)

Arguments

Summarise a study design output

Description

Print a structured summary of a movedesign_output object produced by md_replicate() or md_stack(). The summary reports the study design, replication settings, estimation performance for each target metric, and a convergence assessment.

This method runs automatically when calling summary(output) on a movedesign_output object.

Usage

## S3 method for class 'movedesign_output'
summary(
  object,
  verbose = FALSE,
  m = NULL,
  ci = 0.95,
  tol = 0.05,
  n_converge = 9,
  plot = TRUE,
  pal = c("#007d80", "#A12C3B"),
  ...
)

Arguments

See Also

md_replicate(), md_stack() to generate results. md_check() to inspect convergence directly. md_compare() to compare designs after convergence.

Examples

if(interactive()) {

data(buffalo)

input <- md_prepare(
  species = "African buffalo",
  data = buffalo,
  n_individuals = 5,
  dur = list(value = 1, unit = "month"),
  dti = list(value = 1, unit = "day"),
  set_target = "hr",
  which_meta = "mean")

output <- md_replicate(input, n_replicates = 20)

# Print standard summary:
summary(output)

# Run full convergence diagnostics:
summary(output, verbose = TRUE, tol = 0.05)

}

Summary method for movedesign_processed

Description

Summary method for movedesign_processed

Usage

## S3 method for class 'movedesign_processed'
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