% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/Plots.R
\name{Plots}
\alias{Plots}
\title{\code{Plot} wrapper intended for use in a SpaDES module}
\usage{
Plots(
  data,
  fn,
  filename,
  types = quote(params(sim)[[currentModule(sim)]]$.plots),
  path = quote(figurePath(sim)),
  .plotInitialTime = quote(params(sim)[[currentModule(sim)]]$.plotInitialTime),
  ggsaveArgs = list(),
  usePlot = getOption("spades.PlotsUsePlot", FALSE),
  deviceArgs = list(),
  envir = parent.frame(),
  useCache = FALSE,
  ...
)
}
\arguments{
\item{data}{An (optional) arbitrary data object. If supplied, it will be passed as
the first argument to \code{Plot} function, and should contain all the data
required for the inner plotting. If passing a \code{RasterLayer},
it may be a good idea to set \code{names(RasterLayer)} so that
multiple layers can be plotted without overlapping each other. When a custom \code{fn}
is used and all arguments for \code{fn} are supplied and named, then this can be omitted.
See examples.}

\item{fn}{An arbitrary plotting function. If not provided, defaults to using \code{quickPlot::Plot}}

\item{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 \code{types}.
If a user provides this as an absolute path, it will override the \code{path}
argument.}

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

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

\item{.plotInitialTime}{A numeric. If \code{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., \emph{not} \code{NA}.}

\item{ggsaveArgs}{An optional list of arguments passed to \code{ggplot2::ggsave}}

\item{usePlot}{Logical. If \code{TRUE}, the default, then the plot will occur
with \code{quickPlot::Plot}, so it will be arranged with previously existing plots.}

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

\item{envir}{The environment where the \code{data} argument should be evaluated if it is
a \code{call}. Normally, this should be left at its default, \code{parent.frame()}.}

\item{useCache}{Logical or character vector. If \code{TRUE}, caching is enabled for
all non-screen output types. If a character vector, caching is enabled only
for the matching \code{types}. Default is \code{FALSE}.}

\item{...}{Anything needed by \code{fn}, all named.}
}
\value{
Called for its side effect of plot creation.
}
\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 \code{"screen"} or to disk as an image file,
such as \code{"png"}.
\emph{This has currently been tested with \code{ggplot2}, \code{RasterLayer}, and \code{tmap} objects.}
The default (or change with e.g., \verb{fn = "print", usePlot = FALSE}) uses
\code{Plot} internally, so individual plots may be rearranged. When saved to
disk (e.g., via \code{type = 'png'}), then \code{Plot} will not be used and the single object
that is the result of this \code{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 \code{data}, but commonly would simply be named
arguments required by \code{fn}).
See below and examples.
}
\details{
\itemize{
\item \code{type}
\itemize{
\item \code{"screen"} -- Will plot to the current device, normally a plot window
\item \code{"object"} -- Will save the plot object, e.g., \code{ggplot} object
\item \code{"raw"} -- Will save the raw data prior to plotting, e.g.,
the data argument
\item \code{"png"} -- or any other type save-able with \code{ggsave}
}
}
}
\note{
\strong{This is still experimental and could change in the next release.}

\code{Plots} now has experimental support for "just a \code{Plot} call", but with \code{types} specified.
See examples.
The devices to save on disk will have some different behaviours to the screen representation,
since "wiping" an individual plot on a device doesn't exist for a file device.

This offers up to 4 different actions for a given plot:
\itemize{
\item To screen device
\item To disk as raw data (limited testing)
\item To disk as a saved plot object  (limited testing)
\item To disk as a \file{.png} or other image file, e.g., \file{.pdf}
}

To turn off plotting both to screen and disk, set both
\code{.plotInititalTime = NA} and \code{.plots = NA} or any other
value that will not trigger a TRUE with a \code{grepl} with the \code{types}
argument (e.g., \code{""} will omit all saving).
}
\section{Recording of files saved}{

In cases where files are saved, and where \code{Plots} is used within a SpaDES module,
the file(s) that is/are saved will be appended to the \code{outputs} slot of the
\code{simList} of the module. This will, therefore, keep a record of figures saved
\emph{within} the \code{simList}
}

\examples{
\donttest{
  # 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. Otherwise, it will cause a memory leak.
  if (requireNamespace("ggplot2")) {
    fn <- function(d)
      ggplot2::ggplot(d, ggplot2::aes(a)) +
      ggplot2::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(tempdir(), "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(tempdir(), "figures"),
      filename = tempfile(),
      .plotInitialTime = 1
    )

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

    # with ggplotify, Plots can also be used to plot/save
    # non-ggplot objects:


    if (require("ggplotify")) {
      if (!require("lattice")) stop("please install lattice")

      p1 <- densityplot(~mpg|cyl, data=mtcars)
      Plots(data = p1, fn = as.ggplot, filename = tempfile(),
            ggsaveArgs = list(width = 5, height = 4, dpi = 300,
                              bg = "white", units = "in"),
            types = c("screen", "png"),
            .plotInitialTime = 1)
    }
  } # end ggplot
  unlink("figures") # clean up
} # end of dontrun
}
