-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathacdc_plot_record.Rd
171 lines (147 loc) · 9.76 KB
/
acdc_plot_record.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
167
168
169
170
171
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/acdc_analyse_record.R
\name{acdc_plot_record}
\alias{acdc_plot_record}
\title{Plot time-specific maps from the AC/DC algorithm(s)}
\usage{
acdc_plot_record(
record,
type = c("map_cumulative", "map_timestep"),
plot = 1,
add_coastline = NULL,
add_receivers = NULL,
add_raster = list(col = rev(grDevices::terrain.colors(255))),
add_containers = list(),
add_additional = NULL,
crop_spatial = FALSE,
xlim = NULL,
ylim = NULL,
fix_zlim = FALSE,
pretty_axis_args = list(side = 1:4, axis = list(list(), list(), list(labels = FALSE),
list(labels = FALSE)), control_axis = list(las = TRUE), control_sci_notation =
list(magnitude = 16L, digits = 0)),
par_param = list(),
png_param = list(),
cl = NULL,
varlist = NULL,
verbose = TRUE,
check = TRUE,
...
)
}
\arguments{
\item{record}{An \code{\link[flapper]{acdc_record-class}} object.}
\item{type}{A character that defines the plotted surface(s): \code{"map_cumulative"} plots the cumulative surface and \code{"map_timestep"} plots time step-specific surfaces.}
\item{plot}{An integer vector that defines the time steps for which to make plots. If \code{plot = NULL}, the function will make a plot for all time steps for which the necessary information is available in \code{record}.}
\item{add_coastline}{(optional) A named list of arguments, passed to \code{\link[raster]{plot}}, to add a polygon (i.e., of the coastline), to the plot. If provided, this must contain an `x' element that contains the coastline as a spatial object (e.g., a SpatialPolygonsDataFrame: see \code{\link[flapper]{dat_coast}} for an example).}
\item{add_receivers}{(optional) A named list of arguments, passed to \code{\link[graphics]{points}}, to add points (i.e., receivers) to the plot. If provided, this must contain an `x' element that is a SpatialPoints object that specifies receiver locations (in the same coordinate reference system as other spatial data).}
\item{add_raster}{(optional) A named list of arguments, passed to \code{\link[fields]{image.plot}}, to plot the RasterLayer of possible locations that is extracted from \code{record}.}
\item{add_containers}{(optional) For outputs from the AC* algorithms (\code{\link[flapper]{ac}} or \code{\link[flapper]{acdc}}), \code{containers} is a named list of arguments, passed to \code{\link[raster]{plot}}, to add the acoustic containers to the plot. If specified, the container that defines the boundaries of the individual's possible locations at each time step is drawn (i.e., `container_c` in \code{\link[flapper]{acdc_record-class}} objects).}
\item{add_additional}{(optional) A stand-alone function, to be executed after the background plot has been made and any specified spatial layers have been added to this, to customise the result (see Examples).}
\item{crop_spatial}{A logical variable that defines whether or not to crop spatial data to lie within the axis limits.}
\item{xlim, ylim, fix_zlim, pretty_axis_args}{Axis control arguments. \code{xlim} and \code{ylim} control the axis limits, following the rules of the \code{lim} argument in \code{\link[prettyGraphics]{pretty_axis}}. \code{fix_zlim} is a logical input that defines whether or not to fix z axis limits across all plots (to facilitate comparisons), or a vector of two numbers that define a custom range for the z axis which is fixed across all plots. \code{fix_zlim = FALSE} produces plots in which the z axis is allowed to vary flexibly between time units. Other axis options supported by \code{\link[prettyGraphics]{pretty_axis}} are implemented by passing a named list of arguments to this function via \code{pretty_axis_args}.}
\item{par_param}{(optional) A named list of arguments, passed to \code{\link[graphics]{par}}, to control the plotting window. This is executed before plotting is initiated and therefore affects all plots.}
\item{png_param}{(optional) A named list of arguments, passed to \code{\link[grDevices]{png}}, to save plots to file. If supplied, the plot for each time step is saved separately. The `filename' argument should be the directory in which plots are saved. Plots are then saved as "1.png", "2.png" and so on.}
\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}}. If supplied, the function loops over specified time steps in parallel to make plots. This is only implemented if plots are saved to file (i.e., \code{png_param} is supplied).}
\item{verbose}{A logical variable that defines whether or not relay messages to the console to monitor function progress.}
\item{check}{A logical variable that defines whether or not to check user inputs to the function before its initiation.}
\item{...}{Additional arguments, passed to \code{\link[raster]{plot}}, to customise the blank background plot onto which spatial layers are added, such as \code{xlab}, \code{ylab} and \code{main}.}
}
\value{
The function plots the results of the AC* algorithm(s) at specified time steps, with one plot per time step. Plots are saved to file if \code{png_param} is supplied.
}
\description{
This function is used to plot time-specific maps from the AC/DC algorithm(s). To implement the function, an \code{\link[flapper]{acdc_record-class}} list from \code{\link[flapper]{ac}}, \code{\link[flapper]{dc}} or \code{\link[flapper]{acdc}} plus \code{\link[flapper]{acdc_simplify}} must be supplied, from which the results can be extracted and plotted for specified time steps. For each time step, the function extracts the necessary information; sets up a blank background plot using \code{\link[raster]{plot}} and \code{\link[prettyGraphics]{pretty_axis}} and then adds requested spatial layers to this plot. Depending on user-inputs, this will usually show a cumulative map of expected time spent in different parts of the study area (from the start of the algorithm to each time point). Coastline, receivers and acoustic containers (if applicable) can be added and customised and the finalised plots can be returned or saved to file.
}
\examples{
#### Step (1): Implement AC/DC algorithm(s)
# ... see examples via ac(), dc() and acdc()
#### Step (2): Simplify outputs of the AC/DC algorithm(s)
dat_acdc <- acdc_simplify(dat_acdc)
#### Example (1): The default options simply plot the first surface
acdc_plot_record(record = dat_acdc)
#### Example (2): Define the number of plots to be produced and control the plotting window
acdc_plot_record(
record = dat_acdc,
plot = 1:2,
par_param = list(mfrow = c(1, 2), mar = c(8, 8, 8, 8))
)
#### Example (3): Add and customise spatial information via add_* args
## Define a SpatialPoints object of receiver locations
proj_wgs84 <- sp::CRS(SRS_string = "EPSG:4326")
proj_utm <- sp::CRS(SRS_string = "EPSG:32629")
rsp <- sp::SpatialPoints(dat_moorings[, c("receiver_long", "receiver_lat")], proj_wgs84)
rsp <- sp::spTransform(rsp, proj_utm)
## Plot with receiver locations and coastline, customise the containers and the raster
acdc_plot_record(
record = dat_acdc,
add_coastline = list(x = dat_coast, col = "darkgreen"),
add_receivers = list(x = rsp, pch = 4, col = "royalblue"),
add_containers = list(col = "red"),
add_raster = list(col = rev(topo.colors(100)))
)
#### Example (4): Control axis properties
# ... via smallplot argument for raster, pretty_axis_args, xlim, ylim and fix_zlim
# ... set crop_spatial = TRUE to crop spatial data within adjusted limits
acdc_plot_record(
record = dat_acdc,
add_coastline = list(x = dat_coast, col = "darkgreen"),
add_receivers = list(x = rsp, pch = 4, col = "royalblue"),
add_containers = list(col = "red"),
add_raster = list(smallplot = c(0.85, 0.9, 0.25, 0.75)),
crop_spatial = TRUE,
pretty_axis_args = list(
side = 1:4,
control_sci_notation =
list(magnitude = 16L, digits = 0)
),
xlim = raster::extent(dat_coast)[1:2],
ylim = raster::extent(dat_coast)[3:4],
fix_zlim = c(0, 1)
)
#### Example (5): Modify each plot after it is produced via add_additional
# Specify a function to add titles to a plot
add_titles <- function() {
mtext(side = 1, "x (UTM)", line = 2)
mtext(side = 2, "y (UTM)", line = -8)
}
# Make plots with added titles
acdc_plot_record(
record = dat_acdc,
plot = 1:2,
par_param = list(mfrow = c(1, 2), mar = c(8, 8, 8, 8)),
add_coastline = list(x = dat_coast, col = "darkgreen"),
add_receivers = list(x = rsp, pch = 4, col = "royalblue"),
add_containers = list(col = "red"),
add_raster = list(),
crop_spatial = TRUE,
xlim = raster::extent(dat_coast)[1:2],
ylim = raster::extent(dat_coast)[3:4],
add_additional = add_titles
)
#### Example (6) Save plots via png_param
list.files(tempdir())
acdc_plot_record(
record = dat_acdc,
plot = 1:2,
png_param = list(filename = tempdir())
)
list.files(tempdir())
#### Example (7) To plot the overall map, you can also just use a
# ... a raster plotting function like prettyGraphics::pretty_map()
ext <- update_extent(raster::extent(dat_coast), -1000)
prettyGraphics::pretty_map(
x = ext,
add_rasters = list(x = dat_acdc$map),
add_points = list(x = rsp, pch = "*", col = "red"),
add_polys = list(x = dat_coast, col = "lightgreen"),
crop_spatial = TRUE,
xlab = "Easting", ylab = "Northing"
)
}
\seealso{
This function is typically used following calls to \code{\link[flapper]{ac}}, \code{\link[flapper]{dc}} or \code{\link[flapper]{acdc}} and \code{\link[flapper]{acdc_simplify}}.
}
\author{
Edward Lavender
}