mapmate (version 0.3.1)

save_ts: Save time series plots

Description

Save a time series plot to disk intended to be part of a as a still image sequence of a growing time series.

Usage

save_ts(data, x, y, id, cap, dir = ".", col = "black", xlm, ylm,
  axes.only = FALSE, axes.space = TRUE, file = "Rplot",
  png.args = list(width = 1920, height = 1080, res = 300, bg = "transparent"),
  save.plot = TRUE, return.plot = FALSE, overwrite = FALSE,
  num.format = 4)

Arguments

data

data frame containing the x and y plotting variables.

x

character, the column name in data for the variable plotted along the x axis.

y

character, the column name in data for the variable plotted along the y axis.

id

character, column name referring to column of data representing frame sequence integer IDs.

cap

time index/frame ID used to subset data. The rows of data retained are all those where p <= cap, where p represents the frame ID values in column id. Defaults to all data if missing.

dir

png output directory. Defaults to working directory.

col

color of the time series line or the axes lines, ticks, and text. Defaults to black.

xlm

x axis limits.

ylm

y axis limits.

axes.only

only plot axis information, no data. Defaults to FALSE.

axes.space

if axes.only=TRUE, leave room for x and y axes in plot window when axes.space=TRUE. Remove this marginal area so that data are plotted over the full canvas when axes.space=FALSE. Defaults to TRUE. Ignored when axes.only=TRUE because of the explicit intent to draw axes.

file

character, output filename pattern preceeding the image sequence numbering and file extension. Defaults to "Rplot".

png.args

a list of arguments passed to png.

save.plot

save the plot to disk. Defaults to TRUE. Typically only set to FALSE for demonstrations and testing.

return.plot

return the ggplot object. Defaults to FALSE. Only intended for single-plot demonstrations and testing, not for still image sequence automation.

overwrite

logical, overwrite existing files. Defaults to FALSE. If file exists and return.plot=TRUE the plot is still returned. Otherwise returns NULL. This is a frame by frame check on each file. File writing is simply skipped for existing files when overwrite=FALSE. No error or warning is thrown.

num.format

number of digits including any leading zeros for image sequence frame numbering. Defaults to 4, i.e. 0001, 0002, ....

Value

usually returns NULL after writing file to disk. May return a ggplot object with or without the file writing side effect.

Details

For id column frame ID values i, cap subsets data to rows where i <= cap. Sequential application of save_ts should involve iterating cap over the values i. A data frame passed to save_map need not be subset based on the current frame ID in advance so providing cap values is important. See example.

When calling save_ts iteratively from the save_seq wrapper function, save_ts is applied over a list of sequentially subsetted data frames based on the frame IDs. In this case, specifying cap is not needed and an error will be thrown if provided.

Fixed axis limits must be established in advance by computing the max range or other desired range for the x and y variables that are to be plotted.

Examples

# NOT RUN {
library(dplyr)
library(purrr)
data(annualtemps)
temps <- mutate(annualtemps, frameID = Year - min(Year) + 1) %>%
  group_by(Year, frameID) %>% summarise(z=mean(z))
xlm <- range(temps$Year)
ylm <- range(temps$z)

# should specify a dir or set working dir for file output
# consider running over a smaller subset of frame IDs
walk(temps$frameID, ~save_ts(temps, x="Year", y="z", id="frameID",
  cap=.x, col="blue", xlm=xlm, ylm=ylm))
# }