Learn R Programming

tis (version 1.23)

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(off
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 vect
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 typ
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
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 p
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.

Value

  • tierChart invisibly returns a list with the following components:
  • pxa matrix with nYears columns containing the x coordinates of the points for each year.
  • pya matrix with nYears columns containing the y coordinates of the points for each year.
  • ymdmatrix of yyyymmdd dates corresponding to x coordinates in px
  • indexmatrix giving positions of the elements of the y matrix in the original x series, that is, x[index[i,j]] == y[i,j]
  • lBoxvector of 4 numbers giving the c(left, bottom, right, top) bounds of the scroll arrow box in the upper left corner of the plot.
  • rBoxvector of 4 numbers giving the c(left, bottom, right, top) bounds of the scroll arrow box in the upper right corner of the plot.
  • printBoxvector of 4 numbers giving the c(left, bottom, right, top) bounds of the print box in the adjoining the left scroll box.
  • startMonththe input argument of the same name
  • nMonthsnumber of months wide the plot is
  • nYearsnumber of years plotted
  • If the input argument code{boxes} 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.

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.

See Also

monthplot for a nice way to look at seaonality in monthly data.

Examples

Run this code
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

Run the code above in your browser using DataLab