tisPlot {tis} | R Documentation |
tisPlot
is a function with dozens of options for creating
high quality time series plots. Can be used with screenPage
.
tisPlot(..., leftAxis = TRUE, plotType = "l", lineType = "solid", lineWidth = 1.5, plotChar = "*", dataCex = 1, color = 1, midPoints = TRUE, dropNA = FALSE, 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())
... |
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 .
|
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 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 |
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 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 , 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 .
|
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.
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
.
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
.
evalOrEcho
, scatterPlot
,
tisLegend
, nberShade
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()