*! version 1.0.0 28aug2018
avciplot -- Added-variable plot with confidence intervals

Syntax

avciplot indepvar
[, options]

options

Plot
marker_options change look of markers (color,
size, etc.)

marker_label_options add marker labels;
change look or position

xlim(# [#]), ylim(# [#]) limit
the ranges of the x and y residuals displayed

generate(exvar eyvar) save the values of x and y residuals
in new variables

Regression line
rlopts(cline_options) affect rendition of
the regression line

nocoef turns off display of coefficent below graph

Confidence interval
noci turns off confidence interval

ciunder puts confidence intervals underneath scatter

level(level:#) specifies the confidence level

ciopts(fitarea_options:ci_options) affect rendition of
the confidence

ciplot(graph_twoway:plottype) how to plot
CIs; default is ciplot(rline);
a common alternative is ciplot(rarea)

Add plots
"addplot(addplot_option:plot)" add other plots to the
generated graph

Y axis, X axis, Titles, Legend, Overall
twoway_options any options other than by()
documented in [G-3] twoway_options

Description of avciplot

avciplot creates an added-variable plot (a.k.a. partial-regression
leverage plot, partial regression plot, or adjusted partial residual plot) after
regress. It differs from avplot
by adding confidence intervals around the regression line and various options.

indepvar is an independent (x) variable (a.k.a. predictor, carrier, or
covariate) that may or may not be included in the preceding regression. The user
would choose an indepvar not already in the regression to evaluate whether
it is worthwhile to include it.

avciplot shows the partial correlation between one indepvar and
the depvar controlling for all the other regressors in an multiple linear
regression.

Besides showing the relationship between the indepvar and the depvar
controlling for the other regressors, avciplot is useful for visually
identifying which outlier observations have a big effect on the estimated
coefficient.

avciplot calculates e(x|X),
the residuals from the regression of the indepvar (x)
on the other independent (X) variables, and e(y|X),
the residuals from the regression of the depvar (y)
on the other (X) variables. The graph shows e(x|X) plotted against
e(y|X), that is, the variation in x not correlated with X plotted against
the variation in y not correlated with X.

The fitted line shown in the graph is the least squares fit between the
residuals e(x|X) and e(y|X). The fitted line
has the same slope as estimated coefficient on the indepvar in
the preceding full regression.

By construction, the residuals e(x|X) and e(y|X) each have a mean
of zero, and the regression line (without a constant term) fitted between them passes
exactly through e(x|X)=0 and e(y|X)=0. At that point, the confidence
interval has zero width, giving it an unfamiliar shape. Note that this
also happens in a conventional regression at the point where all the independent
variables have a value of zero if there is no constant term.

Options for avciplot

Plot

marker_options
affect the rendition of markers drawn at the plotted points, including
their shape, size, color, and outline; see [G-3] marker_options.

marker_label_options
specify whether and how markers are to be labeled;
see [G-3] marker_label_options.

xlim(# [#]), ylim(# [#]) constrain
the range of the indepvar and depvar residuals displayed. If
only one number is specified, residuals with a value below that number will
not be displayed in the scatter plot. If two numbers are specified, residuals
below that first number and above the second number will not be displayed.

Excluding observations of the residual does not affect the slope of the regression
line in the graph. The purpose of these options is to avoid situations where
outlying observations cause a lot of extra white space in the graph, obscuring
display of the relationship between the variables. As usual, care should
be taken to make sure that the undisplayed observations are not important
to the estimated relationship.

generate(exvar eyvar) saves the values of the x and y residuals
in variables named by the user. The user must specify two variable names for
exvar and eyvar. These
residuals can be used for subsequent calculations or graphing commands.

Regression line

rlopts(cline_options) affects the rendition of the regression
(fitted) line. See [G-3] cline_options.

nocoef turns off display of the coefficent, standard error and t
statistic from the regression line below the graph.

Confidence interval

noci turns off display of the confidence interval on the graph.

ciunder confidence interval will be graphed underneath the scatter
plot (i.e. data scatter is graphed on top of confidence interval). This is
mainly useful when graphing a solid confidence interval with option
ciplot(rarea).

level(#) specifies the confidence level, in percent,
for confidence interval of the coefficients; see help level.

ciopts(line_options) affects how the upper and lower
confidence interval lines are rendered.
See [G-3] cline_options.
If you specify ciplot(), then rather than using
cline_options, you should specify whichever options are appropriate for
the plottype.

ciplot(plottype)
specifies how the confidence interval is to be plotted. The
default is ciplot(rline), meaning that the prediction will be
plotted by graph twoway rline.

A common alternative is ciplot(rarea), which will
substitute lines around the prediction for shading.
See [G-2] graph twoway for a list of plottype
choices. You may choose any plottypes that expect two y variables
and one x variable.

Add plots

addplot(plot) provides a way to add other plots to the generated graph.
See [G-3] addplot_option.

Y axis, X axis, Titles, Legend, Overall

twoway_options are any of the options documented in
[G-3] twoway_options, excluding by(). These include options
for titling the graph (see [G-3] title_options) and for saving
the graph to disk (see [G-3] saving_option).

Examples

Load the auto dataset and look at a graph of engine displacement versus
fuel efficiency (mpg):

. sysuse auto

. twoway lfitci mpg displacement || scatter mpg displacement, msize(vsmall) leg(off)

Though the correlation of displacement and mpg is clearly
negative, if we also include weight as a regressor in a multiple regression,
displacement has a positive and insignificant partial correlation.

. regress mpg displacement weight

How can we show this graphically? With an added-variable plot:

. avciplot displacement

The added-variable plot shows the correlation of the x variable,
displacement, conditional on all the other independent variables in the
regression, with the y variable,
mpg, also conditional on all the other regressors. That is, it shows the
the correlation of one x with y, netting out the influence of all the
other independent variables.

The added-variable plot shows a scatter of the values of the residuals e(x|X)
versus
e(y|X). The solid line is the regression fit of these values and
the dashed lines are the limits of the 95% confidence interval around the
regression fit. The slope of the regression fit in the added-variable plot
is equal to the coefficient on displacement in the preceding regression
which is also printed at the bottom of the graph.

Unlike avplot,
avciplot shows the confidence interval around
the linear regression line. We can see that the
partial correlation of displacement with mpg is not statistically
significant (at the 5% level) since the confidence interval includes zero.

avciplot can display the confidence interval as a solid pattern
(similar to the lfitci graphs) by using the option ciplot(rarea)
rather than the default of delineating the interval by two dashed lines. The
ciunder option causes the scatter plot to be superimposed on the confidence
interval rather than vice versa, so that data points within the interval are
still visible:

. avciplot displacement, ciplot(rarea) ciunder

Added-variable plots are a good diagnostic for finding outlier
observations which influence the partial correlation of a regressor of interest,
in this case displacement.

There is a clear outlier in the e(mpg|X)
vertical axis with a value of about 14. It is also clear that this outlier
has little affect on the slope of the regression line because it has a
value e(displacement|X) of about zero. Including this outlier makes the rest
of the graph smaller.

We can exclude the display of this observation with the
option ylim(-10 10) to magnify the rest of the graph. The lower limit of
ylim has no affect because there are no e(mpg|X) values below -10. The
ylim and xlim options are not available in
avplot so this could be a reason
to use avciplot even if you don't want to display a confidence interval.

Another difference between avplot and
avciplot is the ability to save the values of e(x|X) and e(y|X)
for later use with the generate option, perhaps to create a
more complicated graph after running the avciplot command.

The following command implements the ylim, generate and noci
(no confidence interval display) options:

. avciplot displacement, ylim(-10 10) noci generate(ey ex)

The new variables ex and ey, containing the residuals of the
x and y variables conditional on all the other regressors,
are added to the dataset in memory.

A simple scatter plot of a dummy variable like foreign versus mpg
only displays two values on the horizontal axis, making it difficult
to discern the relationship visually:

. twoway lfitci mpg foreign || scatter mpg foreign, leg(off) xl(0 1) yt(mpg) xt(foreign)

In contrast, the added-variable plot of foreign versus mpg graphs
the residual of the dummy variable conditional on the other x variables,
which is continuous even though the dummy variable itself only has two discrete
values.
avciplot can take an indepvar which has not yet been included
in the regression, making it a useful tool for exploring the influence of new
variables. To see the partial correlation of the new variable foreign
added to the existing regression, use

. avciplot foreign

This controls for all the existing variables in the last regression, which
in our example are displacement, weight and an intercept. The
added-variable plot of foreign could help the user decide whether
to add it as a new variable to the regression.

The companion command avciplots shows the added-variable plots of
all regressors in the preceding regression in a single graph. We include
an interaction term between weight and foreign in the regression
and then show all the partial correlations:

. regress mpg displacement weight foreign c.weight#i.foreign

. avciplots, title(All covariates)

avciplots provides a quick way of understanding the coefficient estimates
after any linear regression. The graph shows the strength and significance
of the partial correlations of all the independent variables, as well as
help to highlight outlier observations which affect each correlation.

The examples above show how avciplot and avciplots can be used
to present the relationship between independent and dependent variables graphically
when there are multiple covariates in a regression. The inclusion of confidence
intervals in the avciplot graphs makes it possible to see the statistical
significance of the estimated coefficients as well as their magnitude.

Stored results

avciplot stores the following in r():

Scalars

r(coef) the estimated coefficient of the added variable

r(se) the standard error of the estimated coefficient

Author

John Luke Gallup, Portland State University, USA
jlgallup@pdx.edu