Save time series plots

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

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))
# }