sparkline: Draws a sparkline
In jayemerson/YaleToolkit: Data exploration tools from Yale University.

Description Usage Arguments Details Note Author(s) References See Also Examples

Draws a times series or ‘sparkline’ in a compact iconic fashion suitable for inclusion in more complex graphics or text.

sparkline(s, times = NULL, ylim = NULL, buffer = unit(0, "lines"),
          margins = NULL, IQR = NULL, yaxis = FALSE, xaxis = FALSE,
          ptopts = list(points = NULL, labels = NULL, labels.ch = NULL,
          gp = NULL, just = NULL, pch = NULL), margin.pars = NULL,
          buffer.pars = NULL, frame.pars = NULL, line.pars = gpar(lwd = 1),
          main = NULL, sub = NULL, xlab = NULL, ylab = NULL, new = TRUE)

`s`	a vector or time series (class `"ts"` or `"zoo"`) giving the data to be plotted. If `s` is a time series, the `start`, `end`, and `frequency` found in `attributes(s)$tsp` are automatically converted into an argument to `times`.
`times`	the times at which to plot the data; if `NULL` (the default), equal spacing is assumed, equivalent to setting `times = 1:length(s)`.
`ylim`	the maximum and minimum value on the y-axis; if `NULL`, defaults to the actual maximum and minimum of the data.
`buffer`	a buffer above the maximum and below the minimum values attained by the sparkline. Defaults to `unit(0, 'lines')`.
`margins`	margins around the sparkline-plus-buffer area. NULL (the default) provides no margins; the value passed must be a 4-vector of units giving the bottom, left, top and right margins in that order.
`IQR`	a list of graphics parameters to shade or otherwise delineate the interquartile range of the sparkline. `NULL` (the default), does not show the IQR. See `Details` for more information.
`yaxis`	draws a vertical axis if `TRUE`; defaults to `FALSE` in which case no axis is drawn.
`xaxis`	`'interior'` draws a horizontal axis inside the plotting frame; `'exterior'` outside the plotting frame (in the margins); defaults to `FALSE`, in which case no axis is drawn.
`ptopts`	a list of graphics parameters describing the points on the sparkline that are plotted and labelled. In particular the first and last or minimum and maximum points are labeled if `ptopts$labels` is `'first.last'` or `'min.max'`. In addition to `labels`, other relevant parameters from `gpar` should be valid. See `Details` for more information.
`margin.pars`	a list of graphics parameters describing the margin area. See `Details` for more information.
`buffer.pars`	a list of graphics parameters describing the buffer area. See `Details` for more information.
`frame.pars`	a list of graphics parameters describing the exact area taken up by the plotted sparkline. See `Details` for more information.
`line.pars`	a list of graphics parameters describing the sparkline. See `Details` for more information.
`main`	a main title, above the sparkline.
`sub`	a subtitle, to the right of the sparkline.
`xlab`	a string to label the x-axis.
`ylab`	a string to label the y-axis.
`new`	defaults to `TRUE`, which creates a new, empty page; otherwise adds the sparkline to an existing plot.

In all the cases where a list of graphics parameters is needed, the valid parameter names are the same as would be valid when passed to gpar in the appropriate call. That is, passing list(fill = 'blue', col = 'red') to margin gives a margin that is blue with a red border; but adding fontface = 'bold' will have no effect, just as it would have no effect in a call to grid.rect(). In particular, note that ptopts takes the following non-standard parameters: labels, a vector indexing the points to label or the string 'min.max' or 'first.last'; labels.ch, a vector of strings giving the labels; and points, a vector indexing the points at which points should be plotted. Passing 'min.max' or 'first.last' to ptopts$labels overrides any values of ptopts$labels.ch.

This is primarily intended to be called by other functions (sparklines() and sparkmat()), but it can also be used as an alternative to ts.plot(). Thanks to Gabor Grothendieck for suggesting the generalization that provides support of "zoo" objects.

John W. Emerson, Walton Green

Tufte, E. R. (2006) /it Beautiful Evidence Cheshire, Connecticut: Graphics Press.

ts.plot, sparklines, sparkmat

### sparkline examples
data(nhtemp)

## The default behaviour of sparkline

sparkline(nhtemp)

## Creating stand-alone plots

sparkline(rnorm(10),
                buffer = unit(1, "lines"),
                ptopts = 'first.last',
                margins = unit(c(1,1,1,1), 'inches'),
                yaxis = TRUE, xaxis=TRUE,
                IQR = gpar(fill = 'grey', col = 'grey'),
                main = "Ten Random Standard Normal Numbers",
                sub = '...plotted here')

data(YaleEnergy)
y <- YaleEnergy[YaleEnergy$name==YaleEnergy$name[2],]
sparkline(y$ELSQFT, times=y$year+y$month/12,
          xaxis=TRUE, yaxis=TRUE, main="Branford College Electrical Consumption",
          buffer=unit(1, "lines"), margins = unit(c(1, 1, 1, 1), 'inches'))

sparkline(Nile,
                buffer = unit(1, "lines"),
                ptopts = list(labels = 'min.max'),
                margin.pars = gpar(fill = 'lightblue'),
                buffer.pars = gpar(fill = 'lightgreen'),
                frame.pars = gpar(fill = 'lightyellow'),
                yaxis = TRUE, xaxis=TRUE,
                IQR = gpar(fill = 'grey', col = 'grey'),
                main="Nile Discharge between 1871 and 1970",
                sub='In what units?')

## Adding a sparkline to an existing plot

grid.newpage()
pushViewport(viewport(w = 0.8, h = 0.8))
sparkline(rnorm(10),
                buffer = unit(1, "lines"),
                margins = unit(c(4,4,4,4),'points'),
                ptopts = list(labels = 'min.max'),
                margin.pars = gpar(fill = 'lightblue'),
                buffer.pars = gpar(fill = 'lightgreen'),
                frame.pars = gpar(fill = 'lightyellow'),
                yaxis = TRUE, xaxis=TRUE,
                IQR = gpar(fill = 'grey', col = 'grey'),
                main="Title (plotted OUTSIDE the viewport)", new = FALSE)
popViewport()