tis: tierChart – R documentation

Become an expert in R — Interactive courses, Cheat Sheets, certificates and more!

tierChart

Create tier charts

Description

A tier chart plots several years' observations of a series against the times of year in which they were observed. Useful for seeing seasonal patterns in daily, weekly and irregularly-spaced data.

Usage

tierChart(x,
          startMonth = latestJanuary(end(x)),
          nMonths = 4,
          nYears = 7,
          offsets = 0,
          padDays = 6,
          pch = "year",
          lty = "solid",
          lwd = 1.5,
          col = 1 + (n.y:1),
          type = "b",
          ylim = NULL,
          outlier.trim = 0,
          noTrimLastYear = TRUE,
          extendHorizontalTicks = TRUE,
          circles.ymd = NULL,
          circles.col = 6,
          circles.inches = 0.1,
          vlines.ymd = NULL,
          vlines.col = 2,
          vlines.lty = 4,
          vlines.lwd = 1.5,
          vlines2.ymd = NULL,
          vlines2.col = 3,
          vlines2.lty = "solid",
          vlines2.lwd = 2,
          hlines = NULL,
          hlines.col = 1,
          hlines.lty = 1,
          hlines.lwd = 1,
          tiPoints.1 = NULL,
          tiPoints.2 = NULL,
          pch.1 = "*",
          pch.2 = "+",
          col.1 = 2,
          col.2 = 3,
          nolegend = FALSE,
          main = deparse(substitute(x)),
          topleft.labels = NULL,
          topright.labels = NULL,
          legend.ncol = length(years),
          legend.bg = 0,
          timestamp = TRUE,
          topline = TRUE,
          vlines.periodEnd = TRUE,
          vlines.month = TRUE,
          midperiod = FALSE,
          lwdLastYear = 1.5,
          cex = 1.5,
          boxes = TRUE,
          ...)

adjustableTierChart(x,
                    ...,
                    edit = TRUE,
                    changes = numeric(0),
                    verbose = FALSE)

Arguments

`x`	A monhly or higher frequency (such as weekly or daily) time indexed series (a `tis` object) or something that `as.tis` can convert to one.
`startMonth`	a monthly time index (`ti`) object indicating first month to show on plot.
`nMonths`	number of months to show on plot.
`nYears`	number of years to include in the plot.
`offsets`	vector of day offsets for the years in descending order. If `offsets[2]` is 3, for example, the points for the second-to-last year will be shifted forward 3 days on the plot. Negative numbers shift points back. If `length(offsets) < nYears`, zeroes will be appended to `offsets` to make it `nYears` long.
`padDays`	number of extra days to plot before and after the requested months.
`pch`	plotting symbols to be drawn when plotting points. If pch is a character string, such as "a1b2", the first year's points will be labeled "a", the second year's with "1", the third with "b", and so on. Alternatively, pch can be a numeric vector giving the numbers of plotting symbols to use, as detailed in the documentation for `lines`. The default string "year" uses the last digit of the year number for each point in that year.
`lty`	vector of line types. The first element is for the first year, the second element for the second year, etc., even if lines are not plotted for all years. Line types will be used cyclically until all years are drawn.
`lwd`	number specifying line width
`col`	vector of colors for the years, specified as numbers or color names.
`type`	character string, telling which type of plot (`"p"`, points; `"l"`, lines; `"b"`, both; `"n"`, none; or `"h"`, high-density) should be done for each year. The first character of `type` defines the first year, the second character the second, etc. Characters in `type` are cycled through; e.g., `"pl"` alternately plots points and lines. The default is "b".
`ylim`	ylim is a vector of 2 numbers giving desired y-axis limits. The actual limits on the plot will be the result of `pretty(ylim)`. If `ylim` is not set explicitly, the value of `outlier.trim` is used to calculate it such that the `c(outlier.trim, 1 - outlier.trim)` quantiles of the plotted points fall within the calculated `ylim` before it is "prettied".
`outlier.trim`	see `ylim` above
`noTrimLastYear`	if `TRUE` (the default), `outlier.trim` is effectively set to zero for the most recent year, i.e., the y-axis limits will be expanded, if necessary, to insure that all of the points plotted for the most recent year fit on the plot.
`extendHorizontalTicks`	if `TRUE` (the default), extend the horizontal ticks with a dotted line all the way across the chart.
`circles.ymd`	draws circles around the plotted points corresponding to these ymd dates. The colors and sizes of the circles are given by `circles.col` and `circles.inches`.
`circles.col`	see `circles.ymd` above.
`circles.inches`	see `circles.ymd` above.
`vlines.ymd`	numeric vector of yyyymmdd dates, draws vertical lines of type `vlines.lty` width `vlines.lwd` and colors `vlines.col` at the dates given.
`vlines.col`	see `vlines.ymd` above
`vlines.lty`	see `vlines.ymd` above
`vlines.lwd`	see `vlines.ymd` above
`vlines2.ymd`	numeric vector of yyyymmdd dates, draws vertical lines of type `vlines2.lty` width `vlines2.lwd` and colors `vlines2.col` at the dates given.
`vlines2.col`	see `vlines2.ymd` above
`vlines2.lty`	see `vlines2.ymd` above
`vlines2.lwd`	see `vlines2.ymd` above
`hlines`	numeric vector, draws horizontal lines of type `hlines.lty` width `hlines.lwd` and colors `hlines.col` at the locations given.
`hlines.col`	see `hlines` above
`hlines.lty`	see `hlines` above
`hlines.lwd`	see `hlines` above
`tiPoints.1`	a `ti` object specifying dates for which the corresponding points will be marked with the characters in `pch.1` in colors `col.1`.
`pch.1`	see `tiPoints.1` above
`col.1`	see `tiPoints.1` above
`tiPoints.2`	a `ti` object specifying dates for which the corresponding points will be marked with the characters in `pch.2` in colors `col.2`.
`pch.2`	see `tiPoints.2` above
`col.2`	see `tiPoints.2` above
`nolegend`	if `T` do not plot a legend
`main`	character string giving main title for the chart.
`topleft.labels`	strings to place in left corner of top margin
`topright.labels`	strings to place in right corner of top margin
`legend.ncol`	number of columns to use for legend. Has no effect if `nolegend` is `T`.
`legend.bg`	background color for legend
`timestamp`	if `T` put a timestamp in upper right corner of top margin
`topline`	if `T` (the default) draw an axis line across the top of the plot
`vlines.periodEnd`	if `T` (the default) draw a light vertical line at each period end of the most recent year plotted.
`vlines.month`	if `T` (the default) draw a light vertical line at month boundaries
`midperiod`	if `T` draw the point for each period on the middle day of the period. If `F` (the default) draw points on the last day of the period.
`lwdLastYear`	line width for the last year plotted.
`boxes`	if `T` (the default) add scroll arrow and PrintMe boxes to the plot for use by `adjustableTierChart`.
`cex`	numeric character expansion factor for the characters denoting the points on the plot.
`...`	for `adjustableTierChart`, arguments to be passed on to `tierChart`. For `tierChart`, ... denote arguments to be passed to `matplot`, which does the actual plotting.
`edit`	if `T`, the points on the plot are editable. Clicking above or below a point draws an arrow from the point to it desired new location.
`changes`	used internally by the function to remember what points have been moved thus far while scrolling. This argument should never be set by the user.
`verbose`	if `T`, `adjustableTierChart` is chattier about what it is doing.

Details

A tier chart shows seasonal patterns in data by superimposing the data from the same months of several years onto a single plot. Tier charts can be used both to present a view of a time series and to graphically edit its values by pointing and clicking.

For most purposes, adjustableTierChart is preferred to tierChart, since the former presents a chart that can be edited, scrolled and printed via mouse clicks, while the latter simply draws a single chart and returns. However, adjustableTierChart requires user interaction, which may make it unsuitable for some uses.

When adjustableTierChart is called, it draws on the current graphics device and then waits for mouse clicks to occur. A left mouse button click on one of the scroll arrows changes the display to show adjacent months, while a left mouse click on the PrintMe box causes the current plot to be copied to the printer. Left mouse clicks in the data area of the plot are used to edit the values of the time series. Arrows are drawn from the current data points to the mouse location to show where the new data values will be.

A middle mouse button click causes adjustableTierChart to return. Closing the graphics window via the windowing system (e.g., clicking on the window's X button) has the same effect. Until adjustableTierChart is told to return, the entire R process will appear to be frozen. It isn't actually frozen, it's just waiting for mouse input. Use tierChart instead if no user interaction is desired.

Value

tierChart invisibly returns a list with the following components:

`px`	a matrix with `nYears` columns containing the x coordinates of the points for each year.
`py`	a matrix with `nYears` columns containing the y coordinates of the points for each year.
`ymd`	matrix of yyyymmdd dates corresponding to x coordinates in `px`
`index`	matrix giving positions of the elements of the y matrix in the original x series, that is, x[index[i,j]] == y[i,j]
`lBox`	vector of 4 numbers giving the c(left, bottom, right, top) bounds of the scroll arrow box in the upper left corner of the plot.
`rBox`	vector of 4 numbers giving the c(left, bottom, right, top) bounds of the scroll arrow box in the upper right corner of the plot.
`printBox`	vector of 4 numbers giving the c(left, bottom, right, top) bounds of the print box in the adjoining the left scroll box.
`startMonth`	the input argument of the same name
`nMonths`	number of months wide the plot is
`nYears`	number of years plotted

If the input argument codeboxes is F, the lBox, rBox and printBox elements of the list will not be present.

adjustableTierChart returns the edited input series x as a tis object, with an additional startMonth attribute.

Side Effects

a tier chart is drawn on the current graphics device.

Examples

## Not run: 
tierChart(m1.w)   ## January - April of 7 most recent years

tierChart(m1.w, startMonth=1, nMonths = 12)  ## Tier chart for entire year

tierChart(m1.w, type="l", lty=1)   ## same as first example, but with
                                   ## solid lines and no plotting symbols

xe <- adjustableTierChart(x)    ## xe will be edited version of x

## End(Not run)

tis

Time Indexes and Time Indexed Series

v1.38

Unlimited

Authors

Jeff Hallman <jeffhallman@gmail.com>

Initial release