SpaDES.core (version 1.0.9)

Plots: Plot wrapper intended for use in a SpaDES module

Description

This is a single function call that allows a user to change which format in which the plots will occur. Specifically, the two common formats would be to "screen" or to disk as an image file, such as "png". THIS CURRENTLY HAS BEEN TESTED WITH ggplot2, RasterLayer, and tmap objects. It uses Plot internally, so individual plots may be rearranged. When saved to disk (e.g., via type = 'png'), then Plot will not be used and the single object that is the result of this Plots call will be saved to disk. This function requires at least 2 things: a plotting function and arguments passed to that function (which could include data, but commonly would simply be named arguments required by fn). See below and examples.

Usage

Plots(
  data,
  fn,
  filename,
  types = quote(params(sim)[[currentModule(sim)]]$.plots),
  path = quote(file.path(outputPath(sim), "figures")),
  .plotInitialTime = quote(params(sim)[[currentModule(sim)]]$.plotInitialTime),
  ggsaveArgs = list(),
  usePlot = TRUE,
  deviceArgs = list(),
  ...
)

Arguments

data

An (optional) arbitrary data object. If supplied, it will be passed as the first argument to Plot function, and should contain all the data required for the inner plotting. If passing a RasterLayer, it may be a good idea to set names(RasterLayer) so that multiple layers can be plotted without overlapping eachother. When a custom fn is used and all arguments for fn are supplied and named, then this can be omitted. See examples.

fn

An arbitrary plotting function. If not provided, defaults to using quickPlot::Plot

filename

A name that will be the base for the files that will be saved, i.e, do not supply the file extension, as this will be determined based on types. If a user provides this as an absolute path, it will override the path argument.

types

Character vector, zero or more of types. If used within a module, this will be deduced from the P(sim)$type and can be omitted. See below.

path

Currently a single path for the saved objects on disk. If filename is supplied as an absolute path, path will be set to dirname(filename), overriding this argument value.

.plotInitialTime

A numeric. If NA then no visual on screen. Anything else will have visuals plotted to screen device. This is here for backwards compatibility. A developer should set in the module to the intended initial plot time and leave it, i.e., not NA.

ggsaveArgs

An optional list of arguments passed to ggplot2::ggsave

usePlot

Logical. If TRUE, the default, then the plot will occur with quickPlot::Plot, so it will be arranged with previously existing plots.

deviceArgs

An optional list of arguments passed to one of png, pdf, tiff, bmp, or jgeg. This is useful when the plotting function is not creating a ggplot object, e.g., plotting a RasterLayer.

...

Anything needed by fn, all named.

Details

• type

  • "screen" -- Will plot to the current device, normally a plot window

  • "object" -- Will save the plot object, e.g., ggplot object

  • "raw" -- Will save the raw data prior to plotting, e.g., the data argument

  • "png" -- or any other type save-able with ggsave

Examples

# NOT RUN {
# }
# NOT RUN {
# Note: if this is used inside a SpaDES module, do not define this
#  function inside another function. Put it outside in a normal
#  module script. It will cause a memory leak, otherwise.
if (!require("ggplot2")) stop("please install ggplot2")
fn <- function(d)
  ggplot(d, aes(a)) +
  geom_histogram()
sim <- simInit()
sim$something <- data.frame(a = sample(1:10, replace = TRUE))

Plots(data = sim$something, fn = fn,
      types = c("png"),
      path = file.path("figures"),
      filename = tempfile(),
      .plotInitialTime = 1
      )

# plot to active device and to png
Plots(data = sim$something, fn = fn,
      types = c("png", "screen"),
      path = file.path("figures"),
      filename = tempfile(),
      .plotInitialTime = 1
      )

# Can also be used like quickPlot::Plot, but with control over output type
r <- raster::raster(extent(0,10,0,10), vals = sample(1:3, size = 100, replace = TRUE))
Plots(r, types = c("screen", "png"), deviceArgs = list(width = 700, height = 500))

# }
# NOT RUN {
 # end of dontrun
# }