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 irregularlyspaced data.
Usage
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57  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 
startMonth 
a monthly time index ( 
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

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

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
( 
ylim 
ylim is a vector of 2 numbers giving desired yaxis limits. The
actual limits on the plot will be the result of 
outlier.trim 
see 
noTrimLastYear 
if 
extendHorizontalTicks 
if 
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 
see 
circles.inches 
see 
vlines.ymd 
numeric vector of yyyymmdd dates, draws vertical lines of type

vlines.col 
see 
vlines.lty 
see 
vlines.lwd 
see 
vlines2.ymd 
numeric vector of yyyymmdd dates, draws vertical lines of type

vlines2.col 
see 
vlines2.lty 
see 
vlines2.lwd 
see 
hlines 
numeric vector, draws horizontal lines of type 
hlines.col 
see 
hlines.lty 
see 
hlines.lwd 
see 
tiPoints.1 
a 
pch.1 
see 
col.1 
see 
tiPoints.2 
a 
pch.2 
see 
col.2 
see 
nolegend 
if 
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

legend.bg 
background color for legend 
timestamp 
if 
topline 
if 
vlines.periodEnd 
if 
vlines.month 
if 
midperiod 
if 
lwdLastYear 
line width for the last year plotted. 
boxes 
if 
cex 
numeric character expansion factor for the characters denoting the points on the plot. 
... 
for 
edit 
if 
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 
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 
py 
a matrix with 
ymd 
matrix of yyyymmdd dates corresponding to x coordinates in 
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.
See Also
monthplot
for a nice way to look at seaonality in monthly
data.
Examples
1 2 3 4 5 6 7 8 9 10 11  ## 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)
