sparkline            package:YaleToolkit            R Documentation

_D_r_a_w_s _a _s_p_a_r_k_l_i_n_e

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

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

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

     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)

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

       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.

_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()'. 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'.

_N_o_t_e:

     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.

_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', 'sparklines', 'sparkmat'

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

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

