tisPlot: Plot time indexed series (tis objects)

Description Usage Arguments Details Value Note See Also Examples

View source: R/tisPlot.R

Description

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

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
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.

See Also

evalOrEcho, scatterPlot, tisLegend, nberShade

Examples

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
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()

Example output



tis documentation built on Sept. 29, 2021, 1:06 a.m.