1. Introduction

F1000Research

2046-1402

F1000 Research Limited

London, UK

10.12688/f1000research.124810.1

Software Tool Article

Articles

abmAnimalMovement: An R package for simulating animal movement using an agent-based model

[version 1; peer review: 2 approved with reservations]

Marshall

Benjamin Michael

Conceptualization Software Visualization Writing – Original Draft Preparation Writing – Review & Editing https://orcid.org/0000-0001-9554-0605 a 1 Duthie

Alexander Bradley

Supervision Writing – Review & Editing b 1 1Biological and Environmental Sciences, Faculty of Natural Sciences, University of Stirling, Stirling, FK9 4LA, UK

a benjaminmichaelmarshall@gmail.com b alexander.duthie@stir.ac.uk

No competing interests were disclosed.

17 10 2022

2022

1182

5 9 2022

2022

This is an open access article distributed under the terms of the Creative Commons Attribution Licence, which permits unrestricted use, distribution, and reproduction in any medium, provided the original work is properly cited.

Animal movement datasets are growing in number and depth, and researchers require a growing number of analytical approaches to adequately answer questions using movement datasets. As the complexity of questions and analyses increase, deciding on the best approach both in terms of study design and analysis can become more difficult. A potential solution is to simulate an array of synthetic datasets under varying study designs and simulation parametrisations to gain insight into the impact of analysis choice(s) in different contexts. The abmAnimalMovement R package provides the means of simulating animal movement for this purpose. The abmAnimalMovement simulations use a discrete time agent-based model and does not require previous movement data as an input. The simulations include a number of key internal and external movement influences, as well as parameters for navigation and mobility capacity of the animal. Internal influences include three predefined behavioural states (e.g., rest, explore, forage) and any number of activity cycles (e.g., diel, seasonal). External influences are implemented via matrices describing landscape characteristics (e.g., shelter quality, foraging resources, movement ease), and predefined points describing shelter sites and points the animal aims to avoid. Navigation capacity is defined by the range the animal can dynamically choose a foraging location to which it is subsequently attracted. Mobility capacity is implemented by user defined distributions, from which step length and turn angles are draw at each time step, governing the possible subsequent locations of the animal. Critically, the navigation capacity (the choice of destination) operates on a different time scale to the mobility capacity, allowing the internal state of the animal to differ from the observed movements. When combined with other emergent properties, such as site fidelity generated via repeated shelter site use, the simulations offer opportunities to test whether movement analyses can accurately recover hidden mechanisms, states, and drivers.

Movement ecology agent-based individual-based simulation behavioural states spatial ecology

Natural Environment Research Council

BMM was funded by the Natural Environment Research Council (NERC) via the IAPETUS2 Doctoral Training Partnership.

The funders had no role in study design, data collection and analysis, decision to publish, or preparation of the manuscript.

1. Introduction

As the biodiversity crisis deepens, we are in constant need of new refined methods of mitigating human impacts on animals. Developing mitigation strategies is aided by a strong understanding of animals lives and needs. How animals move offers a window into their decisions making process, ¹ ^, ² as well as how they prioritise resources, ³ ^– ⁵ avoid threats, ⁶ and react to anthropogenic modification of the environment. ⁷ ^– ⁹ Examinations of animal movement are frequently integrated into conservation plans ¹⁰ because of the insights they provide on habitat and space requirements, but also because they offer avenues to explore fundamental questions about ecology. For example, space use has been tied directly to body size connected via the energy requirements for animals, ¹¹ and movement has provided incredible insights into behaviour. ¹²

The information gathered from animal movement studies is only as robust as the methods and analysis applied. In the past decade, the volume of animal data has exploded, ¹³ ^, ¹⁴ and the infrastructure for collating these data has improved drastically. ¹⁵ There are stand out examples of novel methods, ¹⁶ and exceptionally detailed insights into animal behaviour using new bio-logging technology (e.g., Ref. 12). However, on the whole, analysis approaches to maximise the information extracted have arguably lagged behind the technological and data improvements. ¹³ The bodily cost of attaching bio-telemetry devices (with examples from reptiles ¹⁷; mammals ¹⁸; and birds ¹⁹), as well as the possible conservation sensitivity of study animals, means researchers have an ethical duty to maximise the value/impact of the data collected.

Maximising the value of data should include ensuring that results gained are robust and replicable. Meta-analyses have revealed that several textbook examples in ecology are not as universally replicable as once thought. ²⁰ ^– ²³ Whereas lab studies can more feasibly be repeated (although such replications are far from cheap), movement studies conducted on free-ranging wild animals are difficult to repeat while satisfactorily meeting the conditions of the true replication. ²⁴ It is hard to justify placing bio-telemetry devices on more animals to repeat a study, especially when they are of conservation concern. Studies tend to focus on larger, less vulnerable species, ²⁵ ^, ²⁶ but as the benefits of detailed movement data grow, we can expect greater demand for tracking species of conservation concern. ¹⁰ With the limited scope for repeating wild movement studies, and the desire to maximise study-to-benefit ratio for sensitive species, it is imperative that we maximise the quality of the initial studies.

Expanding pre-study planning and developing better approaches to guide study design may provide a partial solution. ²⁷ Study scenarios where researchers have control over the environment, randomisation, and controls can satisfy the assumptions of many statistical approaches. ²⁸ Movement studies conducted in the wild are fraught with uncontrollable confounding variables and often further restricted by sample sizes limited by ethics, capture rates, and cost of bio-telemetry equipment. As the complexity of the research environment increases, so must the analytical approach to account for the uncontrollable –but potentially extraneous to the question– variables. Testing these analysis approaches, and their limitations therefore becomes more difficult to asses a priori.

A potential solution is virtual ecology: where synthetic data are simulated to cover a range of possible scenarios allowing researchers to explore different study approaches/designs with the aim of identifying the best for a given question. ²⁹ Exploration of analysis methods using simulations can yield useful insights even for broadly understood techniques (e.g., Generalised linear mixed model ³⁰). Such an approach has the potential to adequately recreate the complex emergent properties that could hamper analyses. ³⁰ The suite of tools for simulating aspects of ecological systems (e.g., landscapes, ³¹ genetics, ³² conservation choices, ²⁹ ecological community comparisons, ³³ resource selection ³⁴) is growing, and some are explicitly focusing on aiding study design. There are also examples of simulation approaches being directly tied to applied issues like human-wildlife conflict (e.g., snakes, ³⁵ tigers ³⁶).

Population monitoring studies offer a great example of a mature relationship between simulated data, study design, and applied research, implemented in a complex study environment. ³⁷ There are examples of simulated datasets being used to validate field protocols (e.g., camera trap effort ³⁸ ^, ³⁹) and analyses (e.g., accounting for species interactions, ⁴⁰ or difficult to account for variation in populations ⁴¹). More recently, explicitly simulating animal movement processes rather than the population distribution has helped validate spatially-explicit capture recapture methods (SECR), while also prompting deeper questions concerning the findings generalisably to drastically different movement processes. ³⁷ Once validated with real-world data, simulated explorations of study design presents opportunities to understand the trade-offs between effort and precision. ³⁹ But similarly, disagreements on the implementation of surveying methods have led to further explorations of how we conceptualise and simulate animal processes. ⁴²

As illustrated by the SECR example, different simulation approaches and different analyses accounting for different additional complexities offer different suggestions on the optimal study design. There are a number of approaches for simulating animal movement including (but not limited to): 1.

continuous movement processes, best exemplified by the R package ctmm ⁴³ and worked examples such as Ref. 44 and Ref. 37. These methods rely on a mathematically defined movement process (such as Ornstein–Uhlenbeck foraging process ⁴⁵). A key aspect of animal movement they simulate is correlated speeds and central tendency (i.e., home range).

hidden markov models, exemplified by the simData function from the R package moveHMM. ⁴⁶ Their biggest contribution to simulating animal movement is the inclusion of state switching (i.e., different behaviours). They are best used in conjunction with existing movement data for parametric bootstrapping to explore estimator uncertainty. ⁴⁶

agent-based approach, is a bottom-up approach where simulations of an agent (e.g., an animal) are based upon a number of rules, ⁴⁷ and through repeatedly following those rules a complex output emerges. In the model we present here, this output represents the movement pathways in a landscape. Previous examples of agent-based movement models have targeted specific key components of animal movements such as movement heavily constrained by landscape features, ⁴⁸ simulating memory/home range, ⁴⁹ or migratory behaviour. ⁵⁰

Here we present an agent-based approach to supplement those existing simulations, which provides a unique combination of features. The agent-based approach is suited to explore a combination of the complexities of animal movement, and the emergent properties. Our model does not require fitting to prior movement data, allows for multiple predefined points of attraction/avoidance, multiple-levels of activity cycling, three behavioural states, and multiple spatial environmental covariates. A new independently developed approach to simulating animal movement will provide a additional routes to test the robustness of movement analyses.

2. Methods 2.1 Overview of the agent-based model

The abmAnimalMovement package provides the functionality to simulate animal movements via an agent-based model. We wrote the model using C++ via the Rcpp v.1.0.8.3 package ⁵¹ ^– ⁵³ to ensure it runs efficiently while allowing for easier manipulation of model inputs and outputs via R (R is the most used analysis tool in movement ecology with numerous supporting packages ¹³ ^, ⁵⁴).

The model simulates animal locations over a given period of time at discrete time steps. At each time step, the agent (i.e., simulated animal) is presented with a range of movement options in the form of new locations [ Figure 2], and will choose from amongst these (i.e., sum-based model as opposed to facing a series of sequential binary decisions, see Ref. 2 for an example of the latter). The possible movement options, and how the new location is selected, are influenced by several factors: behavioural state of the animal, environmental quality, and proximity to points of attraction/avoidance. By simulating these drivers of animal movement, we hope to capture aspects of the internal state (i.e., motivation to move via behaviour); motion capacity (i.e., the individual’s varying ability to move); navigation capacity (i.e., ability to plan ahead beyond the immediate movement distance); and external factors (i.e., the landscape that steers and limits movement), all of which are defined as key components of animal movement. ⁴⁷ ^, ⁵⁵

The animal has three behavioural states, broadly defined here as state 0 - sheltering (or resting), state 1 - exploring, and state 2 - foraging. Each behavioural state modifies the movement characteristics of the animal; for example, exploring comprises of more random movements with longer distances between subsequent chosen locations, whereas resting behaviour is largely defined by stationary or very low discrete movements after returning to a shelter site. The movement characteristics are defined by two distributions: a Gamma distribution that step lengths are drawn from, and a Von-Mises that turn angles are drawn from. The resulting step length, combined with a turn angle describes the change in animal location between each time step (as selected from a given number of options). We will largely define these based on the movement capacity of the animal over a minute.

As the simulation will be running with three behavioural states, we need to define how likely an animal is to switch between the behaviours. We achieved this by creating a transition matrix that describes the probability at each time step of the animal changing to another behaviour [ Figure 1], where each value describes the probability of the animal transitioning from the current behaviour (row: b0, b1, b2), to the behaviour for the next time step (columns: b0, b1, b2). The diagonal describes the probability of the animal remaining in the same behavioural state. These probabilities can be kept very high to introduce autocorrelation in the behavioural state; a high autocorrelation is required if we are modelling time steps as one minute. ## b0 b1 b2 ## b0 0.9700 0.01000 0.0010 ## b1 0.0002 0.95000 0.0008 ## b2 0.0010 0.00001 0.9900

Figure 1. A diagram showing the transition probabilities between the three behavioural states.

Remain values indicate the probabilities of the animal remaining in the same behavioural state. Values correspond directly to those in the transition matrix used as a simulation input.

Animals behaviour is frequently expressed via cycles, such as day/night or diel cycles ⁵⁶; therefore, we want the transition matrix to vary over time. We describe a number of cycles (or waves) that can be applied to the core transition matrix impacting the probability of entering resting behaviour. For example, a diel cycle can be expressed via a Sine wave with a frequency of 12 hours and an amplitude of 0.1. At each time step we draw a value from the wave, and by added that weighting (from -0.05 to 0.05) to the transition probability of entering resting state (row 1, column 1 of the matrix); therefore, the probability of resting will increase and decrease following the Sine wave approximately a 12 hour activity pattern. We can define as many cycles as needed, and they impact the resting probability additively.

When entering the resting state the animal will seek out a shelter site. In the abmAnimalMovement package, we can supply a number of shelter sites to simulate this need and create site fidelity. As these shelter sites act as points of attraction for the animal for each rest, the animal occupies a consistent area, or something approximating a home range. Home ranges are meant to represent areas in which the animal can source all resources required for a given life stage. ⁴⁴ The predefined and steady state of these shelter sites provides the stability we look for in a home range, as well as a means of predefining a level of site fidelity. As the abmAnimalMovement model can have multiple attraction (rest) sites supplied, we can simulate home ranges with unequal and behaviourally influenced space use.

In addition to the predefined attraction to shelter sites, the abmAnimalMovement package allows for a more dynamic attraction to areas of high resource quality. Movements cannot be directly translated to animal preference; for example, habitat preference may miss key movement corridors ⁵⁷; or the habitat decisions may occur at scales different to observed movement. ¹ Therefore, the simulation required a mechanism that somewhat detaches the preference/choice for observed movements. When entering foraging mode, the animal randomly selects foraging destinations as a point of attraction (but weighted towards areas of higher quality) [ Figure 2]. This attraction impacts the movement choices made at each time step, with the animal more likely to choose (and therefore move to) options closer to the foraging destination. Therefore, foraging destination choice operates on a different time frame to the movement and allows movements through low-quality foraging areas. This presents a critical benefit of the simulation approach, as we define the internal state decision making process of the animal. The two time frames also allow exploration of assumptions connecting observed movement choices to choices grounded in resource use, and whether downstream analyses can accurately recover a hidden decision making process.

Figure 2. A diagram showing the simulated animal’s decision processes operating at two different time frames.

A - the time frame of the destination choice, B - the time frame of movements at each time step.

At all times, the subsequent locations of the animal are impacted by a movement resistance matrix. Differing values represent different environmental conditions that could change how easily/likely an animal is to use that area to move towards a destination. For example, rivers or hard barriers within a landscape could present very high movement resistance and an animal would aim to avoid traversing them. Alternatively areas of lower movement resistance could aid movement, and potentially form movement corridors. The movement matrix has values that describe the weighting of movement probability (lower values indicating a lower probability of entering a cell). Whereas the resource environmental layer and shelter locations interact with destination/goal decisions, the movement resistance affects the step-by-step movement decisions.

The interplay between shelter sites, foraging quality, and movement resistance simulates the site fidelity required for home ranges, while allowing the environment to help shape the size and diffusion of that home range. Simulating a more dynamic and messy array of movements can help test how far assumptions of uniform circular animal movement are practical.

2.2 Generating three species

To demonstrate the variation that movement ecology methods needs to wrangle, as well as the scope of movements the agent-based model can recreate, we provide three example species. The examples cover a range of movement capacities, site fidelity, and resting/sheltering patterns. Unlike alternative methods that are built to fit and simulate movements from existing data, our examples are loosely based on summary statistics from previous published results (cited below in each example species’ section). The choice of using species specific examples is intended to provide some biological context while demonstrating a range of simulation parametrisations. Therefore, we are only interested in whether the simulated data returns the intended traits we are attempting to simulate for each example species (e.g., avoidance, site fidelity, expected step lengths). We show one example via a more detailed walk-through (badger), and the other example parametrisations are included as uses cases at the end of the manuscript (vulture, king cobra).

2.3 Primary example

2.3.1 Ecology and objectives - badger

Our primary example is based on a badger. Badgers occupy setts, in our example a two home/shelter sites, to where they routinely return. ⁵⁸ ^, ⁵⁹ When not at the sett, the badger forages, and the foraging distances are impacted by resource position and movement capacity of the badger (i.e., how far can a badger feasibly travel for food from the sett). The badger therefore expresses very high site fidelity, a range dictated by the spatial positioning of resources, and is subject to the movement resistance of the terrestrial environment.

We can draw on studies such as Refs. 58 and 60 to roughly gauge the speed of badgers (i.e., step length per minute). How this speed differs between behaviours is more difficult to estimate from existing literature, but we can use Ref. 58 reported maximum speed to guide more direct movements (e.g., state 0 - sheltering and state 1 - exploring). In particular Ref. 58 mentioned the heightened speeds moving from and to the setts. We also want to allow the exploratory (state 1) movements to be great enough to occasionally exceed the normal home range or territory. ⁶¹ We can draw on statements regarding maximum distance travelled in a night from papers such as, Refs. 58, 60 and 62 to approximate how distance foraging locations could be from a sett, While also confirming the nocturnal activity cycle for the badger. For the example, we will consider badgers as fully nocturnal, and with active periods lasting for around 8 hours each night. ⁶⁰ ^, ⁶³ The 8 hour active periods are not consistent throughout the year. Badger occupying temperate areas are impacted by seasonal shifts that modify daylight hours and available resources. ⁶⁰ ^, ⁶³ Badger movements are also impacted by their territoriality, avoiding areas occupied by other badger groups, but also displaying occasional extra-territorial movements. ⁵⁹ ^, ⁶¹ This suggests a general, but not complete avoidance of areas occupied by other badger groups.

We can broadly summarise the badger ecology we want to parametrise as follows: 1.

Exhibits site fidelity via the use of two shelter sites ⁵⁸ ^, ⁵⁹

Movement speed approximated by summary statistics from previous studies, ⁵⁸ ^, ⁶⁰ ^, ⁶² while constrained by terrestrial environment and territoriality ⁵⁹ ^, ⁶¹

An 8-12 hour activity cycle, that shifts over the year ⁶⁰ ^, ⁶³

2.4 Operation

The abmAnimalMovement package requires links to the Rcpp (>= 1.0.8.3) ⁵¹ ^– ⁵³ and BH (>= 1.78.0.0) packages, ⁶⁴ and therefore requires a version of R >=3.5.0 ⁶⁵ (available from www.r-project.org). Currently the abmAnimalMovement package can be installed from Github using install_github provided by the devtools package. ⁶⁶

A submission to the Comprehensive R Archive Network (CRAN) is under way, which will streamline installation and ensure compatibly with a wide range of platforms.

2.5 Implemenation

While only the abmAnimalMovement package is required for running core simulations ( abm_simulate function), to generate, organise, and review the inputs and outputs of simulations, we make use of a number of R packages. An alternative simpler implementation with no dependencies is provided as a package vignette. # core package library(abmAnimalMovement) # data manipulation library(dplyr) library(reshape2) # visualisation library(ggplot2) library(ggforce) library(ggtext) library(ggridges) library(patchwork) # environmental matrix generation library(raster) library(NLMR)

We used R v.4.2.1 ⁶⁵ via RStudio v.2022.2.2.485, ⁶⁷ and used rmarkdown v.2.14, ⁶⁸ ^– ⁷⁰ bookdown v.0.26, ⁷¹ ^, ⁷² tinytex v.0.39, ⁷³ ^, ⁷⁴ and knitr v.1.39 ⁷⁵ ^– ⁷⁷ packages to generate type-set outputs. We used the here v.1.0.1 package ⁷⁸ to help with relative file path definition. We used the dplyr v.1.0.9 and reshape2 v.1.4.4 packages for data manipulation. ⁷⁹ ^, ⁸⁰ We used ggplot2 v.3.3.6 for creating figures, ⁸¹ ^, ⁸² with the expansions: ggridges v.0.5.3, ⁸³ ggtext v.0.1.1, ⁸⁴ ggforce v.0.3.3, ⁸⁵ and patchwork v.1.1.1. ⁸⁶ We used the raster v.3.5.21, ⁸⁷ sp v.1.4.7, ⁸⁸ ^– ⁹⁰ and NLMR v.1.1 ⁹¹ ^, ⁹² for generating environmental matrices.

2.5.1 Generating environmental matrices

To ensure that the simulation completed during this example is repeatable, we set a seed. For the sake of simplicity, the year the examples was written (2022) is used. seed ˂- 2022 set.seed(seed)

Before starting to simulate animal movement, we need to generate a landscape. The landscapes in this case will take the form of matrices, where each cell is describing the quality of foraging, shelter, and movement ease. The highest quality locations/cells are coded as 1, with quality decreasing as the values range down to 0. The 1 to 0 quality values in each cell are later used to help the animal to choose how and where it moves throughout the landscape. Depending on the behavioural state, the weighing of which matrix/layer used will change (e.g., when in a resting behavioural state the shelter site quality layer is used).

For most applications, a landscape would be known a priori, but for this demonstration and testing of methods we will use a selection of random generated landscape matrices [ Figure 3], using the NLMR package (neutral landscape models).

Figure 3. The three resulting landscape layers to be fed into the simulation for the badger example: shelter quality, foraging resources, movement ease.

We used a Gaussian field with an autocorrelation range of 40, a magnitude of variation across the landscape of 5, a magnitude of variation in the scale of autocorrelation range of 0.2, and a mean of 0.5. For foraging, we build on the Gaussian field already produced, allocating all values lower than 0.4 as 0 (i.e., no value for foraging), then normalising the remaining values between 0 and 1.

For a baseline movement resistance layer, we take the original Gaussian field and increase areas greater than 0.6 by 0.5 to allow areas of high resource quality to be easily accessible. We also greatly increase the movement ease in “edge” habitat (+1), where values fall between 0.6 and 0.3. Again we normalise between 0 and 1, where 1 are areas easily traversed. The resulting environment is one with easily traversable edge areas, surrounding better quality foraging locations than can be moved into easily.

Shelter quality is intermediate; we increased weighting by +1 in areas where cell values were greater than 0.5 and lower than 0.7. Thereby shelter sites are more likely to occur in the areas of higher foraging quality, but not in the core (i.e., >0.7), nor in the edge areas (<0.5). This provides some balance between accessibility and proximity to resources. The three matrices described provide a baseline for our examples, but can easily be modified for different scenarios [ Figure 3]. To aid balancing, we keep values between 0 and 1; any numeric value can be used, but the simulation will interpret the values as relative weights when the animal is making decisions (Note: The current implementation of cpp_get_values that extracts values from the matrices during the simulation returns -99.9 weighting when presented with NA values; therefore, -99.9 serves as a lower limit to the matrix weighting values).

Once generated will supply the core simulation function ( abm_simulate) with each of these layers via the shelteringMatrix, foragingMatrix, and movementMatrix arguments.

2.5.2 Animal parameters

We predefine a suite of parameters describing the movement and behaviour characteristics of the animal (e.g., badger) loosely based on summary statistics and general statements from previous research (e.g., Refs. 58– 63). We store the parameters as objects we can later input into the abm_simulate function. We complete this process for three species; the badger values are displayed below, whereas the values for vulture and king cobra examples are provided at the end of the manuscript.

We parametrise shelter information in the following ways. For the sett, we draw a two sets of coordinates from the shelter quality layer. During the simulation the badger will randomly select a sett to return to each time it enters the resting behavioural state. The choice of which sett to return to is weighted by the values supplied via the shelter quality environmental layer [ Figure 3]. The coordinate data frame is provided to the core simulation function’s shelterLocations argument.

The shelterSize argument describes the radius around the shelter locations within which the animal exhibits near stationary behaviour. We specify the shelter size to be 8 m, meaning that when within 8 m of the selected shelter site the animal’s possible step lengths are decreased 100-fold. The shelter site size of 8 m allows for small movements near/within the sett during resting behaviour. sampledShelters ˂- sampleRandom(raster(landscapeLayersList$shelter), 2, ext = extent(0.45, 0.65, 0.45, 0.65), rowcol = TRUE) BADGER_shelterLocs ˂- data.frame( "x" = sampledShelters[,2], "y" = sampledShelters[,1]) BADGER_shelterSize ˂- 8

Badger movement is set via the definition of three pairs of Gamma and Von Misses distributions. Each behavioural state is provided with a Gamma distribution to describe the step lengths between locations, and a Von Mises to describe the turn angles. When combined these two distributions provide the animal with a number of locations to choose from at each time step [ Figure 2]. As we have three behavioural states, each movement parameter takes the form of a vector of length three. The step lengths require predefined shape (k) and scale ( θ) parameters to describe the Gamma distributions, and we provide these to the simulate function via the k_step and s_step arguments. For the turn angles we require the mean ( μ) and concentration ( κ) to defined the Von Mises distributions, and provide these via the mu_angle and k_angle arguments.

The perceptual range, in other words, where the badger decides to forage is set in a similar fashion. Where destinationRange provides the shape (k) and scale ( θ) for the Gamma distribution describing distance of possible foraging locations, and destinationDirection provides the mean ( μ) and concentration ( κ) the Von Mises distribution describing the angle which those locations can fall [ Figure 4].

Figure 4. The distribution of step lengths used during the badger simulation example.

The distribution displayed is generated from the same shape and scale parameters that will be input into the simulation function for the badger simulation. The lower plot shows the distribution used to generate potential foraging desintations.

We can also alter the strength of attraction to the foraging destinations. At each time step, the animal is offered a number of location options to move to next time step. The simulation calculates the distance between all options and the destination (i.e., a foraging location or shelter site), then normalises the distances between 0 and 1. The normalises values serve as weighting to increase the chances the animal will move towards its destination. We modify the weighting with the destinationTransformation and destinationModifier arguments. The destinationTransformation allows for weightings to be transformed (where 0 = no transformation, 1 = weights are square-rooted, 2 = weights are squared). Values supplied destinationModifier applies a linear multiplicative effect to all the weightings. When these weightings increase in value the animal will exhibit a stronger attraction and choose more direct movements to its current destination.

We also store a value ready for the rescale_step2cell argument. The rescale value is a simple means of adjusting the environment layers to fit with the scale/unit in which the step lengths are provided. In this case, we treat each cell as 5m by 5m, thereby ensuring that our 2000x2000 matrix is sufficient for the badger to traverse without leaving. The rescale value therefore allows high resolution movements on lower resolution environments, offering a crucial memory saving optimisation. BADGER_k_step ˂- c(0.3*60, 1.25*60, 0.25*60) BADGER_s\_step ˂- c(0.8, 0.25, 0.5) BADGER_mu_angle ˂- c(0, 0, 0) BADGER_k_angle ˂- c(0.6, 0.99, 0.6) BADGER_destinationRange ˂- c(3, 120) BADGER_destinationDirection ˂- c(0, 0.01) BADGER_destinationTransformation ˂- 2 BADGER_destinationModifier ˂- 2 BADGER_rescale ˂- 5

The territoriality is not simulated directly via other individuals, instead we approximate it by supplying a number of point locations the badger will avoid. An alternative way of simulating this behaviour would be to create areas of high movement resistance to prevent the badger from entering. We provide a set of x, y coordinates of locations to be avoided. Alongside the locations, we need to define how strongly the badger will avoid them using avoidTransformation (distance to point is weighting squared) and avoidModifier (distance to point is weighting multiplied by 4). Both avoidTransformation and avoidModifier operate in the same way as the destination attraction arguments, but inverted; therefore, the avoidance behaviour will directly counteract the attraction to destination behaviour. BADGER_avoidLocs ˂- data.frame( "x" = c(1205, 1500, 1165), "y" = c(980, 1090, 1250)) BADGER_avoidTransformation ˂- 2 BADGER_avoidModifier ˂- 4

We implement two cycles to capture the daily and seasonal cycles the badger experiences. Both cycles are created by describing a Sine wave defined by its amplitude, midline, offset ( ϕ) and frequency ( τ; via the cycle_draw function). The abm_simulate function has two arguments for wave parameters: rest_Cycle is a mandatory input to describe diel activity cycling, and additional_Cycles to define any number of additive additional cycles. For rest_Cycle we will store a vector of length 4, with values defining the amplitude, midline, offset, and frequency in that order (Frequency is supplied in hours, i.e., 60 times the time step). We set the amplitude to 0.12 and midline as 0, meaning the probability of resting will be modified by values ranging from -0.06 to 0.06 depending on the location in the wave. Our badger example requires a 24 hour cycle where the probability of resting will peak and nadir, hence offset and frequency are set to 24 hours. When combined with the base transition probability to rest, the above parametrisation creates a scenario of approximately 8 hour periods of activity every 24 hours.

To add a seasonal cycle we will use additional_Cycles. We predefine a data frame where each row contains four elements describing the amplitude, midline, offset, and frequency. Whereas our diel activity is defined by a 24 hour cycle, a seasonal cycle is 365 days and we shift the peak half a year (offset = 365/2). The seasonal wave will increase the probability of resting behaviour during a portion of the year, while not also overwhelming a relatively stable diel cycle (i.e., badger will sleep longer during one part of the year) as we have set a lower amplitude for the seasonal cycle (0.075). A more extreme implementation of the second cycle could introduce hibernation behaviour.

We also pull forward the behaviour transition matrix we showed during the overview, and rename it so all simulation input objects have the BADGER_ prefix. BADGER_rest_Cycle ˂- c(0.12, 0, 24, 24) # additional cycle c0 ˂- c(0.075, 0, 24* (365/2), 24* 365) # seasonal BADGER_additional_Cycles ˂- rbind(c0) BADGER_additional_Cycles ## [,1] [,2] [,3] [,4] ## c0 0.075 0 4380 8760 BADGER_behaveMatrix ˂- Default_behaveMatrix BADGER_behaveMatrix ## b0 b1 b2 ## b0 0.9700 0.01000 0.0010 ## b1 0.0002 0.95000 0.0008 ## b2 0.0010 0.00001 0.9900

2.5.3 Running the simulation

We need to initially define a start location for our animal. To introduce some more individual variation, we can randomly vary this starting location, but we will restrict the start locations to be proximal to the centre of the environment. For the simulation, we need a vector of length 2, where the first value is the x location, the second is y. startLocation ˂- sample(900:1100, 2, replace = TRUE)

We finally have some parameters that describe the scope and intensity of the simulation. The length of the simulation is provided via the timesteps argument; in our examples we are operating under the assumption that one time step is equal to one minute. Equally timesteps can be thought as the number of movement choices simulated. We also need to specify how many options will be drawn and considered by the animal at each time step. The options argument is where this is input. Similarly des_options is where we specify the number of dynamically selected foraging attraction/destinations to choose from when it enters the foraging behaviour mode (state 1).

We can then call all our settings describing badger behaviour and movement settings we stored as objects previously, and run the simulation using abm_simulate. simSteps ˂- 24*60 *365 simRes ˂- abm_simulate( # a data frame with x and y coordinates start = startLocation, # an integer describing the length of the simulation timesteps = simSteps, # an integer describing the number of foraging destination options an animal # is offered des_options = 10, # an integer describing the number of movement options an animal is offered options = 12, # a data frame providing x and y coordinates of the shelter locations shelterLocations = BADGER_shelterLocs, # a value describing the radius around shelter sites that movement step # lengths are reduced shelterSize = BADGER_shelterSize, # a data frame providing x and y coordinates of the avoidance locations avoidPoints = BADGER_avoidLocs, # a numeric vector of length two that contains the shape and scale values # that describe the Gamma distribution for potential foraging destinations destinationRange = BADGER_destinationRange, # a numeric vector of length two that contains the mean and concentration values # that describe the Von Mises distribution for potential foraging destinations destinationDirection = BADGER_destinationDirection, # a value to chose the type of transformation applied to the animal’s # attraction to a chosen destination destinationTransformation = BADGER_destinationTransformation, # a value modifying the animal’s attraction to a chosen destination destinationModifier = BADGER_destinationModifier, # a value to chose the type of transformation applied to the animal’s # avoidance to a avoidance locations avoidTransformation = BADGER_avoidTransformation, # a value modifying the animal’s avoidance of avoidance locations avoidModifier = BADGER_avoidModifier, # a vector of three numbers describing the three behavioural state’s Gamma # distributions’ shape parameter for step lengths k_step = BADGER_k_step, # a vector of three numbers describing the three behavioural state’s Gamma # distributions’ scale parameter for step lengths s_step = BADGER_s_step, # a vector of three numbers describing the three behavioural state’s Von Mises # distributions’ mean parameter for turn angles mu_angle = BADGER_mu_angle, # a vector of three numbers describing the three behavioural state’s Von Mises # distributions’ concentration parameter for turn angles k_angle = BADGER_k_angle, # a numeric value to specify the size of the environmental matrices cells rescale_step2cell = BADGER_rescale, # a 3x3 numeric matrix describing the transition probabilities between the # three behavioural states behave_Tmat = BADGER_behaveMatrix, # A vector length 4 for amplitude, midline, offset and frequency to define the # resting/active cycle rest_Cycle = BADGER_rest_Cycle, # A data.frame 4 columns wide for amplitude, midline, offset and frequency to # define any additional activity cycles, where each row is another cycle additional_Cycles = BADGER_additional_Cycles, # Three arguments for the three matrices describing the landscape the # simulated animal occupies shelteringMatrix = BADGER_shelter, foragingMatrix = BADGER_forage, movementMatrix = BADGER_move)

3. Results 3.1 Output format

The simulation function ( abm_simulate) outputs a list containing: (1) a dataframe of realised movements, (2) a dataframe of options the animal had available, and (3) a list of the inputs used to simulate the movement. The realised movement dataframe ( locations) describes all realised locations the animal occupied, step length information, behavioural state, and current point of attraction, where each row is equal to a time step. Note the simulation is scale agnostic, so each row can represent a different time step to the example. Other than the lack of timestamps and location error, the format largely mirrors a typical movement dataset. Our example is minute by minute; changing the time step would require a reparametrisation of step length and behavioural transition probabilities. The options dataframe describes all the options available to the animal over the entire simulation duration, where each row is equal to an option repeated for each time step.

3.2 Outputs review

Once simulated, we can review the movement characteristics of the three species. The simplest to examine is the movement speeds or step lengths. During the simulation parametrisation we provided rescale values for the size of the cells describing environmental information (see rescale_step2cell argument). The simulated movement will return the scaled values, so to plot something comparable to the input values, we must rescale the simulated step lengths.

We can compare the simulation’s inputs displayed in Figure 4 to the simulated/observed outputs displayed in Figure 5 and see that they largely agree as expected. The turn angles are more variable, as the destination decisions and attraction to locations heavily influence the distribution overriding the initial parametrisation of the Von Mises distribution. Figure 10 and Figure 12 in the uses cases section show the outputs for vulture and king cobra simulations.

Figure 5. The badger example’s simulated/observed turn angles and step lengths.

Step lengths are scaled to the input units. Inset pie chart show the number of step lengths that were below the shelter site size; the sub-shelter site step lengths are excluded from the density plot. Note that x axis is not consistent between the three plots.

We can review how the movements appear in space. With the badger example, the impact of the avoidance points is clearly visible [ Figure 6A, Figure 7A], whereas the lack of or weaker avoidance in vulture [ Figure 6B] and king cobra [ Figure 6C] makes the avoidance less influential. The vulture’s movements and chosen foraging locations are largely to the east [ Figure 7B], demonstrating the impact of the underlying foraging quality environmental layer. The king cobra plot shows the impact of a near impermeable barrier truncating the southward movements [ Figure 7C].

Figure 6. The observed locations of the three simulated species (A - Badger, B - Vulture, C - King Cobra).

Black points show the observed location at each time step. The orange squares show the dynamically selected foraging destinations. Circles with an interior S show the shelter site locations, and cricles with an interior A show the avoidance points. Note that the size represented by each unit on the x and y axis differs depending on the species.

Figure 7. The observed locations of the three simulated species (A - Badger, B - Vulture, C - King Cobra) over the first month of time steps.

Grey path shows the overall movement during that month, overlaid points indicate where the animal was in a given behavioural mode. Circles with an interior S show the shelter site locations, and cricles with an interior A show the avoidance points, black squares show the dynamically selected foraging destinations. Note that the size represented by each unit on the x and y axis differs depending on the species.

The activity cycles and the timing of behavioural shifts is a key component in the simulations. We can examine that the predefined cycles result in expected patterns. A year of data makes observing all but the broadest cycles difficult, so in Figure 8 we can look at several months of data as well as the daily cycle. Badger and vulture daily cycles are largely the same [ Figure 8A & B], with a consistent daily activity cycle differing only slightly in the time spent active and balance between shifts from sheltering to foraging and exploring. Some of the differences are a result of the different behavioural transition matrix provided to simulated the two species, where both had different baseline probabilities of shifting between behavioural states. By contrast, the king cobra example demonstrates the interaction between the daily and weekly cycles [ Figure 8]. We can see intermittently extended sheltering periods, punctuated by short exploratory or foraging bouts.

Figure 8. The observered (top half) and parametrised activty cycles (bottom half) governing sheltering behaviour in the three example species (A - Badger, B - Vulture, C - King Cobra).

Point colour and position describe the behavioural state at each simulated time step, whereas the purple waves indicated the input values. Note that the input waves acting on the simulated animal in conjunction with the beahvioural transition matrix.

At the daily and monthly scale, we cannot see the impact of the broad scale seasonal cycles. Instead we can look at the percentage of time steps per day the animal was in sheltering behaviour [ Figure 9]. Again the Badger and Vulture sheltering rates are similar, differing in intensity, but with both demonstrating a seasonal decrease in the middle of the simulation. The king cobra cycles reveal decrease in the number of days spent entirely sheltering and an overall impression that the seasonal cycle is less influential (as it is only one of three activity cycles).

Figure 9. The percentage of time steps spent in state 0 - resting per day, and how it varies over the entire simulated year. 4. Discussion

Animal movement datasets are complex and require a suite of analytical approaches to tackle satisfactorily. Efforts to develop new, and test existing, analyses would be aided by access to a range of diverse datasets. While ideal simulations often accompany new analysis methods and provide superb validation for the method in question, reaffirming the method’s robustness and pushing them to new limits with a messier, more stochastic, simulation approach could greatly strengthen our confidence in results. The abmAnimalMovement package provides an independent route to test new methods that covers a range of interacting movement features, not necessarily directly tied to a single analytical method.

By including a range of features linked to movement and behaviour, the abmAnimalMovement package can be implemented to investigate a suite of questions commonly asked of movement data –from habitat selection, to behaviour detection (for examples of common themes see Ref. 13). While some of the features can appear simplistic, there remains ample flexibility to simulate a wide range of useful scenarios. For example, we conceptualise the three movement states as sheltering, exploring, and foraging. However, only several aspects are immutable: one state exhibits site fidelity (state 0), one state is free from all attraction (state 1), and one state is driven by an underlying environmental layer (state 2).

The abmAnimalMovement package has an advantage over data-driven simulation methods in scenarios where data are scarce, as much of the animal world is untracked. ¹³ ^, ²⁵ For the untracked animals, we may be limited to basic information of speed, activity, and resources, or such information may even need to be inferred from ecologically similar species. In such data starved situations, the abmAnimalMovement package’s low computational cost and minimal data requirements allows for a large number of alternative parametrisations to be explored. Via the explorations of different parametrisations researchers can help build a picture of the study and analysis methods best suited for their questions, with the opportunity to test those analyses on synthetic simulated data.

In cases where data cannot be shared (e.g. due to concerns over species sensitivity), using a synthetic dataset could allow researchers to provide peer reviewers a dataset to test and error-check analysis code. ⁹³ Providing data is a key component to ensuring computational reproducibility, ⁹⁴ and synthetic datasets provide an avenue to limit the reproducibility loss from data sharing restrictions. Additionally, such synthetic datasets could be integrated into preregistration as a means of demonstrating the validity of an analysis plan prior to undertaking a study.

Producing a range of simulated datasets that cover alternate scenarios may present researchers opportunities to test real data against a null model. For example, researchers looking to investigate whether an animal was avoiding a certain landscape feature could calibrate a number of simulations covering a range of differing avoidance strengths. The simulated results could then be compared to the real data to gauge how different the real data was from simulations exhibiting zero avoidance (i.e., a null model scenario). This approach could complement current analysis methods, akin to sensitivity analysis.

4.1 Future directions

The abmAnimalMovement package provides adequate functionality to simulate a range of scenarios and movements. However, there are several aspects that will bear updating in future versions. 1.

Dynamic state 0. While state 0 and the steady state of the attraction locations is key to simulating range stability (i.e., home range), there maybe scenarios where this stability is not desired. For example, simulating dispersal behaviour of juvenile or sub-adult animals there may be a desire to have shelter site dynamically chosen for a time. Currently such behaviour could be simulated, but it would require the dispersal to occur immediately, and the dispersal destination to be predefined (i.e., the sites for state 0 attraction). Therefore, in the current state the package may be limited in its ability to help predict possible dispersal destination, but potentially capable of informing dispersal routes.

Autocorrelated speed. We may need to improve the autocorrelation of the animal’s speed. Currently the speeds are non-independent based on the behavioural mode of the animal. The need to implement a more aggressive movement momentum/autocorrelative structure may be felt more acutely at different time frames, and for animals with a great variation in step lengths (i.e., a larger θ for the Gamma distribution). Explorations of simulated data using methods that measure autocorrelation in animal speed will reveal how much of a priority this should be.

Dynamic environment. All the environmental matrices are static; currently there is no system to update values during the simulation. This prevents shifts in the landscape such as seasonal variation in resources, or the development of trails. Currently, the closest solution is to run multiple simulations where the end location of simulation ₁ is the start location for simulation ₂, where simulation ₂ is provided with a new season-appropriate resource layer. This solution would be inadequate for trail development, as trail development would require a system within the simulation to update previously used cells for the animal at each time step.

4.2 Use cases

This section provides alternative parametrisations for the secondary examples to better demonstrate the range of movement types and scenarios the abmAnimalMovement package can replicate. We provide example implementations of vulture and king cobra-like movement.

4.2.1 Ecology and objectives - vulture

Unlike badgers and other terrestrially moving animals, vultures can move great distances with minimal obstruction [ Figure 11]. Vultures can also move greater distances more rapidly, ⁹⁵ resulting in a more variable and distribution of step lengths ⁹⁶ ^– ⁹⁸ [ Figure 10].

Figure 10. The distribution of step lengths used during the vulture simulation example.

The distribution displayed is generated from the same shape and scale parameters that will be input into the simulation function for the vulture simulation. The lower plot shows the distribution used to generate potential foraging desintations.

Similar to badgers vultures exhibit significant site fidelity, re-using roosting and nesting sites. ⁹⁹ Such shelter sites could be predefined; for example, if shelter sites were known a priori discovered via the capture and tagging of animals, which in the case of birds is more likely.

Vultures also offer an opportunity to demonstrate how the underlying resource availability impact the movements of animals. In the case of vultures, their moments have been seen to follow carcass, creating starkly contrasting areas where vultures will and will not travel ⁹ [ Figure 11].

Figure 11. The three resulting landscape layers to be fed into the simulation for the vulture example: shelter quality, foraging resources, movement ease.

Vultures have a very similar cycle pattern to the badgers (just inverted), one defined by a standard 12 hours of activity during the day, and 12 hours of increased resting behaviour during the night. The importance of simulating such cycles is made clear by vultures studies demonstrating that day-night cycles can impact rates of location collection. ¹⁰⁰ How the the animals’ activity cycle and the probability of collected data interact could be key consideration for some research questions. Again similar to badgers we would expect seasonal shifts in the form of an increase and decrease in activity depending on the time of year. ⁹⁵ ^– ⁹⁷ ^, ¹⁰¹

We can broadly summarise the vulture ecology we want to parametrise as follows: 1.

Medium site fidelity via the use of multiple roosting/resting sites ⁹⁹

Movement speed approximated by summary statistics from previous studies, ⁹⁵ ^– ⁹⁸ with minimal landscape derived resistance

A 8-12 hour activity cycle, ¹⁰⁰ that shifts over the year ⁹⁵ ^, ⁹⁶ ^, ¹⁰¹

4.2.2 Ecology and objectives - king cobra

Whereas the previous two species have a very limited or single shelter sites, king cobras make use of a wider range of shelter sites distributed more widely over their home ranges. ¹⁰² ^, ¹⁰³ These sites can also be larger, comprising burrow systems or rock complexes.

What more dramatically sets king cobras, and other snakes, apart is a vastly differing rest-forage cycle. While snakes still exhibit a diel cycle, the intermittent depredation of large prey items and the time required sheltering to digest large meals results in a second broader activity cycle operating over a more widely observed diel cycle. ¹⁰³ ^– ¹⁰⁶ We can conceptualise this pattern as two additive cycles, one that will describe the daily activity cycle, and a second that describes the foraging and digestion cycle. Seasonality also impacts king cobra activity. As king cobras occupy tropical regions, the seasonality they experience is not as pronounced as the badger or vulture examples. Overall king cobras have three activity cycles acting on three different scales.

In this example we can also demonstrate the movement resistance dramatically impacting movement possibilities. King cobra movement can be limited by roads, ¹⁰⁷ ^, ¹⁰⁸ where unless provided with crossing structures king cobras are vulnerable to vehicle hits [ Figure 13]. In addition to roads presenting linear barriers across the landscape, king cobras face persecution when near or in human settlements. ¹⁰⁸ ^, ¹⁰⁹ Despite the risks, avoidance of such areas appears weak.

Finally, king cobra movement characteristics will be dramatically reduced compared to the vulture’s, but with similar shape to the badger with greater variability [ Figure 12] as king cobras are known to range over large areas. ¹⁰² ^, ¹⁰³ ^, ¹¹⁰

Figure 12. The distribution of step lengths used during the king cobra simulation example.

The distribution displayed is generated from the same shape and scale parameters that will be input into the simulation function for the king cobra simulation. The lower plot shows the distribution used to generate potential foraging desintations.

We can broadly summarise the king cobra ecology we want to parametrise as follows: 1.

Lower site fidelity via the use of many shelter sites ¹⁰² ^, ¹⁰³

Movement speed approximated by summary statistics from previous studies, ¹⁰² ^, ¹⁰³ ^, ¹¹⁰ with examples of very high landscape derived resistance ¹⁰⁷ ^, ¹⁰⁸

A 8-12 hour activity cycle, with a approximately weekly forage-digest cycle, and weak seasonality ¹⁰³ ^– ¹⁰⁶

4.2.3 Simulation inputs

Vulture Inputs Largely the vulture parametrisation matches the badger. We specified a number of predefined resting/shelter sites, assuming that bird bio-tagging is more likely to occur at known site (i.e., nests or roosts). The shelter site size is smaller than the badger sett, so is only 5 m. Step length parameters are all larger and more variable, along with destination ranges [ Figure 10]. We set a larger rescale value also to ensure the vulture has a larger landscape to operate across. The rest cycle is broadly similar, with a 12 hour diel cycle and gentle seasonality. We make two small modifications to the transition matrix allows for more frequent switches between foraging and exploring. We also alter two of the environmental matrices. We maximise movement ease across the entire landscape, while also lowering the foraging quality for an area to the West reflecting lower resources in that area [ Figure 11]. Finally, we specify that the vulture will not be avoiding any locations; we still require inputs for the simulation, but we can provide zeroes to negate the effect. # predefined shelter sites VULTURE_shelterLocs ˂- data.frame( "x" = c(1024}, 1005, 1115), "y" = c(1193, 1070, 882)) # shelter site radius to reduce movements VULTURE_shelterSize ˂- 5 # parameters defining Gamma (step length) and Von Mises (turn angle) for each # behaviour state # Gamma shape VULTURE_k_step ˂- c(2, 2.2*60, 1.5*60) # Gamma scale VULTURE_s_step ˂- c(40, 1.2, 1) # Von Mises mean VULTURE_mu_angle ˂- c(0, 0, 0) # Von Mises concentration VULTURE_k_angle ˂- c(0.6, 0.99, 0.6) # parameters defining Gamma (shape and scale) and Von Mises (mean and # concentration) for foraging destination options VULTURE_destinationRange ˂- c(50, 120) VULTURE_destinationDirection ˂- c(0, 0.01) # the transformation (2 = squared) and strength of attraction to destinations VULTURE_destinationTransformation ˂- 2 VULTURE_destinationModifier ˂- 2 # each cell of the environmental matrix is 20x20 VULTURE_rescale ˂- 20 # the diel resting/active cycle: amplitude, midline, offset, frequency VULTURE_rest_Cycle ˂- c(0.1, 0, 24, 24) # additional cycles as a dataframe: amplitude, midline, offset, frequency c0 ˂- c(0.025, 0, 24* (365/2), 24* 365) # seasonal VULTURE_additional_Cycles ˂- rbind(c0) # select modifications to the default behavioural transition matrix VULTURE_behaveMatrix ˂- Default_behaveMatrix VULTURE_behaveMatrix[2,3] ˂- 0.0002 VULTURE_behaveMatrix[3,2] ˂- 0.000015 # maximising movement ease by changing the default movement matrix VULTURE_movementMatrix ˂- landscapeLayersList$movement VULTURE_movementMatrix[] ˂- 1 # reducing foraging quality in the West of the landscape VULTURE_forageMatrix ˂- landscapeLayersList$forage VULTURE_forageMatrix[1:950,1:2000] ˂- VULTURE_forageMatrix[1:950,1:2000] - 0.6 VULTURE_forageMatrix[VULTURE_forageMatrix[˂ 0] ˂- 0 # place holder avoidance location VULTURE_avoidLocs ˂- data.frame( "x" = c({1000), "y" = c(1000)) # vulture has zero avoidance of the place holder point VULTURE_avoidTransformation ˂- 0 VULTURE_avoidModifier ˂- 0

King Cobra Inputs Compared to the vulture, the king cobra movements are smaller, but king cobras can still occupy large areas [ Figure 12]. We provide a rescale value of 10 m to provide a large enough landscape to capture a potentially large range. The activity cycle provides an opportunity to demonstrate three additive cycles. The diel cycle is largely similar to the other examples, but we also define an approximately weekly cycle to cover the forage-digestion cycle as well as weak seasonal cycle. Combined the three cycles create an activity pattern quite different from either the badger or vulture. To balance the three cycles and their influence on the behaviour transitions, we make some minor adjustments to the underlying behavioural transition matrix. As mentioned in the ecology and justifications, we want to simulate a barrier limiting movement. We construct this by altering the values in the environmental matrices, minimising the weighting in cells following two perpendicular lines [ Figure 13]. We also provide a set of avoidance locations and a relatively weak avoidance weighting coefficient. Finally, we can set the shelter sites. We draw 12 sites randomly based on shelter site quality, and limit the area that they can be draw from to ensure they are not on the far side of the barrier. We use a larger shelter site size, as king cobras are known to occupy large rock complexes at times. # parameters defining Gamma (step length) and Von Mises (turn angle) for each # behaviour state # Gamma shape KINGCOBRA_k_step ˂- c(30, 40, 20) # Gamma scale KINGCOBRA_s_step ˂- c(0.75, 1.2, 1.75) # Von Mises mean KINGCOBRA_mu_angle ˂- c(0, 0, 0) # Von Mises concentration KINGCOBRA_k_angle ˂- c(0.6, 0.99, 0.6) # parameters defining Gamma (shape and scale) and Von Mises (mean and # concentration) for foraging destination options KINGCOBRA_destinationRange ˂- c(50, 10) KINGCOBRA_destinationDirection ˂- c(0, 0.01) # the transformation (2 = squared) and strength of attraction to destinations KINGCOBRA_destinationTransformation ˂- 2 KINGCOBRA_destinationModifier ˂- 1.5 # each cell of the environmental matrix is 10x10 KINGCOBRA_rescale ˂- 10 # the diel resting/active cycle: amplitude, midline, offset, frequency KINGCOBRA_rest_Cycle ˂- c(0.14, 0, 24, 24) # additional cycles as a dataframe: amplitude, midline, offset, frequency c0 ˂- c(0.12, 0, 24, 24*4) # digestion c1 ˂- c(0.05, 0, 24 * (365/2), 24* 365) # seasonal KINGCOBRA_additional_Cycles ˂- rbind(c0, c1) # select modifications to the default behavioural transition matrix KINGCOBRA_behaveMatrix ˂- Default_behaveMatrix KINGCOBRA_behaveMatrix[1,1] ˂- 0.95 KINGCOBRA_behaveMatrix[1,2] ˂- 0.005 KINGCOBRA_behaveMatrix[3,1] ˂- 0.00025 KINGCOBRA_behaveMatrix[3,2] ˂- 0.000001 KINGCOBRA_behaveMatrix[3,3] ˂- 0.999 # extracting the default matrices ready for changes KINGCOBRA_shelteringMatrix ˂- landscapeLayersList$shelter KINGCOBRA_forageMatrix ˂- landscapeLayersList$forage KINGCOBRA_movementMatrix ˂- landscapeLayersList$movement # defining the start and end of strong intersections hampering movement roadMin_x ˂- 1360 roadMax_x ˂- roadMin_x + 40 roadMin_y ˂- 660 roadMax_y ˂- roadMin_y + 40 # applying the change, dramatically reducing the weighting for all matrices KINGCOBRA_shelteringMatrix[roadMin_x:roadMax_x,1:2000] ˂- KINGCOBRA_shelteringMatrix[roadMin_x:roadMax_x,1:2000] - 90 KINGCOBRA_shelteringMatrix[1:2000,roadMin_y:roadMax_y] ˂- KINGCOBRA_shelteringMatrix[1:2000,roadMin_y:roadMax_y] - 90 KINGCOBRA_shelteringMatrix[!{KINGCOBRA_shelteringMatrix >= -99.9] ˂- -99 KINGCOBRA_forageMatrix[roadMin_x:roadMax_x,1:2000] ˂- KINGCOBRA_forageMatrix[roadMin_x:roadMax_x,1:2000] - 90 KINGCOBRA_forageMatrix[1:2000,roadMin_y:roadMax_y] <- KINGCOBRA_forageMatrix[1:2000,roadMin_y:roadMax_y] - 90 KINGCOBRA_forageMatrix[!KINGCOBRA_forageMatrix >= -99.9] <- -99 KINGCOBRA_movementMatrix[roadMin_x:roadMax_x,1:2000] <- KINGCOBRA_movementMatrix[roadMin_x:roadMax_x,1:2000] - 90 KINGCOBRA_movementMatrix[1:2000,roadMin_y:roadMax_y] <- KINGCOBRA_movementMatrix[1:2000,roadMin_y:{roadMax_y] - 90 KINGCOBRA_movementMatrix[!KINGCOBRA_movementMatrix >= -99.9] <- -99 # defining a number of avoidance points KINGCOBRA_avoidLocs <- data.frame( "x" = c(552, 1232, 1587), "y" = c(789, 975, 1356)) # and specifying a weak avoidance of the points KINGCOBRA_avoidTransformation <- 2 KINGCOBRA_avoidModifier <- 1 # after the matrices have been altered, drawing 12 shelter sites based on shelter quality sampledShelters <- sampleRandom (raster (KINGCOBRA_shelteringMatrix), 12, ext = extent(0.35, 0.65, 0.42, 0.65), rowcol = TRUE) # and storing those shelter sites as a dataframe ready for the simulation function KINGCOBRA_shelterLocs <- data.frame( "x" = sampledShelters[,2], "y" = sampledShelters[,1]) # specifying a larger shelter site radius KINGCOBRA_shelterSize <- 10

Figure 13. The three resulting landscape layers to be fed into the simulation for the king cobra example: shelter quality, foraging resources, movement ease.

Movement ease is blocked by bars of -99 weighting.

4.2.4 Simulation outputs

Figures 10 and 12 describe the inputs for the vulture and king cobra example respectively, and can be compared to Figures 14 and 15 that display the realised movements. Figures 14, and 15 also provide information on the rates of stationary behaviour, defined in the plot as step lengths less than the shelter site size. The king cobra example in particular highlights the prolonged near weekly resting periods.

Figure 14. The vulture example’s observed turn angles and step lengths resulting from the simulation.

Step lengths are scaled back to the input units. Inset pie chart show the number of step lengths that were below the shelter site size; the sub-shelter site step lengths are excluded from the density plot. Note that x axis is not consistent between the three plots.

Figure 15. The king cobra example’s observed turn angles and step lengths resulting from the simulation.

Data availability

The parameters used to generate the examples (based on Refs. 58– 63 for the badger example; Refs. 95– 101 for the vulture example; and Refs. 102– 110 for the king cobra example) presented in this study are included in the GitHub and Zenodo repositories in the file ‘notebook/manuscript/Agent-based_model_walkthrough.Rmd’.

Zenodo: Simulated data from abmAnimalMovement: An R package for simulating animal movement using an agent-based model, https://doi.org/10.5281/zenodo.6992495. ¹¹¹

This project contains the following underlying data: •

eg_simdata_BADGER_locations.csv (A csv file that contains the realised locations of the example badger simulation, where each row is equal to a timestep. Columns include: timestep, the timestep as a integer; x, the x coordinate of the animal; y, the y coordinate of the animal; sl, the step length between locations used during the simulation; sl_rescale the rescale factor required to return step lengths back to the input scale; ta, turning angle between locations in degrees; behave, the behavioural mode the animal was in at a given timestep; chosen, the location chosen out of the number of options available; destination_x and destination_y the point the animal was attracted to at that time (note exploratory behaviour is not subject attraction)).

•

eg_simdata_BADGER_options.csv (A csv file that contains the options available to the example badger simulation over the entire simulation duration, where each row is equal to an option repeated for each timestep. Columns include: timestep, the timestep as an integer; oall_x, and oall_y show the x and y coordinates of all the options available to an animal at a timestep; oall_steplengths are the step lengths from the current location compared to all the options).

•

eg_simdata_completelist.RDS (This RDS file contains a list object of length three, where the full simulation outputs from each three example is stored. Each species slot contains the “locations” dataframe (see description of locations.csv), the “options” dataframe (see description of options.csv), and a nested list containing all the “inputs” used to generate the simulated results (split into subsections: inputs_basic that contains inputs linked to simulation duration and intensity, inputs_destination that contains inputs linked to destination and attraction aspects, inputs_movement that contains inputs linked to movement capacity and behavioural switching, inputs_cycle that contains inputs linked to activity cycling, inputs_layerSeed that contains the environmental matrices and seed). A fourth object is return called “others” that captures all other outputs, mainly used internally for debugging and checking).

•

eg_simdata_KINGCOBRA_locations.csv (A csv file that contains the realised locations of the example king cobra simulation, where each row is equal to a timestep. The file structure follows the same as the BADGER_options.csv file).

•

eg_simdata_KINGCOBRA_options.csv (A csv file that contains the options available to the example king cobra simulation over the entire simulation duration, where each row is equal to an option repeated for each timestep. The file structure follows the same as the BADGER_options.csv file).

•

eg_simdata_VULTURE_locations.csv (A csv file that contains the realised locations of the example vulture simulation, where each row is equal to a timestep. The file structure follows the same as the BADGER_locations.csv file).

•

eg_simdata_VULTURE_options.csv (A csv file that contains the options available to the example vulture simulation over the entire simulation duration, where each row is equal to an option repeated for each timestep. The file structure follows the same as the BADGER_locations.csv file).

Data are available under the terms of the Creative Commons Attribution 4.0 International license (CC-BY 4.0).

Software availability

Source code available from: https://github.com/BenMMarshall/abmAnimalMovement/tree/v.0.1.3.0000

Archived source code at time of publication: https://doi.org/10.5281/zenodo.6951938 ¹¹²

License: GPL-3.0-only

References 1

Bastille-Rousseau

Murray

Schaefer

: Spatial scales of habitat selection decisions: Implications for telemetry-based movement modelling. Ecography. 2017;40:1–7.

Sridhar

Gorbonos

: The geometry of decision-making in individuals and collectives. Proc. Natl. Acad. Sci. 2021 Dec [cited 2022 May 3];118(50):e2102157118. 34880130

10.1073/pnas.2102157118

Prange

Gehrt

Wiggers

: Influences of anthropogenic resources on raccoon (Procyon lotor) movements and spatial distribution. J. Mammal. 2004;85(3):8.

Christy

Savidge

Yackel Adams

: Experimental landscape reduction of wild rodents increases movements in the invasive brown treesnake (Boiga irregularis). Manag. Biol. Invasion. 2017 [cited 2021 Aug 22];8(4):455–467. 10.3391/mbi.2017.8.4.01

Reference Source

Vogt

Vimercati

Ryser

: Suitability of GPS telemetry for studying the predation of Eurasian lynx on small- and medium-sized prey animals in the Northwestern Swiss Alps. Eur. J. Wildl. Res. 2018 Dec [cited 2020 Mar 13];64(6):73. 10.1007/s10344-018-1225-7

Loveridge

Valeix

Elliot

: The landscape of anthropogenic mortality: How African lions respond to spatial variation in risk. Howe C, editor. J. Appl. Ecol. 2017 Jun [cited 2019 Jun 4];54(3):815–825. 10.1111/1365-2664.12794

Tucker

Böhning-Gaese

Fagan

: Moving in the Anthropocene: Global reductions in terrestrial mammalian movements. Science. 2018 Jan;359(6374):466–469. 29371471

10.1126/science.aam9712

Tucker

Alexandrou

Bierregaard

: Large birds travel farther in homogeneous environments. Boucher-Lalonde V, editor. Glob. Ecol. Biogeogr. 2019 May [cited 2019 May 6];28(5):576–587. 10.1111/geb.12875

Arrondo

Moleón

Cortés-Avizanda

: Invisible barriers: Differential sanitary regulations constrain vulture movements across country borders. Biol. Conserv. 2018 Mar [cited 2022 May 25];219:46–52. 10.1016/j.biocon.2017.12.039

Reference Source

Fraser

Davies

Davy

: Tracking the conservation promise of movement ecology. Front. Ecol. Evol. 2018;6(October):150. 10.3389/fevo.2018.00150/full?utm_source=F-NTF\&utm_medium=EMLX\&utm_campaign=PRD_FEOPS_20170000_ARTICLE

Noonan

Fleming

Tucker

: Effects of body size on estimation of mammalian area requirements. Conserv. Biol. 2020 Jun [cited 2020 Jun 23];34:1017–1028. 10.1111/cobi.13495

Studd

Derbyshire

Menzies

: The Purr-fect Catch: Using accelerometers and audio recorders to document kill rates and hunting behaviour of a small prey specialist. Methods Ecol. Evol. 2021 Jul [cited 2022 May 25];12(7):1277–1287. 10.1111/2041-210X.13605

Joo

Picardi

Boone

: Recent trends in movement ecology of animals and human mobility. Mov. Ecol. 2022 May [cited 2022 Jun 3];10(1):26. 35614458

10.1186/s40462-022-00322-9

Wild

Wikelski

Tyndel

: Internet on animals: Wi-Fi-enabled devices provide a solution for big data transmission in biologging. Methods Ecol. Evol. 2022 Jan [cited 2022 May 25]; 2041–210X.13798. 10.1111/2041-210X.13798

Kays

Davidson

Berger

: The Movebank system for studying global animal movement and demography. Methods Ecol. Evol. 2022 Feb [cited 2022 May 25];13(2):419–431. 10.1111/2041-210X.13767

Saunders

Nguyen

Cowen

: Radio-tracking wildlife with drones: A viewshed analysis quantifying survey coverage across diverse landscapes. Wildl. Res. 2022 Feb [cited 2022 May 25];49(1):1–10. 10.1071/WR21033

Reference Source

Weatherhead

Blouin-Demers

: Long-term effects of radiotelemetry on black ratsnakes. Wildl. Soc. Bull. 2004;32(3):900–906. 10.2193/0091-7648(2004)032[0900:LEOROB]2.0.CO;2

Reference Source

Robstad

Lodberg-Holm

Mayer

: The impact of bio-logging on body weight change of the Eurasian beaver. PLoS One. 2021 Dec [cited 2022 May 3];16(12):e0261453. 10.1371/journal.pone.0261453

Portugal

White

: Externally attached biologgers cause compensatory body mass loss in birds. Methods Ecol. Evol. 2022 [cited 2022 May 3];13(2):294–302. 10.1111/2041-210X.13754

Clark

Raby

Roche

: Ocean acidification does not impair the behaviour of coral reef fishes. Nature. 2020 Jan [cited 2020 Jul 21];577(7790):370–375. 10.1038/s41586-019-1903-y

Reference Source

Roche

Amcoff

Morgan

: Behavioural lateralisation in a detour test is not repeatable in fishes. EcoEvoRxiv. 2020;62. Reference Source

Sánchez-Tójar

Nakagawa

Sánchez-Fortún

: Meta-analysis challenges a textbook example of status signalling and demonstrates publication bias. elife. 2018 Nov [cited 2020 Jul 21];7:e37385. 30420005

10.7554/eLife.37385

Reference Source

Wang

Forstmeier

Ihle

: Irreproducible text-book “knowledge”: The effects of color bands on zebra finch fitness: COLOR BANDS HAVE NO EFFECT ON FITNESS IN ZEBRA FINCHES. Evolution. 2018 Apr [cited 2020 Jul 21];72(4):961–976. 29574894

10.1111/evo.13459

Fraser

Barnett

Parker

: The role of replication studies in ecology. Ecol. Evol. 2020 Jun [cited 2021 Oct 12];10(12):5197–5207. 32607143

10.1002/ece3.6330

Crane

Silva

Marshall

: Lots of movement, little progress: A review of reptile home range literature. PeerJ. 2021 Jul [cited 2021 Jul 20];9:e11742. 34322323

10.7717/peerj.11742

Reference Source

Tam

Lagisz

Cornwell

: Quantifying research interests in 7,521 mammalian species with h-index: A case study. EcoEvoRxiv. 2021 Nov [cited 2022 May 25]. Reference Source

Williams

Taylor

Benhamou

: Optimizing the use of biologgers for movement ecology research. Gaillard J, editor. J. Anim. Ecol. 2020 Jan [cited 2020 Jan 31];89(1):186–206. 31424571

10.1111/1365-2656.13094

Christie

Amano

Martin

: Simple study designs in ecology produce inaccurate estimates of biodiversity responses. J. Appl. Ecol. 2019 [cited 2022 May 3];56(12):2742–2754. 10.1111/1365-2664.13499

Gupta

Dilkina

Morin

: Reserve design to optimize functional connectivity and animal density. Conserv. Biol. 2019 Jul [cited 2019 Jul 13];33:1023–1034. 31209924

10.1111/cobi.13369

DeBruine

Barr

: Understanding Mixed-Effects Models Through Data Simulation. Adv. Methods Pract. Psychol. Sci. 2021;4(1):1–5.

Sciaini

Fritsch

Scherer

: NLMR and landscapetools: An integrated environment for simulating and modifying neutral landscape models in R. Golding N, editor. Methods Ecol. Evol. 2018 Nov;9(11):2240–2248. 10.1111/2041-210X.13076

Petr

Haller

Ralph

Racimo

: Slendr: A framework for spatio-temporal population genomic simulations on geographic landscapes. bioRxiv. 2022 [cited 2022 May 3]. 10.1101/2022.03.20.485041v1

Guerra-Castro

Cajas

Simões

: SSP: An R package to estimate sampling effort in studies of ecological communities. Ecography. 2021 Apr [cited 2022 May 25];44(4):561–573. 10.1111/ecog.05284

Street

Potts

Börger

: Solving the sample size problem for resource selection functions. Methods Ecol. Evol. 2021 Dec [cited 2022 May 25];12(12):2421–2431. 10.1111/2041-210X.13701

Goldstein

Erinjery

Martin

: Integrating human behavior and snake ecology with agent-based models to predict snakebite in high risk landscapes. Habib AG, editor. PLoS Negl. Trop. Dis. 2021 Jan [cited 2022 May 25];15(1):e0009047. 33481802

10.1371/journal.pntd.0009047

Ahearn

Smith

JLD

Joshi

: TIGMOD: An individual-based spatially explicit model for simulating tiger/human interaction in multiple use forests. Ecol. Model. 2001 May;140(1-2):81–97. 10.1016/S0304-3800(01)00258-7

Theng

Milleret

Bracis

: Confronting spatial capture–recapture models with realistic animal movement simulations. Ecology. 2022 [cited 2022 May 3];103:e3676. 35253209

10.1002/ecy.3676

Howe

Buckland

Després-Einspenner

: Distance sampling with camera traps. Methods Ecol. Evol. 2017 [cited 2022 May 4];8(11):1558–1565. 10.1111/2041-210X.12790

Cappelle

Howe

Boesch

: Estimating animal abundance and effort–precision relationship with camera trap distance sampling. Ecosphere. 2021 [cited 2022 May 4];12(1):e03299. 10.1002/ecs2.3299

Kellner

Parsons

Kays

: A Two-Species Occupancy Model with a Continuous-Time Detection Process Reveals Spatial and Temporal Interactions. J. Agric. Biol. Environ. Stat. 2022 Jun [cited 2022 May 25];27(2):321–338. 10.1007/s13253-021-00482-y

Milleret

Dey

Dupont

: Estimating spatially variable and density-dependent survival using open-population spatial capture-recapture models. bioRxiv. 2022 Mar [cited 2022 May 25]. 10.1101/2022.03.04.482982

Abolaffio

Focardi

Santini

: Avoiding misleading messages: Population assessment using camera trapping is not a simple task. J. Anim. Ecol. 2019 [cited 2022 May 3];88(12):2011–2016. 31523817

10.1111/1365-2656.13085

Calabrese

Fleming

Gurarie

: Ctmm: An R Package for Analyzing Animal Relocation Data As a Continuous-Time Stochastic Process. Methods Ecol. Evol. 2016;7(9):1124–1132. 10.1111/2041-210X.12559

Silva

Fleming

Noonan

: Autocorrelation-informed home range estimation: A review and practical guide. Methods Ecol. Evol. 2022 Mar [cited 2022 May 25];13(3):534–544. 10.1111/2041-210X.13786

Fleming

Calabrese

Mueller

: From Fine-Scale Foraging to Home Ranges: A Semivariance Approach to Identifying Movement Modes across Spatiotemporal Scales. Am. Nat. 2014;183(5):E154–E167. 24739204

10.1086/675504

Michelot

Langrock

Patterson

: moveHMM: An r package for the statistical modelling of animal movement data using hidden Markov models. McInerny G, editor. Methods Ecol. Evol. 2016 Nov;7(11):1308–1315. 10.1111/2041-210X.12578

Tang

Bennett

: Agent-based Modeling of Animal Movement: A Review. Geogr. Compass. 2010 Jul;4(7):682–700. 10.1111/j.1749-8198.2010.00337.x/full

Quaglietta

Porto

: SiMRiv: An R package for mechanistic simulation of individual, spatially-explicit multistate movements in rivers, heterogeneous and homogeneous spaces incorporating landscape bias. Mov. Ecol. 2019 Dec [cited 2022 May 25];7(1):11. 30984401

10.1186/s40462-019-0154-8

Van Moorter

Visscher

Benhamou

: Memory keeps you at home: A mechanistic model for home range emergence. Oikos. 2009;118(5):641–652. 10.1111/j.1600-0706.2008.17003.x

Bennett

Tang

: Modelling adaptive, spatially aware, and mobile agents: Elk migration in Yellowstone. Int. J. Geogr. Inf. Sci. 2006 Oct [cited 2022 May 25];20(9):1039–1066. 10.1080/13658810600830806

Eddelbuettel

François

: Rcpp: Seamless R and C++ integration. J. Stat. Softw. 2011;40(8):1–8.

Eddelbuettel

: Seamless R and C++ integration with Rcpp. New York: Springer;2013.

Eddelbuettel

Balamuta

: Extending extitR with extitC++: A Brief Introduction to extitRcpp. Am. Stat. 2018;72(1):28–36. 10.1080/00031305.2017.1375990

Joo

Boone

Clay

: Navigating through the r packages for movement. Börger L, editor. J. Anim. Ecol. 2020 Jan [cited 2021 Aug 29];89(1):248–267. 10.1111/1365-2656.13116

Nathan

Getz

Revilla

: A movement ecology paradigm for unifying organismal movement research. Proc. Natl. Acad. Sci. 2008;105(49):19052–19059. 19060196

10.1073/pnas.0800375105

Reference Source

Rivera

Fidino

Farris

: Rethinking habitat occupancy modeling and the role of diel activity in an anthropogenic world. Am. Nat. 2022 May [cited 2022 May 6];200:556–570. 36150193

10.1086/720714

Scharf

Belant

Beyer

: Habitat suitability does not capture the essence of animal-defined corridors. Mov. Ecol. 2018;6(1):18. 30275955

10.1186/s40462-018-0136-2

Kowalczyk

Zalewski

Bogumiła

: Daily movement and territory use by badgers Meles meles in Białowieża Primeval Forest, Poland. Wildl. Biol. 2006 Dec [cited 2022 May 26];12(4):385–391. 10.2981/0909-6396%282006%2912%5B385%3ADMATUB%5D2.0.CO%3B2

Feore

Montgomery

: Habitat effects on the spatial ecology of the European badger ( Meles meles). J. Zool. 1999 Apr [cited 2022 May 26];247(4):537–549. 10.1111/j.1469-7998.1999.tb01015.x

Rosalino

Macdonald

Santos-Reis

: Activity rhythms, movements and patterns of sett use by badgers, Meles meles, in a Mediterranean woodland. Mammalia. 2005 Jan [cited 2022 May 26];69(3-4):395–408. 10.1515/mamm.2005.031/html

Kelly

Gaughran

Mullen

: Extra Territorial Excursions by European badgers are not limited by age, sex or season. Sci. Rep. 2020 Dec [cited 2022 May 25];10(1):9665. 32541685

10.1038/s41598-020-66809-w

Reference Source

Loureiro

Rosalino

Macdonald

: Path tortuosity of Eurasian badgers (Meles meles) in a heterogeneous Mediterranean landscape. Ecol. Res. 2007 Aug [cited 2022 May 26];22(5):837–844. 10.1007/s11284-006-0325-0

Magowan

Maguire

Smith

: Dead-reckoning elucidates fine-scale habitat use by European badgers Meles meles. Animal Biotelemetry. 2022 Dec [cited 2022 May 26];10(1):10. 10.1186/s40317-022-00282-2

Eddelbuettel

Emerson

Kane

: BH: Boost c++ header files. 2021. Reference Source

R Core Team. R: A language and environment for statistical computing. Vienna, Austria: R Foundation for Statistical Computing;2021. Reference Source

Wickham

Hester

Chang

: Devtools: Tools to make developing r packages easier. 2021. Reference Source

RStudio Team: RStudio: Integrated development environment for r. Boston, MA: RStudio, PBC;2021. Reference Source

Allaire

Xie

McPherson

: Rmarkdown: Dynamic documents for r. 2022. Reference Source

Xie

Allaire

Grolemund

: R markdown: The definitive guide. Boca Raton, Florida: Chapman; Hall/CRC;2018. Reference Source

Xie

Dervieux

Riederer

: R markdown cookbook. Boca Raton, Florida: Chapman; Hall/CRC;2020. Reference Source

Xie

: Bookdown: Authoring books and technical documents with R markdown. Boca Raton, Florida: Chapman; Hall/CRC;2016. Reference Source

Xie

: Bookdown: Authoring books and technical documents with r markdown. 2022. Reference Source

Xie

: TinyTeX: A lightweight, cross-platform, and easy-to-maintain LaTeX distribution based on TeX live. TUGboat. 2019;1:30–32. Reference Source

Xie

: Tinytex: Helper functions to install and maintain TeX live, and compile LaTeX documents. 2022. Reference Source

Xie

: Dynamic documents with R and knitr. 2nd ed. Boca Raton, Florida: Chapman; Hall/CRC;2015. Reference Source

Knitr

: A comprehensive tool for reproducible research in R. Stodden

Leisch

Peng

, editors. Implementing reproducible computational research. Chapman: Hall/CRC;2014. Reference Source

Xie

: Knitr: A general-purpose package for dynamic report generation in r. 2022. Reference Source

Müller

: Here: A simpler way to find your files. 2020. Reference Source

Wickham

François

Henry

: Dplyr: A grammar of data manipulation. 2022. Reference Source

Wickham

: Reshaping data with the reshape package. J. Stat. Softw. 2007;21(12):1–20. 10.18637/jss.v021.i12

Reference Source

Wickham

Chang

Henry

: ggplot2: Create elegant data visualisations using the grammar of graphics. 2022. Reference Source

Wickham

: ggplot2: Elegant graphics for data analysis. New York: Springer-Verlag;2016. Reference Source

Wilke

: Ggridges: Ridgeline plots in ggplot2. 2021. Reference Source

Wilke

: Ggtext: Improved text rendering support for ggplot2. 2020. Reference Source

Pedersen

TLG

: gforce: Accelerating ggplot2. 2021. Reference Source

Pedersen

: Patchwork: The composer of plots. 2020. Reference Source

Hijmans

: Raster: Geographic data analysis and modeling. 2022. Reference Source

Bivand

Pebesma

Gomez-Rubio

: Applied spatial data analysis with R. 2nd ed. NY: Springer;2013. Reference Source

Pebesma

Bivand

: Classes and methods for spatial data in R. R News. 2005;5(2):9–13. Reference Source

Pebesma

Bivand

: Sp: Classes and methods for spatial data. 2022. Reference Source

Sciaini

Fritsch

Scherer

: NLMR and landscapetools: An integrated environment for simulating and modifying neutral landscape models in r. Methods Ecol. Evol. 2018;1–9. 10.1111/2041-210X.13076

Sciaini

Fritsch

Hesselbarth

: NLMR: Simulating neutral landscape models. 2021. Reference Source

Quintana

: A synthetic dataset primer for the biobehavioural sciences to promote reproducibility and hypothesis generation. Zaidi M, Büchel C, Bishop DVM, editors. elife. 2020 Mar;9:e53275. 32159513

10.7554/eLife.53275

Gerstner

Moreno-Mateos

Gurevitch

: Will your paper be used in a meta-analysis? Make the reach of your research broader and longer lasting. Methods Ecol. Evol. 2017;8(6):777–784. 10.1111/2041-210X.12758

Hribsek

Plecas

Skoric

: First description of movement and ranging behavior of the Griffon vulture (Gyps fulvus) from Serbia using GPS satellite tracking. Arch. Biol. Sci. 2021 [cited 2022 May 25];73(2):185–195. 10.2298/ABS201210013H

Reference Source

García-Jiménez

Pérez-García

Margalida

: Drivers of daily movement patterns affecting an endangered vulture flight activity. BMC Ecol. 2018 Dec [cited 2022 May 25];18(1):39. 30268111

10.1186/s12898-018-0195-7

Margalida

Pérez-García

Afonso

: Spatial and temporal movements in Pyrenean bearded vultures (Gypaetus barbatus): Integrating movement ecology into conservation practice. Sci. Rep. 2016 Dec [cited 2022 May 25];6(1):35746. 27779179

10.1038/srep35746

Reference Source

Subedi

Pérez-García

Sah

SAM

: Spatial and temporal movement of the Bearded Vulture using GPS telemetry in the Himalayas of Nepal. Ibis. 2020 Apr [cited 2022 May 25];162(2):563–571. 10.1111/ibi.12799

Bracis

Bildstein

Mueller

: Revisitation analysis uncovers spatio-temporal patterns in animal movement data. Ecography. 2018;41:1801–1811. 10.1111/ecog.03618

100

Silva

Afán

Gil

: Seasonal and circadian biases in bird tracking with solar GPS-tags. Margalida A, editor. PLoS One. 2017 Oct [cited 2022 May 25];12(10):e0185344. 29020062

10.1371/journal.pone.0185344

101

Peshev

Grozdanov

Kmetova-Biro

: New insight into spatial ecology of Griffon Vulture (Gyps fulvus) on the Balkans provides opportunity for focusing conservation actions for a threatened social scavenger. Biodivers. Data J. 2021 Aug [cited 2022 May 25];9:e71100. 34531699

10.3897/BDJ.9.e71100

Reference Source

102

Marshall

Strine

Jones

: Space fit for a king: Spatial ecology of king cobras (Ophiophagus hannah) in Sakaerat Biosphere Reserve, Northeastern Thailand. Amphibia-Reptilia. 2019 Mar;40(2):163–178. 10.1163/15685381-18000008

103

Marshall

Crane

Silva

: No room to roam: King Cobras reduce movement in agriculture. Movement. Ecology. 2020 Dec [cited 2020 Aug 4];8(1):33. 32774861

10.1186/s40462-020-00219-5

104

D’souza

Gale

Marshall

: Space use and activity of Boiga cyanea – A major songbird nest predator in a seasonal tropical forest in Thailand. Glob. Ecol. Conserv. 2021 Dec [cited 2021 Oct 27];32:e01875. 10.1016/j.gecco.2021.e01875

Reference Source

105

Smith

Jones

Marshall

: Native Burmese pythons exhibit site fidelity and preference for aquatic habitats in an agricultural mosaic. Sci. Rep. 2021 Dec [cited 2021 Mar 29];11(1):7014. 33782524

10.1038/s41598-021-86640-1

Reference Source

106

Siers

Yackel Adams

Reed

: Behavioral differences following ingestion of large meals and consequences for management of a harmful invasive snake: A field experiment. Ecol. Evol. 2018 Oct;8(20):10075–10093. 30397449

10.1002/ece3.4480

107

Jones

Marshall

Smith

: How do King Cobras move across a major highway? Unintentional wildlife crossing structures may facilitate movement. Ecol. Evol. 2022 Mar [cited 2022 Mar 21];12(3):e8691. 35342558

10.1002/ece3.8691

108

Marshall

Strine

Jones

: Hits Close to Home: Repeated Persecution of King Cobras (Ophiophagus hannah) in Northeastern Thailand. Tropical Conservation Science. 2018 Jan;11:194008291881840. 10.1177/1940082918818401

109

Shankar

Ganesh

Whitaker

: King Cobra Ophiophagus hannah (Cantor, 1836) encounters in human-modified rainforests of the Western Ghats, India. Hamadryad. 2013;36(2):62–68.

110

Silva

Crane

Suwanwaree

: Using dynamic Brownian Bridge Movement Models to identify home range size and movement patterns in king cobras. Munderloh UG, editor. PLoS One. 2018 Sep;13(9):e0203449. 30226846

10.1371/journal.pone.0203449

111

Marshall

Duthie

: Simulated data from abmAnimalMovement: An R package for simulating animal movement using an agent-based model (v.0.1.3.0000). [Data set]. Zenodo.

10.5281/zenodo.6992496

112

Marshall

: BenMMarshall/abmAnimalMovement: v.0.1.3.000 Initial pre-print submission version (v.0.1.3.0000). Zenodo. [Software].

10.5281/zenodo.6951938

10.5256/f1000research.137044.r180404

Reviewer response for version 1

Contina

Andrea

1 Referee https://orcid.org/0000-0002-0484-6711 1Department of Integrative Biology, The University of Texas at Austin, Austin, Texas, USA

Competing interests: No competing interests were disclosed.

16 8 2023

2023

This is an open access peer review report distributed under the terms of the Creative Commons Attribution Licence, which permits unrestricted use, distribution, and reproduction in any medium, provided the original work is properly cited.

recommendation

approve-with-reservations

The manuscript describes a new R package called abmAnimalMovement that ecologists can use to build agent-based movement models. The core of the movement simulations is based on three behavioral states (rest, explore, and forage) and activity cycles. Thus, abmAnimalMovement provides an open-source platform to explore movement parameters and mechanisms underlying animal behavior. Overall, the manuscript is straightforward and generally well-written. Importantly, this new R package facilitates the exploration of complex animal behaviors relevant to movement ecology.

With that being said, I have a few concerns about the clarity of the manuscript as well as the rationale used to develop the examples and figures. The authors offer three examples that describe movement simulations in three species (badger, vulture, and king cobra) but it is hard to tell if these simulations are meaningful. In particular, I am confused by the generation and use of the simulated environmental layers. These raster layers have a significant impact on the movement patterns. However, a mix of approaches is presented; the movement parameters (e.g., speed, home range, etc.) are imported from the literature and the environmental conditions are drawn at random. What are the benefits of this approach? Why not using real environmental raster layers?

Even within the realm of simulated scenarios, which do not always need to be realistic and allow for a mix of observed and alternative/simplified parameters and conditions, there must be a strong rationale that justifies this approach. What did we learn about this R package after running the simulations and comparing these three species? Is there a specific question or hypothesis to test? I understand that the aim of the manuscript is not to investigate ecological questions, but why using three species as opposed to a clear single example? It would be helpful to openly address these questions in the Introduction and Methods.

Also, by looking at the figures, it seems that the movements of the snake are pretty extensive compared to the vulture. This result is counterintuitive. Is this a meaningful movement pattern truly representative of the behavioral differences between the two species?

In my opinion, the presentation of the R package would be much stronger and easy to read if the authors shift their focus on the badger example (already presented as the primary example) and explain how different parameters and environmental layers could change the movement outcome in this species. The other two examples could be moved to the suppl. material to streamline the narrative. Ideally, a small set of badger movement simulations with substantially different environmental scenarios (e.g., 3 scenarios) and/or different behaviors could be added to create a comparative framework helpful to show 1) how sensitive the model is to different transition probabilities and 2) how strongly/easily the parameters and input data (raster) can affect the results. Perhaps the authors already attempted to show different outcomes across parameters and taxa, but I find it confusing because I don’t think that these results are comparable. Alternatively, if the authors decide to maintain the existing framework based on these three species, several clarifications (see my comments/questions above) and thorough justifications of the analytical rationale are needed.

Finally, I encourage the authors to simplify the R code presented in the “grey boxes” embedded in the main text. The R code is certainly helpful and necessary but there are too may annotations and it is hard to read. One way to address this problem is to reduce the length of the # annotated comments to just a few key words and move them along the same code line whenever possible.

For example:

# vulture has zero avoidance of the place holder point

VULTURE_avoidTransformation <- 0

Could be presented in a single line as:

VULTURE_avoidTransformation <- 0 # zero avoidance of the place holder point

Other comments

“In the past decade, the volume of animal data has exploded…” I would not use the term “exploded”.

This work should be cited in the introduction: Gochanour et al. 2023 ¹.

“(e.g., Ref. 12)” I would simply include the reference after “technology” and delete “e.g., Ref.”

In the third paragraph of the Methods, what is the difference between exploring and foraging?

In the Methods, the authors introduce the transition matrix but it is hard to determine how these probabilities are calculated: “We achieved this by creating a transition matrix that describes the probability at each time step of the animal changing to another behaviour [Figure 1], where each value describes the probability of the animal transitioning from the current behaviour (row: b0, b1, b2), to the behaviour for the next time step (columns: b0, b1, b2)”. Yet, it is not clear how the behavior is being translated into a matrix of values.

In the next paragraph, the authors describe cycles (or waves) “that can be applied to the core transition matrix impacting the probability of entering resting behaviour”. This is fine but it does not clearly address the issue that I mentioned above (i.e., how to calculate the transition probabilities). Moreover, there are several cases in which animal movements are not described by daily cycles, for example migration and dispersal. Is abmAnimalMovement suitable to study long-distance movements related to seasonal cycles? This aspect should be further clarified in the Discussion.

In Figure 3, what are the units on the axes? There are two “S” in the first panel but no mention of what they represent. Importantly, these landscape layers need “to be fed into the simulation”, but I wonder if the sequence matters. Is there a difference in the output if “foraging resources” is being added before “shelter quality”? It would be helpful to clarify this point.

Are the conclusions about the tool and its performance adequately supported by the findings presented in the article?

Partly

Is the rationale for developing the new software tool clearly explained?

Yes

Is the description of the software tool technically sound?

Yes

Are sufficient details of the code, methods and analysis (if applicable) provided to allow replication of the software development and its use by others?

Partly

Is sufficient information provided to allow interpretation of the expected output datasets and any results generated using the tool?

Reviewer Expertise:

Movement Ecology.

I confirm that I have read this submission and believe that I have an appropriate level of expertise to confirm that it is of an acceptable scientific standard, however I have significant reservations, as outlined above.

References 1

: abmR : An R package for agent‐based model analysis of large‐scale movements across taxa. Methods in Ecology and Evolution .2023;14(1) : 10.1111/2041-210X.14014 218-230

10.1111/2041-210X.14014

Marshall

Benjamin

University of Stirling, UK

Competing interests: No competing interests were disclosed.

23 10 2025

Response: Thank you for the detailed review and comments. Determining whether the simulations are meaningful is admittedly difficult. The purpose in making this simulation package was to create something with a known underlying mechanism that we could reliability compare to the outputs of the usual movement ecology analyses (specifically habitat selection). Therefore, ensuring the simulated outputs produced idealised habitat selection, while also remaining capable of producing something that a reasonable approximation of real movement, was the priority. The same rationale was behind the use of generated landscape, as well as to enable uncomplicated data sharing. That being said, we fully agree with the reviewer that a better more standardised system to parameterise the simulation would be beneficial. We are currently working on developing something that will allow that, potentially building on a systematic review of specific metrics that can be translated into settings. This system is requiring a lot of work to make diverse data sources compatible and will require a wrapper or secondary package we are pursuing funding to enable us to undertake this extension.

Response: This is exactly what we were aiming for: a simulation that can fully be trusted to be following a known habitat preference and would operate as an idealised test case in future work (see previous comment response and added references). This exploration is too extensive to include in this manuscript, and we have cited the thesis and preprint that use these simulations for their intended purpose. We hope that inclusion shows the utility adequately. We have added text in the introduction and discussion highlighting this use case; these example show how the simulation approach can help explore movement ecology methods.

Line 114 (line numbers follow RMD line numbers): “The simulation is primarily set-up to create a foundation for exploring whether different habitat selection analyses result in the same/similar conclusions [more thoroughly explored, using the example simulated species here, in @marshall_habitat_2024; @marshall_multiverse_2024].”

Response: They are re-scaled to use a grid of the same resolution (see line 561). This is completed using the rescale argument in the simulation code. Therefore, the vulture movements are more extensive. The example species, King Cobra, are likely the most far ranging snake species and they do move more extensively than one might expect. We have emphasised this in the figure caption, highlighting the rescale argument.

Line 1479, Figure Caption: “Note that the size represented by each unit on the x and y axis differs depending on the species as governed by the rescale arguement.”

Response: The examples are present to show a variety of scenarios and flexibility of the R package. Given the large number of parameters required to be set for the simulation, we opted for these example species rather than demonstrating more control one-by-one explorations of varying parameter input focused on a single species. We feel both approaches have different compromises. Initially there was discussion on varying each aspect of the simulation as suggested, but as downstream analysis (see https://doi.org/10.1101/2024.06.19.599733) consisted of many branching analyses paths, this became infeasible. We use the diversity of the chosen example species to broaden the generalisability of those findings. We can now directly reference these uses, and have added them into the manuscript. We hope the context of the multiverse explorations we used the simulation in provides rationale for why certain simulation decisions were made and why more parameterisation were not explored.

Line 114: “For example, we have used this simulation to explore the impacts of analysis choice on researcher’s ability to extract habitat selection estimates from movement data [@marshall_habitat_2024; @marshall_multiverse_2024]. By knowing the underlying mechanism of habitat selection we are able to state whether analysis methods returned corrected or expected results, while quantifying how different analytical choices led to uncertainty. … Line 1989: Primarily, we created these further examples for use in @marshall_habitat_2024 and @marshall_multiverse_2024, to broaden the generalisablity of the findings explored in those papers.”

We have simplified the presentation of the figures that has hopefully brought tighter focus on the input vs outputs for the examples. We hope the reduction in the number of repeated figures reduces the multiple examples competing for attention.

The concern of parameterisation is important. As it stands, the parameterisation is vague and there is no clear system for translating. We are working towards a new system to solve this issue, but in the meantime wanted to address the other comments on this manuscript to post a new version. The exact parameterisation was of secondary importance to the intend use case (now cited); the core requirement was for the simulation to implement a known habitat selection mechanism.

For example: # vulture has zero avoidance of the place holder point VULTURE_avoidTransformation <- 0

Could be presented in a single line as: VULTURE_avoidTransformation <- 0 # zero avoidance of the place holder point

Response: Yes, we have shifted the explanations to a table, and moved some shorter comments to the end of line, provided they do not overflow.

Other comments:

• “In the past decade, the volume of animal data has exploded…” I would not use the term “exploded”.

Response: We have changed the wording to “increased”.

• This work should be cited in the introduction: Gochanour et al. 20231.

Response: Thank you, we were not aware of this work. We have added the reference to the introduction.

• “(e.g., Ref. 12)” I would simply include the reference after “technology” and delete “e.g., Ref.”

Response: We have removed the e.g.,

• In the third paragraph of the Methods, what is the difference between exploring and foraging?

Response: We have added an expanded explanation of the three states in this paragraph.

Line 129: “In the sheltering state, the animal chooses a known shelter location to head towards; in the exploration state, the animal randomly moves within the landscape guided only by the movement resistance of the landscape; in the foraging state, the animal chooses a foraging location and moves towards it.”

• In the Methods, the authors introduce the transition matrix but it is hard to determine how these probabilities are calculated: “We achieved this by creating a transition matrix that describes the probability at each time step of the animal changing to another behaviour [Figure 1], where each value describes the probability of the animal transitioning from the current behaviour (row: b0, b1, b2), to the behaviour for the next time step (columns: b0, b1, b2)”. Yet, it is not clear how the behavior is being translated into a matrix of values.

Response: These probabilities are not calculated as such, they are predefined and are the % chance of the animal moving into another behavioural state. With empirical movement data these could be estimated via a Hidden Markov Model, but in the case of these simulations they are set to values that lead to reasonable looking state switching in the simulation outputs. We have expanded the text to clarify this.

Line 139: “For the included example, we select probabilities that allow the animal to express all behavioural state reasonably evenly and allow behavioural cycles to be easily visible in the resulting simulated movement data.”

• In the next paragraph, the authors describe cycles (or waves) “that can be applied to the core transition matrix impacting the probability of entering resting behaviour”. This is fine but it does not clearly address the issue that I mentioned above (i.e., how to calculate the transition probabilities). Moreover, there are several cases in which animal movements are not described by daily cycles, for example migration and dispersal. Is abmAnimalMovement suitable to study long-distance movements related to seasonal cycles? This aspect should be further clarified in the Discussion.

Response: No, currently abmAnimalMovement is not capable to dealing with migration or dispersal. This is a process we are investigating whether we can expand the package to cover. We have added clearer reference to this in the discussion.

Line 1950: “For animals demonstrating more behavioural states, the abmAnimalMovement package would need considerable extension to be useful; the same for migratory species, especially those travelling long distances into mutually exclusive areas.

• In Figure 3, what are the units on the axes? There are two “S” in the first panel but no mention of what they represent. Importantly, these landscape layers need “to be fed into the simulation”, but I wonder if the sequence matters. Is there a difference in the output if “foraging resources” is being added before “shelter quality”? It would be helpful to clarify this point.

Response: We have added an explanation concerning the “S” shelter points. The units are cell counts, for the badger these cells are equal to 5 m (as we later define via BADGER_rescale).

Line 525: “The three resulting landscape layers to be input into the simulation for the badger example: shelter quality, foraging resources, movement ease. The points marked with”S” indicate the generated shelter sites randomly sampled from the underlying shelter quality matrix. X and Y axes cell numbers; in the case of the badger example cell is 5 m by 5 m.”

The order in which these layers are input into the simulation function would not matter as there are separate arguments for each. We have translated the large code chunk into a table to help make this clearer (see final three rows).

10.5256/f1000research.137044.r164972

Reviewer response for version 1

Joo

Rocío

1 Referee https://orcid.org/0000-0003-0319-4210 1Global Fishing Watch, Washington, District of Columbia, USA

Competing interests: No competing interests were disclosed.

24 4 2023

2023

recommendation

approve-with-reservations

The authors developed an R package to simulate movement using an agent-based approach. It allows accounting for three predefined behavioral states and motion characteristics in each state, activity cycles at different scales and external influences. The purpose is to offer opportunities to test whether movement analyses can accurately recover hidden mechanisms, states, and drivers.

The package certainly presents opportunities to simulate movement, but I do not know how useful it is for ecologists. The authors present three case studies of simulated tracks of badger, vulture and king cobra. They explain their rationality for the parameterization. However, it is not easy to see if these would be realistic movements. They come from the parameters defined by the authors and based on the literature, but it is not so clear still. This could be better done by consulting experts (e.g. movement ecologists with fieldwork and tracking data expertise for each of those species) and showing their expert validation, and editing figures of observed tracks vs. simulated tracks side by side for easy comparison. I also think that there is a lack of insight into how those simulated movements could contribute to the movement ecology of the animals. The manuscript shows that the package can be used to simulate movement with certain parameterization, but it would be better to also show and discuss the usefulness of those simulations for the case studies (specifically for badger ecologists, vulture ecologists and king cobra ecologists, respectively). What questions could those simulations allow answering? I would not expect the authors to answer those questions, but at least discuss them when presenting the case studies.

The presentation of the code could improve as well. First, I would encourage the authors to show examples in the manuscript that can be run on their own, which is not the case in the current version of the manuscript. The abm_simulate examples are extremely long because of all the comments describing the arguments of the function. I would suggest creating tables in the manuscript listing the main functions of the package and describing the arguments of those functions (and default values) so that the example would take less space and can be read easily. Also, some arguments were named in the examples and some others were not. There should be more consistency.

Other comments:

The abstract refers to navigation capacity as " the range the animal can dynamically choose a foraging location", but navigation is not only for foraging.

The agent acts at regular time steps, but do they actually choose from among a range of movement options at regular time steps (e.g. every minute as it seems to be in the case studies)? Does it make sense? And how sensitive is the simulation to the choice of time step? I would like the authors to discuss this.

The simulation requires animals to have three internal states. Is there a workaround for cases with fewer or more states? This seems to be related to point one in future directions but could be more explicit.

NLMR is one of the packages used for the examples and it has been removed from CRAN. I would suggest adding a line to say how to install it (if necessary).

The definitions of destination range and destination direction should be clearly stated.

The x-axes in Fig. 5 should be the same for the three plots.

Since movement is being simulated, I would suggest showing plots of individual trajectories (with the three states) and not just plots of points of several overlapping tracks.

Fig. 8: I might have missed it (and I apologize if that's the case), but I did not understand where the observed data comes from, and what " rest prob. modifier" is.

" The abmAnimalMovement package provides an independent route to test new methods (...)" Which methods? Could the authors provide some examples?

Instead of presenting the Use cases at the end, I would suggest presenting them at the same time as the badger case, perhaps in a shorter version and presenting more details in a supplementary form. A table comparing and summarizing the parameters in the three case studies would be helpful too.

Overall, I think the idea behind the manuscript and the package is good, and I commend the authors for their work. I would suggest making clearer the usefulness of the package for research questions and its usability by using tables to present the details of the functions and examples of code that can be run directly.

Are the conclusions about the tool and its performance adequately supported by the findings presented in the article?

Partly

Is the rationale for developing the new software tool clearly explained?

Yes

Is the description of the software tool technically sound?

Yes

Are sufficient details of the code, methods and analysis (if applicable) provided to allow replication of the software development and its use by others?

Is sufficient information provided to allow interpretation of the expected output datasets and any results generated using the tool?

Partly

Reviewer Expertise:

Statistical ecology; movement ecology

Marshall

Benjamin

University of Stirling, UK

Competing interests: No competing interests were disclosed.

23 10 2025

Response: Thank you for the thorough review and comments. We have taken steps to improve the clarity of the paper specifically regarding the parameterisation in comparison to the outputs. We have added a minimally dependent example coding of the simulation to the data and code archive; this example is a simplifying combination of code shown throughout the manuscript. We have also expanded on the purpose of the simulation package. The preprint and thesis that relied on this simulation are now available, and they do a fuller job of justifying the existence and purpose of the package. We feel that the reference to that more extensive work should demonstrate the questions that can be asked with this package. We agree, a clearer and more empirical process of translating known data into values suitable to parameterise the simulation would be massively beneficial. We in the process of applying for funding to attempt to build such a process. The current state of the simulation package has served its purpose (see referenced thesis and preprint); hence, the revisions detailed here.

Other comments:

• The abstract refers to navigation capacity as “the range the animal can dynamically choose a foraging location”, but navigation is not only for foraging.

Response: Equating navigation to foraging priorities was a necessary simplification for this purpose. The “foraging” layer and behaviour can be treated as any combination of desirable environmental conditions (e.g., improve food resources and thermal conditions). For the follow on work, the primary goal was a behaviour and navigation that reasonably reflected a predefined habitat selection.

• The agent acts at regular time steps, but do they actually choose from among a range of movement options at regular time steps (e.g. every minute as it seems to be in the case studies)? Does it make sense? And how sensitive is the simulation to the choice of time step? I would like the authors to discuss this.

Response: We used minute for the example as it provides a scale to determine reasonable step lengths and turn angles. The underlying simulation operates on a step-by-step basis, so the choice of timeframe is mainly relevant for matching those steps (however they are defined in terms of time) to the inputs of the simulation.

Line 133 (line numbers follow RMD line numbers): “Here, we define these based on the movement capacity of the animal over a minute; however, there is no fixed underlying time frame for the simulation itself.”

• The simulation requires animals to have three internal states. Is there a workaround for cases with fewer or more states? This seems to be related to point one in future directions but could be more explicit.

Response: For fewer yes, as the transition probability can be set extremely low thereby preventing the appearance of that behavioural state. More states would require modification of the underlying C++ code, and something we are working on expanding on in the future to allow for more flexibility. We have expanded on this point in the discussion:

Line 1945: “Reduction to a two or one state scenario could be achieved via manipulation of the transition probabilities. For animals demonstrating more behavioural states, the abmAnimalMovement package would need considerable extension to be useful; the same for migratory species, especially those travelling long distances into mutually exclusive areas.”

• NLMR is one of the packages used for the examples and it has been removed from CRAN. I would suggest adding a line to say how to install it (if necessary).

Response: Yes, we have added lines to suggest how to acquire NMLR without CRAN. Also we have exported the rasters generated so the simulations can be recreated without the NMLR package.

Line 292: “ NLMR is no long available on CRAN but still accessible here https://github.com/ropensci/NLMR, and installed using remotes::install_github("ropensci/NLMR").”

• The definitions of destination range and destination direction should be clearly stated.

Response: We have reworded the destination range sentence and added a note about the turn angle meaning for destination direction.

Line 549: “The perceptual range (implemented here as destination range) is how far the the badger can”see” when deciding where to forage and is set in a similar fashion. Where destinationRange provides the shape (k) and scale ( θ) for the Gamma distribution describing distance of possible foraging locations, and destinationDirection provides the mean ( μ) and concentration ( κ), the Von Mises distribution describes the angle at which those locations can fall in relation to the previous direction of movement.”

• The x-axes in Fig. 5 should be the same for the three plots.

Response: Ideally, we agree. However, the scale differences between the three species would render the smaller details of the badger example illegible.

• Since movement is being simulated, I would suggest showing plots of individual trajectories (with the three states) and not just plots of points of several overlapping tracks.

Response: Figure 6 shows movement trajectories, with only the points falling within each state highlighted. The vulture example in particular allows the reader to see out-bound foraging state movements (i.e., away from shelter sites), and return journeys in the resting state. We could subset the data further to a sub-month patterns, but felt a month’s worth of simulated data presented a good trade-off helping to make both local trajectories and overall patterns visible.

• Fig. 8: I might have missed it (and I apologize if that’s the case), but I did not understand where the observed data comes from, and what “rest prob. modifier” is.

Response: Yes, we have changed the wording as it was confusing. We no longer use “observed” to refer to the simulated data anywhere in the manuscript.

We have also changed our explanation of the rest probability modifier. The new figures we have added should also make the manuscript more consistent with clear comparisons between the input parameterisations and the realised simulated outputs.

Line 1736, Figure Caption: “That the input rest probability waves are additively combined with the underlying behavioural transition matrix of each species.”

• “The abmAnimalMovement package provides an independent route to test new methods (…)” Which methods? Could the authors provide some examples?

Response: Yes, we have cited an example of the multiverse paper that uses this simulation and directly referenced habitat selection in the introduction and discussion.

• Instead of presenting the Use cases at the end, I would suggest presenting them at the same time as the badger case, perhaps in a shorter version and presenting more details in a supplementary form. A table comparing and summarizing the parameters in the three case studies would be helpful too.

Response: An earlier draft had the three examples arranged as suggested. But after feedback we rearranged the manuscript to the current set-up as to get to the core functionality of the simulation faster. As the comparison between the species is of secondary importance, we feel the emphasis on the simulation description is worth prioritising.

• Overall, I think the idea behind the manuscript and the package is good, and I commend the authors for their work. I would suggest making clearer the usefulness of the package for research questions and its usability by using tables to present the details of the functions and examples of code that can be run directly.

Response: Thank you for the review and suggested improvements. We feel that the suggested changes have made many aspects of the description of the package clearer. We also strongly agree with the suggested improvements, and will keep them to hand as future work is conducted to expand the simulation’s capabilities.