Summarize inferences using lineplots

Summarize inferences using lineplots

Description

Initializes a line graphic with several optional features aimed at summarizing inferences from regression models: e.g., confidence intervals, perhaps created from simulations; clipping the plot to the convex hull to avoid unwarranted extrapolation; simple linear or robust fits to the data. If you simply want to draw a line on a tile plot, use linesTile instead.

This function does no plotting; it only creates a lineplot object to be drawn on one or more plots in a tiled arrangement of plots. To complete the drawing include the object as an input to tile. From tile, it is possible to set further options including plot and axis titles, axis ranges and labels, logged axes, and annotations to the plot.

Usage

 lineplot(...)  

Arguments

Details

Lineplots offer a plethora of data processing and formatting options. Confidence intervals (shown as shaded regions or dashed lines) can be calculated from simulations or posterior draws, or may be provided by the user. Alternatively, lineplot can add simple fit lines and CIs to the plotted data (e.g., a linear, robust, or loess fit). Optionally, only results inside the convex hull of the original data be drawn; alternatively, extrapolations outside this range can be flagged.

The graphical parameters for each element of the lineplot (including lines, shaded or dashed confidence intervals, and symbols or text marking points on the line) can be adjusted, often on a point-by-point basis.

Used in conjunction with tile, lineplot is a high-level plotting function, meaning that this combination will output finished plots. These plots cannot be easily modified after creation; rather, users can specify a wealth of graphics options within the initial calls to lineplot and tile, as documented below. For example, the graphical parameters for each element of the lineplot (including lines, shaded or dashed confidence intervals, and symbols or text marking points on the line) can be adjusted, often on a point-by-point basis. Users should carefully study the examples below and in tile before use.

A call to lineplot *must* provide an orthogonal pair of the following inputs:

x
co-ordinate vector of data to plot, attached to the x (bottom) axis. x may be plotted directly, or treated as simulation data to summarize (see parameter simulates below)
y
co-ordinate vector of data to plot, attached to the y (left) axis; may be simulation data
top
co-ordinate vector of data to plot, attached to the top axis; may be simulation data
right
co-ordinate vector of data to plot, attached to the right axis; may be simulation data

Users will often wish to provide the following inputs:

simulates
string, identifies one of the variables (x, y, top, or right) as simulation data (default = NULL, for no simulation data). If simulates is set, the other dimension of data will be treated as a matching list of scenarios over which to summarize the simulates. For example, to plot summaries of 1,000 simulates drawn from the conditional distribution of a response for each of 10 different values of a particular covariate, stack all 10,000 simulates in a single vector (e.g., right), then create a corresponding 10,000-vector listing the respective values of (say) x for each of these simulates. lineplot will then calculate confidence intervals each scenario, as requested in ci below
lower
vector, lower bounds; used when
upper
XXX
plot
scalar or vector, the plot(s) in which this trace will be drawn; defaulting to the first plot. Plots are numbered consecutively from the top left, row-by-row; e.g., in a 2x3 tiling, the first plot in the second row is plot number 4.

The next set of inputs are all optional, and control the major features of lineplot. It is usually best to use either ci or fit, but not both.

ci
list, parameters governing the appearance and calculation of confidence intervals from data in lower and upper or provided by the simulations defined in simulates:
levels
XXX
mark
XXX
fit
list, parameters governing the appearance and calculation of simple fits to the two plotted dimensions:

method
The type of fit to apply: linear (default) fits a bivariate linear regression; wls fits a weighted linear regression; robust fits a XXX; loess fits a loess smoother
ci
XXX
mark
XXX
col
XXX

need more

extrapolate
list, parameters governing the plotting of extrapolation outside the convex hull of the covariate data, using whatif in the package WhatIf:
formula
optional formula object, used to specify the estimated model; useful if the model contains interactions or functions of the covariates given in data below
data
matrix or dataframe, the actual values of all covariates used to estimate the model (omit the constant and response variable)
cfact
matrix or dataframe, the counterfactual values of all the covariates (omit the constant and response variable), one row for each scenario. The order of colums must match data, and the order of rows must match the order of the scenarios. If scenarios are calculated from simulates, then the rows must be listed from the scenario with the smallest factor level to the highest
omit.extrapolated
If TRUE (default), then the plotted trace and CIs are clipped to the convex hull; if FALSE, then extrapolation outside the convex hull is printed in a lighter color or with dashed/dotted lines

The following graphics parameters mimic the inputs to grid::gpar. Starred (*) parameters accept vector as well as scalar input, so that different parameter values can be applied to different elements of the plot:

fill
*Color for filling polygons; default is transparent
col
*Color for lines, symbols, and text; default is black
lty
*Line type; default is solid
lwd
*Line width; default is 1
cex
*Multiplier applied to fontsize; default is 1
lex
*1
fontsize
Size of the text in points; default is 12
lineheight
Height of a line as a multple of the size of text; default is 1.2
font
Font face (alias for fontface); default is 1
fontfamily
The font family; default is blank!
fontface
The font face (\code{bold}, \code{italic}, etc.); default is \code{plain}
alpha
Alpha channel for transparency; default is 0.8
lineend
"round"
linejoin
"round"
linemitre
10

These final graphical parameters are specific to tile-based plots, and are available for advanced users to tweak the appearance of traces. Starred (*) parameters accept vector as well as scalar input, so that different parameter values can be applied to different elements of the plot:

markers
*
labels
*
labelxoffset
*
labelyoffset
*
size
*1
pch
*1
addArrow
30
lengthArrow
unit(0.25, "inches")
endsArrow
XXX
typeArrow
XXX
just
XXX
hjust
XXX
vjust
XXX
rot
XXX
check.overlap
XXX
clip
XXX
lighten
XXX
layer
Graphical elements with lower layer will be drawn later in the plotting process, and hence appear on top of elements with higher layer. By default, layer is 10, though polygons in this trace will be plotted at layer + X, and text labels and markers at layer - X.

Value

A lineplot object, used only as an input to tile

Author(s)

Christopher Adolph <[email protected]>

See Also

tile, linesTile

Examples

# Example 1:  Linear regression on Swiss fertility;
# Tiled lineplots of counterfactual scenarios calculated by
# predict() and clipped to convex hull
data(swiss)

# Estimate model
lm.result <- lm(Fertility ~ . , data = swiss)

# Create counterfactual scenarios
cfactbaseline <- apply(swiss[,2:6],2,mean)

cfact1 <- cfact2 <- cfact3 <- cfact4 <- cfact5 <-
    data.frame(matrix(cfactbaseline,nrow=101,ncol=5,byrow=TRUE,
           dimnames=list(NULL,names(cfactbaseline))))

cfact1[,1] <- cfact2[,2] <- cfact3[,3] <- cfact4[,4] <- cfact5[,5] <-
    seq(0,100)

lm.pred1 <- predict(lm.result,newdata=cfact1,interval="confidence",level=0.95)
lm.pred2 <- predict(lm.result,newdata=cfact2,interval="confidence",level=0.95)
lm.pred3 <- predict(lm.result,newdata=cfact3,interval="confidence",level=0.95)
lm.pred4 <- predict(lm.result,newdata=cfact4,interval="confidence",level=0.95)
lm.pred5 <- predict(lm.result,newdata=cfact5,interval="confidence",level=0.95)

# Create traces of each set of counterfactuals
trace1 <- lineplot(x=cfact1[,1],
                   y=lm.pred1[,1],
                   lower=lm.pred1[,2],
                   upper=lm.pred1[,3],
                   ci=list(mark="dashed"),
                   extrapolate=list(data=swiss[,2:6],cfact=cfact1,
                                    omit.extrapolated=TRUE),
                   col="blue",
                   plot=1
                   )

trace2 <- lineplot(x=cfact2[,2],
                   y=lm.pred2[,1],
                   lower=lm.pred2[,2],
                   upper=lm.pred2[,3],
                   ci=list(mark="dashed"),
                   extrapolate=list(data=swiss[,2:6],cfact=cfact2,
                                    omit.extrapolated=TRUE),
                   col="red",
                   plot=2
                   )

trace3 <- lineplot(x=cfact3[,3],
                   y=lm.pred3[,1],
                   lower=lm.pred3[,2],
                   upper=lm.pred3[,3],
                   ci=list(mark="dashed"),
                   extrapolate=list(data=swiss[,2:6],cfact=cfact3,
                                    omit.extrapolated=TRUE),
                   col="green",
                   plot=3
                   )

trace4 <- lineplot(x=cfact4[,4],
                   y=lm.pred4[,1],
                   lower=lm.pred4[,2],
                   upper=lm.pred4[,3],
                   ci=list(mark="dashed"),
                   extrapolate=list(data=swiss[,2:6],cfact=cfact4,
                                    omit.extrapolated=TRUE),
                   col="brown",
                   plot=4
                   )

trace5 <- lineplot(x=cfact5[,5],
                   y=lm.pred5[,1],
                   lower=lm.pred5[,2],
                   upper=lm.pred5[,3],
                   ci=list(mark="dashed"),
                   extrapolate=list(data=swiss[,2:6],cfact=cfact5,
                                    omit.extrapolated=TRUE),
                   col="violet",
                   plot=5
                   )

at.x <- c(0,20,40,60,80,100)
at.y <- c(50,60,70,80,90,100)

# Plot traces using tile
tc <- tile(trace1,
           trace2,
           trace3,
           trace4,
           trace5,
           RxC = c(2,3),
           limits = c(0,100,50,100),
           output = list(wide=7.5,outfile="lineplotExample1",type="pdf"),
           xaxis = list(at=at.x),
           yaxis = list(at=at.y),
           xaxistitle = list(type="all",labels=c(names(cfactbaseline))),
           yaxistitle = list(type="all",labels=c("Fertility")),
           plottitle = list(type="all",labels=c("Test")),
           maintitle = list(labels=c("Linear Model of Fertility")),
           gridlines = list(type="xy"),
           frame = TRUE
           )

# Example 2.1:  Multinomial Logistic Regression of alligator food;
# Tiled lineplots using *manually simulated counterfactuals*, with
# extrapolation outside the convex hull flagged
#
# See Ex. 2.2 for an automated way to handle simulations 

data(gator)
require(MASS)
require(nnet)

# Estimate MNL using the nnet library
mlogit.result <- multinom(food ~ size + female, Hess=TRUE)
pe <- mlogit.result$wts[c(6,7,8,10,11,12)]
                                      # point estimates
vc <- solve(mlogit.result$Hess)       # var-cov matrix

# Simulate counterfactual results, varying size and sex
sims <- 10000
simbetas <- mvrnorm(sims,pe,vc)       # draw parameters, using MASS::mvrnorm
sizerange <- seq(1,4,by=0.1)          # range of counterfactual sizes
femalerange <- c(0,1)                 # range of counterfactual sexes
simycat1 <- simycat2 <- simycat3 <- cfactsize <- cfactfemale <- NULL
for (isex in 1:length(femalerange)) { # loop over sex scenarios
    for (isize in 1:length(sizerange)) { # loop over size scenarios

        # Set up a hypothetical X vector for this scenario
        hypx <- rbind(1, sizerange[isize], femalerange[isex])

        # Calculate simulated MNL denominators for this scenario
        simdenom <- (1 + exp(simbetas[,1:3]%*%hypx) + exp(simbetas[,4:6]%*%hypx))

        # Add simulated probabilities for each category to storage vectors
        simycat1 <- c( simycat1, 1/simdenom )
        simycat2 <- c( simycat2, exp(simbetas[,1:3]%*%hypx)/simdenom )        
        simycat3 <- c( simycat3, exp(simbetas[,4:6]%*%hypx)/simdenom )

        # Save hypothetical X's to storage vectors:
        # must match simulated probabilities element for element
        cfactsize <- c(cfactsize, rep(sizerange[isize],sims) )
        cfactfemale <- c(cfactfemale, rep(femalerange[isex],sims) )
    }
}

# Create one trace for each predicted category of the response, and each sex
trace1 <- lineplot(x=cfactsize[cfactfemale==0],
                   y=simycat1[cfactfemale==0],
                   simulates="y",
                   ci=list(mark="shaded",levels=0.67),
                   extrapolate=list(data=cbind(size,female),
                                    cfact=cbind(sizerange,rep(0,length(sizerange))),
                                    omit.extrapolated=FALSE),
                   col="blue",
                   plot=1
                   )

trace2 <- lineplot(x=cfactsize[cfactfemale==0],
                   y=simycat2[cfactfemale==0],
                   simulates="y",
                   ci=list(mark="shaded",levels=0.67),
                   extrapolate=list(data=cbind(size,female),
                                    cfact=cbind(sizerange,rep(0,length(sizerange))),
                                    omit.extrapolated=FALSE),
                   col="red",
                   plot=1
                   )

trace3 <- lineplot(x=cfactsize[cfactfemale==0],
                   y=simycat3[cfactfemale==0],
                   simulates="y",
                   ci=list(mark="shaded",levels=0.67),
                   extrapolate=list(data=cbind(size,female),
                                    cfact=cbind(sizerange,rep(0,length(sizerange))),
                                    omit.extrapolated=FALSE),
                   col="green",
                   plot=1
                   )

trace4 <- lineplot(x=cfactsize[cfactfemale==1],
                   y=simycat1[cfactfemale==1],
                   simulates="y",
                   ci=list(mark="shaded",levels=0.67),
                   extrapolate=list(data=cbind(size,female),
                                    cfact=cbind(sizerange,rep(1,length(sizerange))),
                                    omit.extrapolated=FALSE),
                   col="blue",
                   plot=2
                   )

trace5 <- lineplot(x=cfactsize[cfactfemale==1],
                   y=simycat2[cfactfemale==1],
                   simulates="y",
                   ci=list(mark="shaded",levels=0.67),
                   extrapolate=list(data=cbind(size,female),
                                    cfact=cbind(sizerange,rep(1,length(sizerange))),
                                    omit.extrapolated=FALSE),
                   col="red",
                   plot=2
                   )

trace6 <- lineplot(x=cfactsize[cfactfemale==1],
                   y=simycat3[cfactfemale==1],
                   simulates="y",
                   ci=list(mark="shaded",levels=0.67),
                   extrapolate=list(data=cbind(size,female),
                                    cfact=cbind(sizerange,rep(1,length(sizerange))),
                                    omit.extrapolated=FALSE),
                   col="green",
                   plot=2
                   )

at.x <- c(1,2,3,4)
at.y <- c(0,0.2,0.4,0.6,0.8,1)

# Plot traces using tile
tc <- tile(trace1,
           trace2,
           trace3,
           trace4,
           trace5,
           trace6,
           RxC = c(1,2),
           limits = c(1,4,0,1),
           output = list(wide=6.5,outfile="lineplotExample2",type="pdf"),
           xaxis = list(at=at.x),
           yaxis = list(at=at.y),
           xaxistitle = list(type="all",labels=c("Size of alligator","Size of alligator")),
           yaxistitle = list(type="first",labels="Pr(Food preference)"),
           undertitle = list(labels=c("Male","Female")),
           maintitle = list(labels="Food choice by alligator size"),
           gridlines = list(type="xy"),
           frame=TRUE
           )


# Example 2.2:  Multinomial Logistic Regression of alligator food;
# Tiled lineplots using *preprocessed simulations*, with
# extrapolation outside the convex hull flagged
#
# (Alternative method for constructing Ex 2.1; output is identical)

data(gator)
require(MASS)
require(nnet)
require(simcf)

# Estimate MNL using the nnet library
mlogit.result <- multinom(food ~ size + female, Hess=TRUE)
pe <- mlogit.result$wts[c(6,7,8,10,11,12)]
                                      # point estimates
vc <- solve(mlogit.result$Hess)       # var-cov matrix

# Alternative code for simulations above which calculates CIs to pass on
# to lineplot & tile (also could try Zelig)
sims <- 10000
simbetas <- mvrnorm(sims,pe,vc)       # draw parameters, using MASS::mvrnorm
simb <- array(NA, dim = c(sims,3,2))  # re-arrange simulates to array format
simb[,,1] <- simbetas[,1:3]           #   for MNL simulation
simb[,,2] <- simbetas[,4:6]
sizerange <- seq(1,4,by=0.1)          # range of counterfactual sizes
femalerange <- c(0,1)                 # range of counterfactual sexes

# Create full factorial set of counterfactuals
xhyp <- setfactorial(size = sizerange, female = femalerange)
                                      
# Simulate expected probabilities
mlogit.qoi1 <- mlogitsimev(xhyp,simb,ci=0.67)

# Create one trace for each predicted category of the response, and each sex
trace1 <- lineplot(x=xhyp$size[xhyp$female==0],
                   y=mlogit.qoi1$pe[xhyp$female==0,1],
                   lower=mlogit.qoi1$lower[xhyp$female==0,,1],
                   upper=mlogit.qoi1$upper[xhyp$female==0,,1],
                   ci=list(mark="shaded"),
                   extrapolate=list(data=cbind(size,female),
                                    cfact=xhyp[xhyp$female==0,],
                                    omit.extrapolated=FALSE),
                   col="blue",
                   plot=1
                   )

trace2 <- lineplot(x=xhyp$size[xhyp$female==0],
                   y=mlogit.qoi1$pe[xhyp$female==0,2],
                   lower=mlogit.qoi1$lower[xhyp$female==0,,2],
                   upper=mlogit.qoi1$upper[xhyp$female==0,,2],
                   ci=list(mark="shaded"),
                   extrapolate=list(data=cbind(size,female),
                                    cfact=xhyp[xhyp$female==0,],
                                    omit.extrapolated=FALSE),
                   col="red",
                   plot=1
                   )

trace3 <- lineplot(x=xhyp$size[xhyp$female==0],
                   y=mlogit.qoi1$pe[xhyp$female==0,3],
                   lower=mlogit.qoi1$lower[xhyp$female==0,,3],
                   upper=mlogit.qoi1$upper[xhyp$female==0,,3],
                   ci=list(mark="shaded"),
                   extrapolate=list(data=cbind(size,female),
                                    cfact=xhyp[xhyp$female==0,],
                                    omit.extrapolated=FALSE),
                   col="green",
                   plot=1
                   )

trace4 <- lineplot(x=xhyp$size[xhyp$female==1],
                   y=mlogit.qoi1$pe[xhyp$female==1,1],
                   lower=mlogit.qoi1$lower[xhyp$female==1,,1],
                   upper=mlogit.qoi1$upper[xhyp$female==1,,1],
                   ci=list(mark="shaded"),
                   extrapolate=list(data=cbind(size,female),
                                    cfact=xhyp[xhyp$female==1,],
                                    omit.extrapolated=FALSE),
                   col="blue",
                   plot=2
                   )

trace5 <- lineplot(x=xhyp$size[xhyp$female==1],
                   y=mlogit.qoi1$pe[xhyp$female==1,2],
                   lower=mlogit.qoi1$lower[xhyp$female==1,,2],
                   upper=mlogit.qoi1$upper[xhyp$female==1,,2],
                   ci=list(mark="shaded"),
                   extrapolate=list(data=cbind(size,female),
                                    cfact=xhyp[xhyp$female==1,],
                                    omit.extrapolated=FALSE),
                   col="red",
                   plot=2
                   )

trace6 <- lineplot(x=xhyp$size[xhyp$female==1],
                   y=mlogit.qoi1$pe[xhyp$female==1,3],
                   lower=mlogit.qoi1$lower[xhyp$female==1,,3],
                   upper=mlogit.qoi1$upper[xhyp$female==1,,3],
                   ci=list(mark="shaded"),
                   extrapolate=list(data=cbind(size,female),
                                    cfact=xhyp[xhyp$female==1,],
                                    omit.extrapolated=FALSE),
                   col="green",
                   plot=2
                   )

at.x <- c(1,2,3,4)
at.y <- c(0,0.2,0.4,0.6,0.8,1)

# Plot traces using tile
tc <- tile(trace1,
           trace2,
           trace3,
           trace4,
           trace5,
           trace6,
           RxC = c(1,2),
           limits = c(1,4,0,1),
           output = list(wide=6.5,outfile="lineplotExample2",type="pdf"),
           xaxis = list(at=at.x),
           yaxis = list(at=at.y),
           xaxistitle = list(type="all",labels=c("Size of alligator","Size of alligator")),
           yaxistitle = list(type="first",labels="Pr(Food preference)"),
           undertitle = list(labels=c("Male","Female")),
           maintitle = list(labels="Food choice by alligator size"),
           gridlines = list(type="xy"),
           frame=TRUE
           )