sparklines            package:YaleToolkit            R Documentation

_D_r_a_w_s _a _p_a_n_e_l _o_f _v_e_r_t_i_c_a_l_l_y _s_t_a_c_k_e_d _s_p_a_r_k_l_i_n_e_s

_D_e_s_c_r_i_p_t_i_o_n:

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

_U_s_a_g_e:

     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)

_A_r_g_u_m_e_n_t_s:

      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.

_D_e_t_a_i_l_s:

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

_N_o_t_e:

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

_A_u_t_h_o_r(_s):

     John W. Emerson, Walton Green

_R_e_f_e_r_e_n_c_e_s:

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

_S_e_e _A_l_s_o:

     'ts.plot', 'sparkline', 'sparkmat'

_E_x_a_m_p_l_e_s:

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

