tis (version 1.37.1)

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.

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.

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
# 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
# }

Run the code above in your browser using DataCamp Workspace