tis: tisPlot – R documentation

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

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, shadeDates = NULL, shadeColor = "gray",
        shadeBorder = FALSE, polyArgs = 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 are a mix of dots and dashes.
`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` for why you might or might not want to do this. The default is `FALSE`.
`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`	a single number or two numbers between 0 and 1. `xAxisMin` and `xAxisMax` will be calculated by multiplicatively extending the data range in both directions by these amounts. 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` and `xAxisMax`, then (ii) including those as endpoints, generate a sequence of every `xTickSkip`'th `ti` between them. Two special strings can also be given. "none" means no labelled tick marks, while "auto" tries (not always successfully) to come up with reasonable tick locations automatically. "auto" also overrides any `xTickSkip` setting. The default is "auto".
`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 (which reflect the last day of the period) are centered under the ticks, else they are (almost) right aligned with the ticks. If rotated labels are specified by nonzero `xLabelRotationDegrees`, tick labels are right aligned with their ticks.
`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`	a single number or two numbers between 0 and 1. `leftAxisMin` and `leftAxisMax` will be calculated by multiplicatively extending the data range in both directions by these amounts. 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`	a single number or two numbers between 0 and 1. `rightAxisMin` and `rightAxisMax` will be calculated by multiplicatively extending the data range in both directions by these amounts. 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 corresponding distance between the extremes.
`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 by `1 - topLabelAlign`.
`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 right edge of the plot.
`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 the extremes.
`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` the same length as `foot`.
`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 in extra space in the bottom figure margin.
`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 interpreted as a fraction of the relevant side, so if `tck = 1` grid lines are drawn. The default is `tck = 0.03`.
`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 default is `"u"`.
`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`, use `nberDates()` to set the `shadeDates`. This will result in shading of NBER recession periods. The default is `FALSE`.
`shadeDates`	a matrix of yyyymmdd dates with two columns named 'Start' and 'End' that specifies the date ranges to be shaded. `nberDates()` produces a suitable matrix. If this argument is `NULL` and `nberShade` is not `TRUE`, no shading is done.
`shadeColor`	color to shade periods specified by `shadeDates`. Passed along to the `ymdShade` function.
`shadeBorder`	if shading is being done, this argument tells what color the border of the shaded areas should be drawn in. It can also be a logical, in which case `TRUE` draws borders in the foreground color and `FALSE` does not draw borders on the shaded areas. Default is `FALSE`.
`polyArgs`	additional args that are passed along to the `ymdShade` function and eventually to `polygon` if shading of date ranges is being done.

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.

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.

Note

The arguments for tisPlot and its sister function scatterPlot have more descriptive names than the corresponding arguments in plot. They are also all of unique types, unlike, for example, the lty argument in the usual R plotting functions, which can be either character or numeric. Limiting each argument to a single type was done to make it easier to design a user interface to drive the functions.

Use tisLegend to add legends to a plot created by tisPlot or scatterPlot.

Examples

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()

tis

Time Indexes and Time Indexed Series

v1.38

Unlimited

Authors

Jeff Hallman <jeffhallman@gmail.com>

Initial release