-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathget_detection_containers_envir.Rd
150 lines (138 loc) · 6.92 KB
/
get_detection_containers_envir.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
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/get_detections.R
\name{get_detection_containers_envir}
\alias{get_detection_containers_envir}
\title{Sample environmental conditions around receivers}
\usage{
get_detection_containers_envir(
xy,
detection_range,
coastline,
plot = FALSE,
envir,
sample_size = NULL,
sample_replace = TRUE,
sample_probs = NULL,
cl = NULL,
varlist = NULL,
verbose = TRUE,
...
)
}
\arguments{
\item{xy, detection_range, coastline, plot, ...}{Arguments required to calculate and visualise detection containers via \code{\link[flapper]{get_detection_containers}}; namely, receiver locations (\code{xy}), the detection range (\code{detection_range}), barriers to detection (\code{coastline}) and whether or not to plot the containers (\code{plot}). Additional arguments can be passed via \code{...} but note that \code{byid} is necessarily \code{TRUE} and should not be provided.}
\item{envir}{A \code{\link[raster]{raster}} that defines the values of an environmental variable across the study area. The coordinate reference system should be the Universal Transverse Mercator system.}
\item{sample_size}{(optional) An integer that defines the number of samples of the environmental variable to draw from the area around each receiver (see the `size' argument of \code{\link[base]{sample}}). If this is provided, \code{sample_size} samples are taken from this area; otherwise, all values are extracted.}
\item{sample_replace}{(optional) If \code{sample_size} is specified, \code{sample_replace} is a logical input that defines whether to implement sampling with (\code{sample_replace = TRUE}, the default) or without (\code{sample_replace = FALSE}) replacement (see the `replace' argument of \code{\link[base]{sample}}).}
\item{sample_probs}{(optional) If \code{sample_size} is specified, \code{sample_probs} is a function that calculates the detection probability given the distance (m) between a cell and a receiver.}
\item{cl, varlist}{(optional) Parallelisation options. \code{cl} is (a) a cluster object from \code{\link[parallel]{makeCluster}} or (b) an integer that defines the number of child processes. \code{varlist} is a character vector of variables for export (see \code{\link[flapper]{cl_export}}). Exported variables must be located in the global environment. If a cluster is supplied, the connection to the cluster is closed within the function (see \code{\link[flapper]{cl_stop}}). For further information, see \code{\link[flapper]{cl_lapply}} and \code{\link[flapper]{flapper-tips-parallel}}.}
\item{verbose}{A logical variable that defines whether or not relay messages to the console to monitor function progress.}
}
\value{
The function returns a list of dataframes (one for each element in \code{xy}; i.e., each receiver), each of which includes the cell IDs of \code{envir} from which values were extracted (`cell'), the value of the environmental variable in that cell (`envir') and, if applicable, the distance between that cell and the receiver (`dist', m) and the detection probability in that cell (`prob').
}
\description{
This function is used to sample environmental conditions from within the detection containers of receivers. To implement the function, a SpatialPoints object that defines receiver locations (\code{xy}) must be provided, along with the detection range (\code{detection_range}) of receivers. This information is used to define detection containers, via \code{\link[flapper]{get_detection_containers}}. Within each receiver's container, all values of an environmental variable, or a random sample of values, are extracted from a user-defined \code{\link[raster]{raster}} (\code{envir}). Under random sampling, values can be sampled according to a detection probability function (\code{sample_probs}). The function returns a list of dataframes, one for each receiver, that include the sampled values.
}
\examples{
#### Define receiver locations as a SpatialPoints object with a UTM CRS
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)
xy@data <- as.data.frame(xy)
#### Example (1): Extract all depth values within each receiver's container
depths_by_container <-
get_detection_containers_envir(
xy = xy,
detection_range = 425,
coastline = dat_coast,
envir = dat_gebco
)
# The function returns a list of dataframes, one for each receiver
# ... with the cell IDs and the value of the environmental variable
utils::str(depths_by_container)
# Collapse the list and compare conditions across receivers
depths_by_container <-
lapply(1:length(depths_by_container), function(i) {
d <- depths_by_container[[i]]
d$receiver_id <- dat_moorings$receiver_id[i]
return(d)
})
depths_by_container <- dplyr::bind_rows(depths_by_container)
prettyGraphics::pretty_boxplot(
depths_by_container$receiver_id,
depths_by_container$envir
)
#### Example (2): Extract a random sample of values
# (We'll keep the values small for speed)
depths_by_container <-
get_detection_containers_envir(
xy = xy,
detection_range = 425,
coastline = dat_coast,
envir = dat_gebco,
sample_size = 2
)
utils::str(depths_by_container)
#### Example (3) Extract a random sample of values with weighted probabilities
# Define detection probability function based only on distance
calc_detection_pr <-
function(dist) {
dpr <- get_detection_pr(
distance = dist,
beta_0 = 2.5,
beta_1 = -0.01,
inv_link = stats::plogis,
output = 2L
)
return(dpr)
}
# Implement sampling with replacement according to detection probability
depths_by_container <-
get_detection_containers_envir(
xy = xy,
detection_range = 425,
coastline = dat_coast,
envir = dat_gebco,
sample_size = 2,
sample_probs = calc_detection_pr
)
# Each element of the outputted list includes the 'cell' and 'envir' column
# ... as well as 'dist' and 'prob' that define the distance of that cell
# ... from the location in xy and the corresponding detection probability
# ... at that distance respectively
utils::str(depths_by_container)
#### Example (4) Sampling without replacement via sample_replace = FALSE
depths_by_container <-
get_detection_containers_envir(
xy = xy,
detection_range = 425,
coastline = dat_coast,
envir = dat_gebco,
sample_size = 2,
sample_probs = calc_detection_pr,
sample_replace = FALSE
)
utils::str(depths_by_container)
#### Example (5) Parallelise the algorithm via cl and varlist arguments
depths_by_container <-
get_detection_containers_envir(
xy = xy,
detection_range = 425,
coastline = dat_coast,
envir = dat_gebco,
sample_size = 2,
sample_probs = calc_detection_pr,
sample_replace = FALSE,
cl = parallel::makeCluster(2L),
varlist = c("dat_gebco", "calc_detection_pr")
)
utils::str(depths_by_container)
}
\author{
Edward Lavender
}