sparklines {YaleToolkit}

Draws a panel of vertically stacked sparklines

Description

Draws a panel of vertically stacked, aligned sparklines, or time series.

Usage

sparklines(ss, times = NULL, overlap = FALSE, yscale = NULL,
           buffer = unit(0, "lines"), buffer.pars = NULL, IQR = NULL,
           ptopts = NULL, yaxis = TRUE, xaxis = "exterior",
           labeled.points = NULL, point.labels = NULL,
           label.just = c(1.2, 0.5), frame.pars = NULL,
           line.pars = gpar(lwd = 1), 
           outer.margin = unit(c(5, 4, 4, 2), "lines"), 
           outer.margin.pars = NULL, main = NULL, sub = NULL, 
           xlab = NULL, ylab = NULL, lcol = NULL, new = TRUE)

Arguments

ss

a data frame whose columns give the time series to be plotted

overlap

FALSE for stacked sparklines; TRUE for all plotted on the same y-axis.

times

the times at which to plot the data; if NULL (the default), equal spacing is assumed. All the sparklines must share the same times argument. If unaligned time series must be plotted, multiple calls to sparklines() are required.

yscale

either a vector of length 2 giving the y-limits for all sparklines, or a list having the same length as the number of columns in ss (each component of which is a 2-vector giving the associated sparkline scales). Defaults to NULL, in which case the scales for each sparkline are set to the sparkline's minimum and maximum values.

buffer

a buffer above the maximum and below the minimum values attained by the sparkline. Defaults to unit(0, 'lines').

buffer.pars

a list of graphics parameters describing the buffer area. See Details for more information.

IQR

a list of graphics parameters to shade or otherwise delineate the interquartile range of the sparkline. Defaults to NULL, in which case the IQR is not shown. See Details for more information.

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'.

yaxis

draws a vertical axis if TRUE; defaults to FALSE, in which case no axis is drawn.

xaxis

'interior' draws horizontal axes inside the plotting frame (for each sparkline); 'exterior' draws the common axis for all the sparklines outside the plotting frame; defaults to FALSE (no axis).

labeled.points

not implemented. See ptopts.

point.labels

not implemented. See ptopts.

label.just

not implemented. See ptopts.

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.

outer.margin

a vector of 4 units (bottom, left, top, right) giving the outer margin sizes in order (around the entire panel of sparklines). Defaults to unit(c(0,0,0,0), 'lines').

outer.margin.pars

a list of graphics parameters describing the outer margin. See Details for more information.

main

a main title, above the stack of sparklines.

sub

a character vector the length of length(ss) providing titles for the individual sparklines, printed to the right of the sparklines.

xlab

a string providing the label for the common x-axis or (probably a useless feature) a character vector the length of length(ss) providing x-axis labels for the individual sparklines.

ylab

a character vector the length of length(ss) providing y-axis labels for the individual sparklines.

lcol

a vector of colors the same length as the number of columns in ss to color the line. As in base graphics, can be either a vector of strings giving the color names, a numeric vector referring to the current pallette, or the output of functions like hsv or rgb

new

defaults to TRUE, which creates a new, empty page; otherwise adds the sparkline to the existing plot.

Details

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.

Note

We do not support non-aligned time series plots such as ts.plot(airmiles, Nile, nhtemp).

Author(s)

John W. Emerson, Walton Green

References

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

See Also

ts.plot, sparkline, sparkmat

Examples

### sparkline examples
data(beaver1)

## The default behaviour of sparklines
sparklines(beaver1)

sparklines(beaver1,
           outer.margin = unit(c(2,4,4,5), 'lines'),
           outer.margin.pars = gpar(fill = 'lightblue'),
           buffer = unit(1, "lines"),
           frame.pars = gpar(fill = 'lightyellow'),
           buffer.pars = gpar(fill = 'lightgreen'),
           yaxis = TRUE, xaxis=FALSE,
           IQR = gpar(fill = 'grey', col = 'grey'),
           main = 'Beaver 1')

data(YaleEnergy)
y <- YaleEnergy[YaleEnergy$name==YaleEnergy$name[2],]
sparklines(y[,c("ELSQFT", "STEAM")], times=y$year+y$month/12,
           main="Branford Electric and Steam Consumption")

## Adding a pair of sparklines to an existing plot

grid.newpage()
pushViewport(viewport(w = 0.8, h = 0.8))
sparklines(data.frame(x = rnorm(10), y = rnorm(10, mean=5)), new = FALSE)
popViewport()

grid.newpage()
pushViewport(viewport(w = 0.8, h = 0.8))
sparklines(data.frame(x = rnorm(10), y = rnorm(10, mean=2)),
                buffer = unit(1, "lines"),
                frame.pars = gpar(fill = 'lightyellow'),
                yaxis = TRUE, xaxis=FALSE,
                IQR = gpar(fill = 'grey', col = 'grey'), new = FALSE)
popViewport()