Summarize inferences using lineplots

tile For Shiny

lineplot(tile)

R Documentation

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

... Any number of arguments given below. Must include exactly one horizontal dimension (x or top) and exactly one vertical dimension (y or right). All inputs should be identified by appropriate tags; i.e., use lineplot(x=myxvar, y=myyvar), not lineplot(myxvar,myyvar)

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

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

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

pch

addArrow

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

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
           )

[Package tile version 0.2 Index]

previous page start next page

Summarize inferences using lineplots

tile For Shiny