sparkline {YaleToolkit} | R Documentation |
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.
### 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()