-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathsim_array.Rd
135 lines (120 loc) · 9.03 KB
/
sim_array.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
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/sims.R
\name{sim_array}
\alias{sim_array}
\title{Simulate (marine) monitoring arrays}
\usage{
sim_array(
boundaries = raster::extent(-10, 10, -10, 10),
coastline = NULL,
land_inside_coastline = TRUE,
n_receivers = 10L,
arrangement = "random",
seed = NULL,
plot = TRUE,
xlim = NULL,
ylim = NULL,
add_sea = NULL,
add_land = NULL,
add_receivers = list(),
verbose = TRUE,
...
)
}
\arguments{
\item{boundaries}{An \code{\link[raster]{extent}} object that defines the boundaries of the (simulated) study area.}
\item{coastline}{(optional) This argument is used to incorporate the presence of barriers, such as coastline, in the area. There are three options. If \code{coastline = NULL}, no barriers are incorporated. If \code{coastline = "simple_random"}, then a triangular island is simulated in the study area. Alternatively, a spatial object (such as a SpatialPolygonsDataFrame) or a \code{\link[raster]{raster}} that defines the coastline in an area can be incorporated into the array design by passing this \code{coastline}. If a \code{\link[raster]{raster}} is used, cells with NA are excluded from sampling.}
\item{land_inside_coastline}{If \code{coastline} is a Spatial okject, \code{land_inside_coastline} is a logical variable that defines whether or not the land is `inside' the polygon(s) defined by \code{coastline} (\code{land_inside_coastline = TRUE}) or the sea is `inside' the polygon(s) (\code{land_inside_coastline = FALSE}).}
\item{n_receivers}{An integer that defines the number of receivers in the array. This is ignored if receiver locations are specified via \code{arrangement}.}
\item{arrangement, ...}{A character string or a SpatialPoints object that defines the arrangement of receivers. If a character is supplied, sampling is implemented via \code{\link[sp]{spsample}} unless \code{coastline} is a \code{\link[raster]{raster}} in which case sampling is implemented via \code{\link[raster]{sampleRegular}}, \code{\link[raster]{sampleRandom}} or \code{\link[raster]{sampleStratified}}, depending on \code{arrangement}. Supported character string options for simulated arrays are \code{"regular"}, \code{"random"}, \code{"stratified"} (for all supported function inputs) and \code{"nonaligned"}, \code{"hexagonal"} and \code{"clustered"} (only for \code{\link[sp]{spsample}} implementations). Additional arguments can be passed to this function via \code{...} for further control. Otherwise, a SpatialPoints object that defines the coordinates of receivers (in the same coordinate reference system as \code{boundaries} and, if applicable, \code{coastline}) is assumed to have been provided.}
\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 plot the array (via \code{\link[prettyGraphics]{pretty_map}}).}
\item{xlim, ylim}{(optional) Axis limits for the plot. These can be specified in any way supported by \code{\link[prettyGraphics]{pretty_axis}}.}
\item{add_sea, add_land, add_receivers}{(optional) Named lists of arguments, passed to \code{\link[prettyGraphics]{pretty_map}}, to customise the appearance of the sea, land and/or receivers on the plot. \code{add_* = NULL} suppresses the addition of the layer to the plot. To use the default graphical parameters, simply specify \code{add_* = list()}.}
\item{verbose}{A logical variable that defines whether or not to print messages to the console to relay function progress.}
}
\value{
The function returns a named list of (a) the spatial objects that define the simulated array (`array') and (b) the arguments used to generate this array (`args'). The `array' element is a named list contains the following elements: `boundaries', an \code{\link[raster]{Extent-class}} object that defines the boundaries of the area (as inputted); `area', a \code{\link[sp]{SpatialPolygons-class}} object that defines the boundaries of the area; `land' and `sea', \code{\link[sp]{SpatialPolygons-class}}, \code{\link[sp]{SpatialPolygonsDataFrame-class}} or \code{\link[raster]{raster}} objects that define the land and sea respectively; and `xy', a \code{\link[sp]{SpatialPoints-class}} object that defines receiver locations. If \code{plot = TRUE}, the function also returns a plot of the array.
}
\description{
This function is designed to simulate different kinds of array designs for monitoring stations. The function has been particularly inspired by the need to simulate passive acoustic telemetry array designs, which comprise networks of acoustic hydrophones that listen for acoustic transmissions from tagged marine animals. To implement the function, it is necessary to define the boundaries of the area (\code{boundaries}). Barriers to movement, such as coastline, within this area can be simulated or included from real datasets. The area is populated with a specified number of receivers (\code{n_receivers}) that are simulated under different array designs (namely, regular, random, stratified, non-aligned, hexagonal and clustered arrangements) or incorporated from real data. The function returns a list of spatial objects that define the array and, if requested, a plot of the area.
}
\details{
Note that this function does not currently support temporally varying array designs.
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}}) note that the representation of the \code{coastline} as \code{\link[sp]{SpatialPolygons-class}} or \code{\link[sp]{SpatialPolygonsDataFrame-class}} objects by the \code{sim_*} functions, rather than a \code{\link[raster]{raster}} grid, may be problematic at the land--sea interface if the Spatial* data used for the simulation do not agree precisely with the \code{\link[raster]{raster}} data used to reconstruct movements: locations that are `allowed' from the perspective of the Spatial* data may not be allowed by the \code{\link[raster]{raster}} data (and vice versa). At the time of writing, this can be resolved in two ways. (A) Check simulated array positions in relation to the grid across which movements are reconstructed. Receiver locations should also be translated onto the \code{\link[raster]{raster}} before simulating detections (see \code{\link[flapper]{sim_detections}}). (B) For this function, you can now use a \code{\link[raster]{raster}} to simulate receiver locations (see also \code{\link[flapper]{acs_setup_containers}}).
}
\examples{
#### Example (1): Simulate an array using default parameters
# ... And force reproducible simulations by defining the seed
array <- sim_array(
boundaries = raster::extent(-10, 10, -10, 10),
seed = 1
)
#### Example (2): Simulate coastline and customise plot
# ... via add_land and add_sea
array <- sim_array(
boundaries = raster::extent(-10, 10, -10, 10),
coastline = "simple_random",
add_land = list(col = "darkgreen"),
add_sea = list(col = scales::alpha("skyblue", 0.2)),
seed = 1
)
#### Example (3): Add custom coastline
array <- sim_array(
boundaries = raster::extent(dat_coast),
coastline = dat_coast,
add_land = list(col = "darkgreen"),
add_sea = list(col = scales::alpha("skyblue", 0.2)),
seed = 1
)
#### Example (4): Change the number of receivers
array <- sim_array(n_receivers = 5)
array <- sim_array(n_receivers = 25)
#### Example (5): Change the arrangement of receivers
## Explore different arrangements
array <- sim_array(n_receivers = 25, arrangement = "random")
array <- sim_array(n_receivers = 25, arrangement = "regular")
array <- sim_array(n_receivers = 25, arrangement = "clustered", nclusters = 5)
array <- sim_array(n_receivers = 25, arrangement = "stratified")
array <- sim_array(n_receivers = 25, arrangement = "nonaligned")
array <- sim_array(n_receivers = 25, arrangement = "hexagonal")
## Force arrangements around coastline
# Simulated island
array <- sim_array(
n_receivers = 25,
coastline = "simple_random",
arrangement = "regular",
add_land = list()
)
# Real coastline
array <- sim_array(
boundaries = raster::extent(dat_coast),
n_receivers = 25,
coastline = dat_coast,
arrangement = "regular",
add_land = list()
)
## Incorporate custom arrangements
# Define receiver locations as a SpatialPoints object with a UTM CRS
# ... to match other spatial datasets
proj_wgs84 <- sp::CRS(SRS_string = "EPSG:4326")
proj_utm <- sp::CRS(SRS_string = "EPSG:32629")
xy <- sp::SpatialPoints(
dat_moorings[, c("receiver_long", "receiver_lat")],
proj_wgs84
)
xy <- sp::spTransform(xy, proj_utm)
# Make array
array <- sim_array(
boundaries = raster::extent(dat_coast),
coastline = dat_coast,
arrangement = xy,
add_land = list()
)
}
\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.
}
\author{
Edward Lavender
}