fan: Fan Plot of Distributions Percentiles Over Time.

Description

Visualise sequential distributions using a range of plotting styles.

Usage

fan(data = NULL, data.type = "simulations", style = "fan", type = "percentile", 
 probs = if (type == "percentile") seq(0.01, 0.99, 0.01) else c(0.5, 0.8, 0.95), 
 start = 1, frequency = 1, anchor = NULL, anchor.time=NULL,
 fan.col = heat.colors, alpha = if (style == "spaghetti") 0.25 else 1, 
 n.fan = NULL, 
 ln = if(length(probs)

Arguments

data

Set of sequential simulation data, where rows represent simulation number and columns represent some form of time index. If data.type = "values", data must instead be a set of quantile values by rows for a set of probabilities (which need t

data.type

Indicates if data are sets of pre-calculated values based for defined probabilities data.type = "values" or simulated data data.type = "simulations". That later is the default.

style

Plot style, choose from fan (default), spaghetti boxplot or boxfan. See Examples and Details Sections for further explanation.

type

Type of percentiles to plot in fan or boxfan. Choose from, percentile (default) or interval.

probs

Probabilities related to percentiles or prediction intervals to be plotted (dependent on the type function. These values control the number of shades used in the fan or boxfan. These must be between 0 and 100 (inclus

start

The time of the first distribution in sims. Similar to use in ts.

frequency

The number of distribution in sims per unit of time in sims. Similar to use in ts.

anchor

Optional data value to anchor a forecast fan on. Typically this will be the last observation of the observed data series.

anchor.time

Optional data value for the time of the anchor. Useful for irregular time series.

fan.col

Palette of colours used in the fan or boxfan.

n.fan

The number of colours to use in the fan.

alpha

Factor modifying the opacity alpha; typically in [0,1].

Vector of number to plot contour lines on-top fan or boxfan. Must correspond to calculated percentiles in probs. By default takes either every percentile or prediction interval given in the probs argumen

med.ln

Add a median line to fan. Might be of particular use if type="interval". Only works when data.type = "simulations" and one of fan, boxfan or spaghetti styles.

ln.col

Line colour to be imposed on top of the fan. By default takes the darkest colour from fan.col argument, unless style="spaghetti"

med.col

Median Line colour. By default this is set to the first colour in fan.col. Users might wish to change to highlight the median.

rlab

Vector of labels at the end (right) of corresponding percentiles or prediction intervals of the fan or boxfan. Must be in calculated in the probs argument. By default plotted alongside values provided to the ln

rpos

Position of right labels for the fan or boxfan. See text.

roffset

Offset of right labels for the fan or boxfan. See text.

rcex

Text size of right labels for the fan or boxfan. See text.

rcol

Colour of text for right labels for the fan or boxfan. See text.

llab

Can take either 1) a TRUE or FALSE value to plot label at the start (right) of the corresponding percentiles or prediction intervals given in rlab, default is FALSE or 2) a original vector of percentile

lpos

Position of left labels for the fan or boxfan. See text.

loffset

Offset of left labels for the fan or boxfan.By default takes the same value as roffset. See text.

lcex

Text size of left labels for the fan or boxfan. By default takes the same value as rex. See text.

lcol

Colour of text for left labels for the fan or boxfan. By default takes the same value as rcol. See text.

upplab

Prefix character string for upper labels to be used for the fan or boxfan when type="interval"

lowlab

Prefix character string for lower labels to be used for the fan or boxfan when type="interval"

medlab

Character string for median label.

n.spag

Number of simulations to plot in the spaghetti plot

space

Space between boxes in the boxfan plot

...

Additional arguments passed to boxplot.

Value

See details

Details

Visualise sequential distributions using a range of plotting styles. Sequential distribution data can be input as either simulations or pre-computed values over time (columns). For the later, the user should declare input data as percentiles by setting data.type = "values". Plots are added to existing graphic devices. Users can choose from four different styles. The fan and boxfan style plot distributions based on used-defined shading scheme, controlled by the fan.col argument. Additional lines and text are added to illustrate major contours on the probability distribution. Lines and labels can be suppressed by adding ln = NULL and rlab = NULL. Labels to the left of the fan can also be specified using the llab argument. Colours are by default taken from the heat.colors palette. Alternatives can be specified using fan.col (see the example below). The joining of a forecast fan to data is controlled be the anchor argument. The spaghetti style, plots random draws (when data.type = "simulations" is set) along the sequence of distributions. The number of draws is controlled by the n.spag argument. The transparency of the lines is controlled by alpha. The boxplot style, adds a box plot for simulated data at the appropriate location, according to the start and frquency arguments. Gaps between box plots are controlled by space argument. Additional arguments are passed to boxplot.

Examples

Run this code

##
## Basic Fan
##
# empty plot
plot(NULL, xlim = c(1, 945), ylim = range(th.mcmc)*0.85)

# add fan
fan(th.mcmc)

##
## 20 or so examples of fan charts and
## spaghetti plots based on the th.mcmc object
##
## Make sure you have zoo, tsbugs, RColorBrewer and 
## colorspace packages installed
##
demo("sv_fan", "fanplot")

##
## Fans for forecasted values
##
#create time series
net <- ts(ips$net, start=1975)

# fit model
library("forecast")
m <- auto.arima(net)

# simulate future values
mm <- matrix(NA, nrow=1000, ncol=5)
for(i in 1:1000)
  mm[i,] <- simulate(m, nsim=5)

# interval fan chart
plot(net, xlim=c(1975,2020), ylim=c(-100,300))
fan(mm, type="interval", start=2013)

# anchor fan chart
plot(net, xlim=c(1975,2020), ylim=c(-100,300))
fan(mm, type="interval", start=2013, 
    anchor=net[time(net)==2012])

##
## Box Plots
##
# sample every 21st date of theta_t
th.mcmc21 <- th.mcmc[, seq(1, 945, 21)]
plot(NULL, xlim = c(1, 945), ylim = range(th.mcmc21))
fan(th.mcmc21, style = "boxplot", frequency = 1/21)

# additional arguments for boxplot
plot(NULL, xlim = c(1, 945), ylim = range(th.mcmc21))
fan(th.mcmc21, style = "boxplot", frequency = 1/21, 
 outline = FALSE, col = "red", notch = TRUE)

##
## Fan Boxes
##
plot(NULL, xlim = c(1, 945), ylim = range(th.mcmc21))
fan(th.mcmc21, style = "boxfan", type = "interval", frequency = 1/21)

# more space between boxes
plot(NULL, xlim = c(1, 945), ylim = range(th.mcmc21))
fan(th.mcmc21, style = "boxfan", type = "interval", 
 frequency = 1/21, space = 10)

# overlay spaghetti
fan(th.mcmc21, style = "spaghetti", 
 frequency = 1/21, n.spag = 50, ln.col = "red", alpha=0.2)