sim_path_ou_1.Rd

% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/sims.R
\name{sim_path_ou_1}
\alias{sim_path_ou_1}
\title{Simulate discrete-time movement paths under a Ornstein-Uhlenbeck process (1)}
\usage{
sim_path_ou_1(
  n = 1000,
  r_1 = NULL,
  r_h = matrix(c(0, 0), ncol = 2),
  k = 1,
  delta_t = 1,
  eps = 1,
  plot = TRUE,
  add_paths = list(length = 0.04, col = viridis::viridis(n)),
  add_points = list(pch = 21, cex = 2, lwd = 2, bg = c("darkgreen", "black")),
  verbose = TRUE,
  ...
)
}
\arguments{
\item{n}{An integer that defines the number of time steps in the simulation.}

\item{r_1}{(optional) A matrix with one row and two columns that defines the starting location (x, y).  If \code{r_1 = NULL}, then a random location is simulated from a uniform distribution with a minimum and maximum value of 0 and 1 respectively.}

\item{r_h}{A matrix with one row and two columns that defines the `home range' centre location (x, y).}

\item{k}{A number that defines the strength of the `central harmonic force' that pulls an individual back towards its home range centre.}

\item{delta_t}{A number that defines the number of time units between each time step.}

\item{eps}{A number that defines the variance.}

\item{plot}{A logical variable that defines whether or not to plot the simulated path.}

\item{add_paths, add_points}{(optional) Named lists of arguments that are used to customise the appearance of points (the home range and starting location, in that order, shown as filled green and black circles by default) and the path on the map.}

\item{verbose}{A logical variable that defines whether or not to print messages to the console that relay function progress.}

\item{...}{Additional arguments, passed to \code{\link[prettyGraphics]{pretty_map}}, to customise the map.}
}
\value{
The function returns an n-row, two-column matrix that defines the simulated location (x, y) at each time step and, if \code{plot = TRUE}, a plot of the path.
}
\description{
This function simulates movement paths under a discrete-time Ornstein-Uhlenbeck process in which the parameters of the movement model are assumed to remain constant through time.
}
\details{
Ornstein-Uhlenbeck processes are convenient models for animal movement around a `home range' centre. In the model, a parameter (\code{k}) `pulls' the location of the individual (\eqn{\vec{r}}) back towards the centre of its home range (\eqn{\vec{r}^H}) as it moves away from this centre. This function implements the discretised form of the Ornstein-Uhlenbeck model in which the parameters of the movement model remain constant through time, and in which movement is not constrained by barriers, described by Alós et al. (2016) (see equations (8) and (9) in particular). Under this model, the position \eqn{\vec{r}} of the animal at time \eqn{n + 1} is given by:

\deqn{\vec{r}_{n + 1} = \vec{r}^H + e^{-k \Delta t} (\vec{r}_n - \vec{r}^H) + \vec{R}_n,}

where \eqn{\vec{r}^H} is the location of the home range centre; \eqn{k} is the strength of the central harmonic force; \eqn{\Delta t} is the duration between time steps; and \eqn{\vec{R}_n} is a bi-dimensional normally distributed random variable with mean zero and standard deviation (\eqn{\sigma}) given by:

\deqn{\sigma = \sqrt{ \frac{\epsilon (1 - e^{-2 k \Delta t})} {2 k}}.}

Note that the default plotting parameters for this function require the \code{\link[viridis]{viridis}} package for pretty visualisation.
}
\examples{
#### Example (1): Implement simulation with default options
path <- sim_path_ou_1()

#### Example (2): Change the number of time steps
path <- sim_path_ou_1(n = 10000)

#### Example (3): Change model parameters
# esp parameter
path <- sim_path_ou_1(n = 10000, eps = 10)
path <- sim_path_ou_1(n = 10000, eps = 500)
# central harmonic parameter
path <- sim_path_ou_1(n = 1000, eps = 1, k = 1)
path <- sim_path_ou_1(n = 1000, eps = 1, k = 3)
path <- sim_path_ou_1(n = 1000, eps = 1, k = 500)

#### Example (4): Customise the plot via add_paths, add_points and ...
n <- 1000
path <- sim_path_ou_1(
  n = n,
  add_points = list(pch = c(1, 4), lwd = 3),
  add_paths = list(col = viridis::magma(n)),
  pretty_axis_args = list(1:4)
)

}
\references{
Alós, J. et al. (2016) Bayesian State-Space Modelling of Conventional Acoustic Tracking Provides Accurate Descriptors of Home Range Behavior in a Small-Bodied Coastal Fish Species. Plos One 11, e0154089.
}
\seealso{
For movement simulations, see \code{\link[flapper]{sim_path_*}} for the full list of functions currently implemented in \code{\link[flapper]{flapper}}. For example, \code{\link[flapper]{sim_path_sa}} simulates a movement path based on step lengths and turning angles. This can support movement within restricted areas. More broadly, \code{\link[flapper]{sim_array}}, \code{\link[flapper]{sim_path_*}} and \code{\link[flapper]{sim_detections}} provide an integrated workflow for simulating acoustic arrays, movement paths in these areas and detections at receivers arising from movement.
}
\author{
Edward Lavender
}