tisPlot: Plot time indexed series (tis objects)

Description

tisPlot is a function with dozens of options for creating high quality time series plots. Can be used with screenPage.

Usage

tisPlot(..., 
        leftAxis = TRUE, plotType = "l",
        lineType = "solid", lineWidth = 1.5,
        plotChar = "*", dataCex = 1, color = 1,
        midPoints = TRUE, dropNA = FALSE, xOffset = 0,
        xAxisMin = NULL, xAxisMax = NULL, xExpandBy = 0.04,
        xTickFreq = "Auto", xTickSkip = 0,
        xUnlabeledTickFreq = "None", xUnlabeledTickSkip = 0,
        xMinorTickFreq = "None", xMinorTickSkip = 0,
        dateFormat = "Auto", xCex = 1,
        midLabels = FALSE, yearLabels = FALSE,
        xAxisLabel = NULL, xSpace = 4, log = FALSE,
        leftAxisMin = NULL, leftAxisMax = NULL, leftExpandBy = 0.04,
        leftTicks = 5, leftTickLocations = NULL,
        labelLeftTicks = FALSE, leftTickLabels = NULL,
        rightAxisMin = NULL, rightAxisMax = NULL, rightExpandBy = 0.04,
        rightTicks = 5, rightTickLocations = NULL,
        labelRightTicks = TRUE, rightTickLabels = NULL,
        yCex = 1, extendTopTick = TRUE,
        cex = 1,
        head = NULL, headAlign = 0.5, headCex = 1.5,
        sub = NULL, subCex = 0.85,
        leftTopLabel = NULL, rightTopLabel = NULL, topLabelAlign = 0,
        labCex = 1,
        leftInsideLabel = NULL, rightInsideLabel = NULL,
        innerLine = 0.5, innerOffset = 0.05, innerCex = 0.8,
        foot = NULL, footColor = "black", footAlign = 0,
        footCex = 0.8, footSpace = -1,
        tck = 0.03,
        axisWidth = 2,
        start = 0, end = 0,
        boxType = "u",
        leftMargin = -1, rightMargin = -1, topMargin = -1, bottomMargin = -1,
        nberShade = FALSE, nberColor = "gray", nberBorder = FALSE, nberArgs = list())

Arguments

...

any number of univariate or multivariate tis series to be plotted. Non-tis arguments will be converted by as.tis.

leftAxis

logical. leftAxis[i] = TRUE means plot the i'th series against the left axis, otherwise plot it against the right axis.

plotType

type of plot desired. Values are "p" for points, "l" for lines, "b" for both points and lines (lines miss the points), and "o" for overlaid points and lines.

lineType

character or numeric vector specifying the line type for each series. The default is 1:nSeries, where nSeries is the number of series being plotted. Normally type 1 is solid, 2 is dotted, 3 and up ar

lineWidth

numeric vector of line widths for the series. The default value is 1.5.

plotChar

vector of characters (or numbers for plotting symbols -- see the help for points for details) to be used for plotting points. Default is "*".

dataCex

numeric vector. cex times these numbers give the character expansion factor for the data points. Default is 1.

color

character or numeric vector specifies color for each series. Default is 1, the device default foreground color.

midPoints

logical. midPoints[i] = TRUE aligns the data points of the i'th series with the middle day of the periods in which they fall, otherwise data points are aligned with the last day of their periods.

dropNA

if TRUE, observations with NA values are dropped before calling lines.default to draw the lines and/or points on the plot. See the details section of the help for lines.tis

xOffset

Shifts the data points for series[i] to the right by xOffset[i] days. This argument is replicated to be as long as the number of series.

xAxisMin

minimum value of the x axis. If non-NULL, this overrides the calculation described in xExpandBy.

xAxisMax

maximum value of the x axis. If non-NULL, this overrides the calculation described in xExpandBy.

xExpandBy

calculate xAxisMin and xAxisMax by multiplicatively extending the data range in both directions by this amount. Default value .04 extends the data range by 4% in each direction.

xTickFreq

a string like the ones returned by tifName. This argument and xTickSkip jointly specify locations for labeled x axis ticks as follow: (i) find the ti's of the given frequency that correspond to xAxisMin

xTickSkip

a number used with xTickFreq to specify location of labeled tick marks. The default is zero.

xUnlabeledTickFreq

same as xTickFreq, but for unlabeled major tick locations.

xUnlabeledTickSkip

same as xTickSkip, but for unlabeled major tick locations.

xMinorTickFreq

same as xTickFreq, but for minor tick locations.

xMinorTickSkip

same as xTickSkip, but for minor tick locations.

dateFormat

format string for x axis date labels. See strftime for formats. Default value "auto" tries to come up with a reasonable format automatically, for some bounded value of "reasonable".

xCex

cex times this number gives the character expansion factor for the x-axis labels. Default is 1.

midLabels

if TRUE (the default) x axis label are centered between the ticks they label; if FALSE the label alignment depends on the setting of midPoints. If midPoints is TRUE, the labels (whi

yearLabels

if TRUE place year labels centered under the x ticks they span. The default is FALSE.

xAxisLabel

text to appear centered under the x axis. Must be a single character string, multi-line xAxisLabel is not supported. No default.

xSpace

lines of space to set aside directly beneath the x-axis to hold tick, year and/or axis labels. Default is 4. The space created is xSpace times labCex.

log

if TRUE use log scaling for y axes. Default is FALSE.

leftAxisMin

minimum value of the left axis. If non-NULL, this overrides the calculation described in leftExpandBy.

leftAxisMax

maximum value of the left axis. If non-NULL, this overrides the calculation described in leftExpandBy.

leftExpandBy

calculate leftAxisMin and leftAxisMax by multiplicatively extending the data range of the leftAxis series in both directions by this amount. Default value .04 extends the data range by 4% in each direction.

leftTicks

number of ticks to draw on left axis at "pretty" locations. Default is 5. This argument is ignored if leftTickLocations is non-NULL.

leftTickLocations

if non-NULL, a vector of desired tick locations or a string that evaluates to such a vector. The default value NULL lets the setting for leftTicks take effect.

labelLeftTicks

If TRUE, label ticks on the left axis. Default is FALSE.

leftTickLabels

character vector of tick labels or NULL (the default). If NULL and labelLeftTicks is TRUE, labels are constructed from the tick locations. This argument has no effect if labelLeftTicks is FALSE.

rightAxisMin

minimum value of the right axis. If non-NULL, this overrides the calculation described in rightExpandBy.

rightAxisMax

maximum value of the right axis. If non-NULL, this overrides the calculation described in rightExpandBy.

rightExpandBy

calculate rightAxisMin and rightAxisMax by multiplicatively extending the data range of the rightAxis series in both directions by this amount. Default value .04 extends the data range by 4% in each direction.

rightTicks

number of ticks to draw on right axis at "pretty" locations. Default is 5. This argument is ignored if rightTickLocations is non-NULL.

rightTickLocations

if non-NULL, a vector of desired tick locations or a string that evaluates to such a vector. The default value NULL lets the setting for rightTicks take effect.

labelRightTicks

If TRUE, label ticks on the right axis. Default is FALSE.

rightTickLabels

character vector of tick labels or NULL (the default). If NULL and labelRightTicks is TRUE, labels are constructed from the tick locations. This argument has no effect if labelRightTicks is FALSE.

yCex

cex times this number gives the character expansion factor for the left and right axis labels. Default is 1.

extendTopTick

if TRUE (the default) the top tick of the y axes encloses the panel. leftAxisMax and rightAxisMax are increased as necessary to include the top tick for enclosing the panel.

cex

the base character expansion factor by which all of the ***cex parameters are scaled. The default setting is the value of par("cex").

head

text to appear at the top of the figure region, with alignment determined by headAlign. No default.

headAlign

number indicating justification for the strings in head and sub. 0 means left justify, 1 means right justify, 0.5 (the default) means to center the text. Other numbers are a correspondin

headCex

cex times this number gives the character expansion factor for head. Default is 1.5.

sub

text to appear just under head, with alignment determined by headAlign. No default.

subCex

cex times this number gives the character expansion factor for sub. Default is 0.85.

leftTopLabel

text to appear at the top of the left axis, with alignment determined by topLabelAlign. No default.

rightTopLabel

text to appear at the top of the right axis, with alignment determined by topLabelAlign. No default.

topLabelAlign

number indicating alignment for the strings in leftTopLabel. 0 (the default) means left justify, 1 means right justify, 0.5 means to center the text. rightTopLabel, if given, is aligned

labCex

cex times this number gives the character expansion factor for leftTopLabel, rightTopLabel, and xAxisLabel.

leftInsideLabel

text to appear left justified and just inside the upper left corner of the plot region. No default.

rightInsideLabel

text to appear right justified and just inside the upper right corner of the plot region. No default.

innerOffset

number between 0 and 1, a fractional offset for the inside labels. The left edge of leftInsideLabel is offset by this fraction of the x range from the left edge of the plot, as is the right edge of rightInsideLabel from the ri

innerLine

Number of lines in from the top edge of the plot to put the first line of the inside labels.

innerCex

cex times this number gives the character expansion factor for leftInsideLabel and rightInsideLabel.

foot

text to appear at the bottom of the figure region, with alignment determined by footAlign. Use a vector of character strings to get several footnotes. No default.

footAlign

number indicating justification for the strings in foot. 0 (the default) means left justify, 1 means right justify, 0.5 means to center the text. Other numbers are a corresponding distance between th

footCex

cex times this number gives the character expansion factor for foot. Default is 0.8.

footColor

character or numeric vector as long as foot, specifying the color for each footnote. Default is 1, the device default foreground color. The elements of this argument are cyclically repeated, if necessary, to make footColor th

footSpace

lines of space to set aside directly beneath the space allocated by xSpace to hold footnotes. The space created is footSpace times footCex. Default is length(foot); using a higher value will result i

tck

The length of xTick, xUnlabeledTick and side tick marks as a fraction of the smaller of the width or height of the plotting region. Minor ticks (xMinorTicks) are 2/3 as long. If tck >= 0.5 it is inte

axisWidth

line width for the axes and box (if any). Default is 2.

start

starting date for the plot. The default is the earliest start time of all the series. This argument can be supplied in any of the forms understood by ti().

end

end date for the plot. The default is the latest end time of all the series. This argument can be supplied in any of the forms understood by ti().

boxType

character representing the type of box. Characters "o", "l" (ell), "7", "c" will produce boxes which resemble the corresponding upper-case letters. The value "n" will suppress boxes. The

leftMargin

lines of space for the left margin. Default value (-1) figures this out automatically.

rightMargin

lines of space for the right margin. Default value (-1) figures this out automatically.

topMargin

lines of space for the top margin. Default value (-1) figures this out automatically.

bottomMargin

lines of space for the bottom margin. Default value (-1) figures this out automatically.

nberShade

if TRUE, call the nberShade function to shade recession periods on the plot. The default is FALSE.

nberColor

color to shade recessionary periods if nberShade is TRUE. Passed along to the nberShade function.

nberBorder

if TRUE and nberShade is also TRUE, draws borders on the NBER shaded areas. Default is FALSE.

nberArgs

additional args to be passed along to the nberShade function if nberShade is TRUE.

Value

tisPlot invisibly returns a list of class "tisPlot" and elements named series, dateFormat, plotType, lineType, dataCex, color, plotChar, lineWidth, yLegendOffset, cex, xRange, leftRange, rightRange, midPoints and par. This list is useful mostly as an argument to tisLegend.

Details

leftAxis, plotType, lineType, lineWidth, plotChar, dataCex, color and midPoints are all cyclically repeated to make them length nSeries, the number of series plotted.

Each of the text items head, sub, leftTopLabel, rightTopLabel, leftInsideLabel, rightInsideLabel, foot, and xAxisLabel can be given as a string, a collections of strings, or as a string that gets evaluated to one of the first two. (But xAxisLabel takes only a single string.) See the help details for evalOrEcho to see how this works.

Examples

Run this code

firstTis <- tis(cumsum(rnorm(120)), start = c(1996,1), freq = 12)
secondTis <- tis(cumsum(rnorm(120)), start = c(1996,1), freq = 12)
tisPlot(firstTis, secondTis, color = c("red", "green"),
           lineType = "solid", head = "Two Random Walks")
tisLegend(legend = c("Random Walk 1", "Random Walk 2"))

series <- tis(cumsum(rnorm(200)), start = c(1960,1), tif = "quarterly")
tisPlot(series, xMinorTickFreq = "annual", nberShade = TRUE,
        head = "A Random Walk", sub = "Looks like an econ series",
        rightTopLabel = "$Billions")
romerLines()

Run the code above in your browser using DataLab