-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathsim_detections.Rd
166 lines (150 loc) · 9.05 KB
/
sim_detections.Rd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/sims.R
\name{sim_detections}
\alias{sim_detections}
\title{Simulate detections}
\usage{
sim_detections(
path,
xy,
crs = NA,
calc_detection_pr,
by_timestep = FALSE,
delta_t = NULL,
seed = NULL,
plot = TRUE,
jitter = function(n) stats::rnorm(n, 0, 0.05),
add_prob = list(col = "royalblue", pch = 3, cex = 0.5),
xlim = c(0, 1000),
verbose = TRUE,
...
)
}
\arguments{
\item{path}{A two-column matrix of the coordinates of the movement path (x, y).}
\item{xy}{A two-column matrix of the coordinates of receivers (x, y).}
\item{crs}{A \code{\link[sp]{CRS}} object that defines the coordinate reference system (CRS) for \code{path} and \code{xy} (if applicable).}
\item{calc_detection_pr}{A function that takes in a vector of distances and returns a vector of detection probabilities.}
\item{by_timestep}{A logical variable that defines whether or not \code{calc_detection_pr} needs to be applied to each time step separately. This may be necessary if some of the parameters of the detection model are vectors (see Examples).}
\item{delta_t}{(optional) An integer that defines the number of time steps over which to aggregate detections. If provided, detections are summed over each \code{delta_t} interval and returned along with averaged distances and probabilities (see Value).}
\item{seed}{An integer that is used to set the seed to enable reproducible simulations (see \code{\link[base]{set.seed}}).}
\item{plot}{A logical variable that defines whether or not to plot detections (and probabilities) against distances.}
\item{jitter, add_prob, xlim, ...}{Plot customisation options. \code{jitter} is a function that jitters \code{n} simulated outcomes (0, 1) in the vertical direction. \code{add_prob} is a named list of arguments, passed to \code{\link[graphics]{points}}, used to customise the addition of calculated probabilities to the plot. (\code{add_prob = NULL} suppresses the addition of probabilities to the plot.) \code{xlim} is a vector of x axis limits. By default, \code{xlim = c(0, 1000)} to improve resolution in the area of the plot that is of interest (under a Universal Transverse Mercator CRS, for most realistic detection probability functions, detection probability beyond 1000 will be negligible) and plotting speed. Additional arguments can be passed to \code{\link[prettyGraphics]{pretty_plot}} to customise the plot via \code{...}.}
\item{verbose}{A logical variable that defines whether or not to print messages to the console to relay function progress.}
}
\value{
If \code{delta_t = NULL}, then function returns a named list with three matrices that define, for each path position (rows) and each receiver (columns), (a) the distance of that position from each receiver (`dist_mat'), (b) the probability of detection at that receiver (`prob_mat') and (c) the simulated outcome (0, no detection; 1, detection) (`det_mat'). If \code{delta_t} is specified, then the function returns a list with a `raw' and an `agg' element. The raw elements contains the matrices described above; the `agg' element contains the aggregated versions of these matrices, with detections summed over each \code{delta_t} interval and distances and probabilities averaged (using the arithmetic mean) over each interval. If \code{plot = TRUE}, the function also returns a plot of the (raw) detections (0, 1) and, if specified, the corresponding probabilities.
}
\description{
This function simulates detections at passive acoustic telemetry receivers under a detection model that depends on distance. To implement the function, the underlying movement path that gives rise to detections (or not) must be supplied (via \code{path}) along with the locations of receivers (\code{xy}) at which detections can be made. At each point along the movement path (i.e., time step), the function calculates the distances from that point to all of the receivers and evaluates a user-supplied detection probability function, based on distance, to determine detection probability at each receiver. The function then simulates binary detection outcomes from a binomial distribution conditional on this probability, and returns these in a matrix with one simulated outcome for each time step and receiver.
}
\details{
The function assumes that the individual transmits an acoustic signal which has the capacity to be detected at each time step. In reality, acoustic transmitters are often programmed with a randomly varying delay, but this is not currently implemented. The function also assumes that all receivers that are supplied are able to make detections. If the receivers at which an individual could be detected change over time, it may be necessary to apply the function iteratively or post-process the outcomes to ensure that individuals are not detected at inactive receivers.
For coupled simulation--analysis workflows (such as \code{\link[flapper]{sim_array}}, \code{\link[flapper]{sim_path_sa}} and \code{\link[flapper]{sim_detections}} plus \code{\link[flapper]{ac}}, \code{\link[flapper]{dc}}, \code{\link[flapper]{acdc}} and \code{\link[flapper]{pf}}), it is important that receiver locations (from \code{\link[flapper]{sim_array}}) and individual locations (from \code{\link[flapper]{sim_path_sa}}) are represented on the \code{\link[raster]{raster}} grid used to reconstruct simulated movements before simulating detections. Receiver locations and movement distances must remain admissible according to the movement model when translated on the grid. Grid resolution should be sufficiently high to represent effectively simulated movement probabilities and detection probabilities.
}
\examples{
#### Step (1) Simulate an array in an area
array_ls <- sim_array(
boundaries = raster::extent(dat_coast),
coastline = dat_coast,
n_receivers = 100,
arrangement = "regular",
seed = 1
)
raster::lines(dat_coast)
#### Step (2) Simulate a movement path in this area
n <- 500
path_ls <- sim_path_sa(
n = n,
sim_step = function(...) stats::rgamma(1, shape = 25, scale = 25),
area = array_ls$array$sea,
seed = 1,
plot = FALSE
)
prettyGraphics::add_sp_path(path_ls$xy_mat, col = viridis::viridis(n), length = 0.02)
#### Step (3) Simulate detections
## (A) Extract path and receiver coordinates from simulated outcomes above
path <- path_ls$xy_mat
xy <- array_ls$array$xy
xy <- sp::coordinates(xy)
## (B) Simulate detections under different probability functions (see below).
#### Example (1) Threshold probability function
# Define detection pr function
calc_detection_pr <- function(dist) ifelse(dist < 425, 1, 0)
# Simulate detections
dets_sim <- sim_detections(
path = path,
xy = xy,
calc_detection_pr = calc_detection_pr
)
# The function returns a list of matrices that define the distances,
# ... probabilities and detections for each time stamp (row) and each receiver
# ... (column)
utils::str(dets_sim)
# Examine probabilities
table(dets_sim$prob_mat)
# We can also aggregate detections via delta_t
dets_sim <- sim_detections(
path = path,
xy = xy,
calc_detection_pr = calc_detection_pr,
delta_t = 10
)
# In this case, the function returns a list with 'agg' and 'raw' elements
# ... The 'agg' elements contain aggregated matrices and the 'raw' elements
# ... contain the matrices described above.
utils::str(dets_sim)
table(dets_sim$raw$det_mat)
table(dets_sim$agg$det_mat)
#### Example (2) Logistic probability function
calc_detection_pr <- function(dist) stats::plogis(2.5 + -0.01 * dist)
dets_sim <- sim_detections(
path = path,
xy = xy,
calc_detection_pr = calc_detection_pr
)
#### Example (3) Spatially varying probability function
# Define spatially varying beta parameter (e.g., reflecting 2 habitat types)
area <- array_ls$array$area
area_r <- raster::raster(
x = raster::extent(area),
crs = raster::crs(area)
)
area_r[] <- 0L
beta_surface <- sim_surface(
blank = area_r,
n = 2L,
sim_values = list(
function(n) -0.05,
function(n) -0.01
),
mask = array_ls$array$sea
)
# Extract receiver specific beta values
xy_sp <- sp::SpatialPoints(xy, proj4string = raster::crs(area_r))
beta <- raster::extract(beta_surface, xy_sp)
# Visualise simulated detection probability surface at some suitable distances
pp <- graphics::par(mfrow = c(2, 2))
lapply(c(0, 50, 100, 500), function(dist) {
r <- raster::calc(beta_surface, function(beta) stats::plogis(2.5 + beta * dist))
raster::plot(r)
})
graphics::par(pp)
# Define detection probability function
calc_detection_pr <- function(dist) stats::plogis(2.5 + beta * dist)
# Simulate detections
# ... Define by_timestep = TRUE so that that distances from each receiver
# ... are combined appropriately with beta values for each receiver
dets_sim <- sim_detections(
path = path,
xy = xy,
calc_detection_pr = calc_detection_pr,
by_timestep = TRUE
)
}
\seealso{
\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. To convert the detection matrix to dataframe, see \code{\link[flapper]{make_df_detections}}.
}
\author{
Edward Lavender
}