plot.yourcast: Plot generation tool for YourCast
In IQSS/YourCast: Forecasting Age-Sex-Country-Cause Mortality Rates

Description Usage Arguments Details Value Author(s) References See Also Examples

Creates graphics from YourCast output for each geographical unit and prints to the device window or a .pdf file in the specified directory.

## S3 method for class 'yourcast'
plot(x, plots=c("age","time"), title=NULL, subtitle=NULL, 
     age.opts=list(), time.opts=list(), threedim.opts=list(),totcount.opts=list(), 
     ex0.opts=list(),print="device", print.args=list(), dv.log=NA, ...)

`x`	A `yourcast` output object.
`plots`	Vector of strings specifying the plot types to be generated. The available plots are age profile (`"age"`), time profile (`"time"`), 3D age/time profile (`"threedim"`), total counts by year (`"totcount"`), and life expectancy at birth (`"ex0"`). The order in which the plots are specified is the order in which they are generated in the device. A maximum of 3 plot types is allowed. Default: `c("age","time")`.
`title`	String. Main title for the plots. Concatenated with country name if `dataobj$G.names` exists. Default: `NULL`.
`subtitle`	String. Subtitle for the plots. Default: `NULL`.
`age.opts`	A list of options for the age profile plot. See ‘Details’.
`time.opts`	A list of options for the time profile plot. See ‘Details’.
`threedim.opts`	A list of options for the 3D plot. See ‘Details’.
`totcount.opts`	A list of options for the total counts plot. See ‘Details’.
`ex0.opts`	A list of options for the life expectancy at birth plot. See ‘Details’.
`print`	String specifying whether graphical output should be displayed sequentially on a device window (`"device"`) or saved directly to a ‘.pdf’ file in the `dpath` (`"pdf"`). Default: `"device"`.
`print.args`	A list of options for the device. See ‘Details’.
`dv.log`	Logical. Is the dependent variable logged? If `NA`, the function parses the formula in the `yourcast` object to determine if the dependent variable is logged. Default: `NA`.
`...`	Further arguments passed to or from other methods.

Plots age profiles, time profiles, 3D age/time profiles, total counts (by time), and life expectancy at birth from yourcast output. Total count (by time) plots should only be used if forecasting counts (eg. population or death counts) and life expectancy at birth should only be used if forecasting mortality rates - both are common quantities of interest calculated from these forecasts and are thus included in the function. See lifetable for details of life expectancy at birth calculations from mortality rates. All plots are created using the ggplot2 package, except for the 3D age/time profile, which is created using the wireframe function from the lattice library.

The function supports multiple plots in each call (up to 3) and arranges them horizontally in the order specified in plots argument. The device window is automatically resized to accomodate different number of plots, albeit device width and height may be specified manually through the print.args option (see below).

Plots are titled with the title and the G.names dataframe if it was supplied to yourcast in the dataobj. For example if title="Respiratory Infections" and the geographic identifier for that region is matched with "Belize", the plot will be titled “Respiratory Infections, Belize”. One or both labels will be utilized by the function if available. A subtitle may also be specified through subtitle.

It is important to note that plot.yourcast will only work if all cross sections within the same geographic unit are of the same dimensions. If, for example, a cross section for one age group has fewer yearly observations than another from the same group, these missing years must be filled in with NA, even if they occur in the beginning of the sample period. This does not hold across geographic units, however.

Finally, note that plot.yourcast opens a new device window for each new plot. This is done so that the size of the device can be controlled to keep the side-by-side plots from appearing distorted when launched.

Options for ‘age’, ‘time’, ‘totcount’, and ‘ex0’ plots

Options for the age profile, time profile, total count, and life expectancy at birth plots may be specified using the age.opts, time.opts, totcount.opts, and ex0.opts arguments, respectively, which are lists with any of following components:

xlab: String specifying the x-axis label. Default is "Age" for ‘age’ plots and "Time" for ‘time’, ‘totcount’, and ‘ex0’ plots.
ylab: String specifying the y-axis label. Default is "Data and Forecasts" for ‘age’ plots and "Forecasts" for ‘time’ plots.
insamp.obs: Logical. Should the observed data be plotted? Default for ‘age’, ‘totcount’, ‘ex0’ is TRUE; default for ‘time’ is FALSE.
insamp.predict: Logical. Should the predicted data be plotted for the in-sample period? Default: TRUE.

Additionally, the following options may be passed to age.opts and time.opts lists:

age.select: A numeric vector listing the ages to be plotted. If a scalar is supplied, it is used as the step size in a sequence of ages between the minimum and the maximum age. If NULL, all ages are plotted. Default: NULL.
time.select: A numeric vector listing the times to be plotted. If a scalar is supplied, it is used as the step size in a sequence of times between the minimum and the maximum time. If NULL, all times are plotted. Default: NULL.
unlog: Logical. Should the dependent variable be unlogged for ‘age’ and ‘time’ plots? Ignored if dv.log is set to FALSE. Default: FALSE.

Option age.select may be included in the totcount.opts list, but it functions differently than for the ‘age’ and ‘time’ plots. Instead of designating the ages to plot, age.select should be a numeric vector listing the ages to be summed over in the calculation of total counts over time.

For ‘ex0’ plots, options ax, a0, and nx that control the calculation of life tables from mortality rates in yourcast objects may be included in the ex0.opts list. By default, ax is set to 0.5, a0 is set to 0.07, and nx is set to NULL. See lifetable for additional information.

Options for ‘threedim’ plot

Options for the 3D age/time profile may be specified through threedim.opts. The argument must be a list with any of the following components:

xlab: String specifying the x-axis label. This corresponds to the time dimension. Default: "Time".
ylab: String specifying the y-axis label. This corresponds to the age dimension. Default: "Age".
zlab: String specifying the z-axis label. This corresponds to the dependent variable. Default: "Forecasts"
insamp.pred: Logical. If TRUE, the forecasted data is plotted for the in-sample period. If FALSE, the observed data is plotted instead. Default: TRUE.
unlog: Should the dependent variable be unlogged? Ignored if dv.log is set to FALSE. Default: FALSE.
args.wireframe: A list of arguments (must be labeled) to be passed to wireframe. Note that some arguments to wireframe such as zlab and screen should be made as arguments to threedim.opts; they will be overwritten if found in args.wireframe.
screen: List with three elements ‘x’, ‘y’, and ‘z’ that rotate the viewing angle for the 3D plot. Default: list(z=-40, x=-60, y=0).

Print options

The function prints sequentially to the device or saves ‘.pdf’ files with the requested plot for each geographic unit in the sample. If requested, ‘.pdf’ files will be saved in a specified directory or the working directory. Use print.args to set print options:

height: Height of device. Default is 5 inches.
width: Width of device. Default width adjusts automatically according to number of plots.
filename: A string or vector of strings denoting the filename(s) of ‘.pdf’s created for each geographical area if print="pdf". If a string, the csid code is automatically appended if multiple geographies so as to ensure unique filenames. If the vector is of the length equal to the number of geographies, the csid is not appended, albeit the order of the labels should be the same as the order of the areas in dataobj$data. Default: NULL, in which case plots are titled as plotgggg.pdf, where gggg denotes the csid.
dpath: A string giving the directory where ‘.pdf’ files will be output if print="pdf". Default: getwd().

Device windows with requested plots or ‘.pdf’ files saved in the dpath.

Konstantin Kashin kkashin@fas.harvard.edu, based on an earlier version by Jon Bischof.

http://gking.harvard.edu/yourcast

yourcast function and documentation (help(yourcast))

# Run Lee-Carter model for Figure 2.6 in Demographic Forecasting
data(chp.2.6.1)
ff.allc <- log(allc2/popu2) ~  time	
ylc.allc <- yourcast(formula=ff.allc, dataobj=chp.2.6.1, model="LC",
                       elim.collinear=FALSE,
                       sample.frame=c(1950,2000,2001,2060))
# default
plot(ylc.allc,title="All causes of death")

## Not run: 
# output plots to pdf
plot(ylc.allc,title="All causes of death", print="pdf")

# output plots to pdf with names "acd"+csid
plot(ylc.allc,title="All causes of death", print="pdf",
print.args=list(filename="acd"))

# order matters
plot(ylc.allc,plots=c("time","age"),title="All causes of death")
plot(ylc.allc,plots=c("age","time"),title="All causes of death")
## End(Not run)

# remove in-sampled predicted data from age profile plot
plot(ylc.allc,title="All causes of death",age.opts=list(insamp.predict=FALSE))

# plot every 10th age instead of every 5th age for age profile plot
plot(ylc.allc,title="All causes of death",
age.opts=list(insamp.predict=FALSE,age.select=10))

## Not run: 
# plot every 5th year instead of every year for time series plot
plot(ylc.allc,title="All causes of death",
age.opts=list(insamp.predict=FALSE),time.opts=list(time.select=5))

# only plot data from 2000+
plot(ylc.allc,title="All causes of death",
age.opts=list(insamp.predict=FALSE, time.select=seq(2001,2060,5)),
time.opts=list(time.select=seq(2001,2060,5)))

# plot unlogged mortality rates
plot(ylc.allc,title="All causes of death",
age.opts=list(insamp.predict=FALSE, unlog=TRUE),time.opts=list(unlog=TRUE))

# plot `threedim' plot in addition to age and time profiles
plot(ylc.allc,plots=c("threedim","age","time"),
title="All causes of death",age.opts=list(insamp.predict=FALSE))

# plot life expectancy at birth in addition to age and time profiles
# since these are 5-year age groups, assume ax=2.5 and a0=1.907
plot(ylc.allc,plots=c("ex0","age","time"),title="All causes of death",
age.opts=list(insamp.predict=FALSE), ex0.opts=list(a0=1.907,ax=2.5))
## End(Not run)