*! version 1.3.0 04jan2018
help marginscontplot2 Patrick Royston

Title

marginscontplot2 -- Graph margins for continuous predictors

Syntax

{marginscontplot2|mcp2}
xvar1 [(xvar1a [xvar1b ...])]
[xvar2 [(xvar2a [xvar2b ...])]
[, options advanced_plot_options
]

options

at(at_list) fix values of model covariates

at1(at1_list) define plotting positions for xvar1

at2(at2_list) define plotting positions for xvar2

ci display pointwise confidence interval(s)

margopts(string) options for margins

name(name [, replace]) store graph to memory

nograph suppress graph

prefix(string) prefix names of created variables (margins and confidence intervals)
with string [relevant only with saving()]

saving(filename [, replace]) save margins and confidence intervals to file

showmarginscmd show the margins command as issued

var1(# | var1_spec) specifies transformed values of xvar1 for plotting

var2(# | var2_spec) specifies transformed values of xvar2 for plotting

advanced_plot_options

areaopts(area_options) options of graph twoway area for plots with ci

combopts(combine_options) options of graph combine for plots with ci in more than one subgroup

lineopts(line_options) options of graph twoway line to modify appearance of plotted line(s)

You must have run an estimation command before using marginscontplot2.

Description

marginscontplot2 provides a graph of the marginal effect of a continuous
predictor on the response variable in the most recently fitted
regression model. See Royston (2013) for details and examples; the paper is
available at http://www.stata-journal.com/article.html?article=gr0056.

When only xvar1 is provided, the plot of marginal effects
is univariate at values of xvar1 specified by the at1() or
var1() options. When both xvar1 and xvar2 are provided,
the plot of marginal effects is against values of xvar1 specified
by the at1() or var1() options for fixed values of xvar2
specified by the at2() or var2() options. A line is plotted
for each specified value of xvar2.

marginscontplot2 has the distinctive ability to plot marginal effects on
the original scale of xvar1 or xvar2, even when the model includes
transformed values of xvar1 or xvar2 but does not include xvar1
or xvar2 themselves. Such a situation arises in models involving simple
transformations such as logs and more complicated transformations such as
fractional polynomials or splines, for example, where non-linear
relationships with continuous predictors are to be approximated.
Transformed covariates are included in the model to achieve this.

mcp2 is a synonym for marginscontplot2 for those who prefer to
type less.

Options

at(at_list) fixes values of model covariates other than xvar1 and
xvar2. at_list has syntax varname1 = #
[varname2 = # ...]. By default, predictions for such
covariates are made at the observed values and averaged across observations.

at1([%]at1_list) defines the plotting positions
for xvar1 through the numlist at1_list. If the prefix %
is included, at1_list is interpreted as percentiles of the distribution
of xvar1. If at1() is omitted, all the observed values of xvar1
are used if feasible. Note that xvar1 is always treated as the primary
plotting variable on the X-dimension.

An important technical issue is that if a transformation of xvar1 is
applied such that the first transformed variable is in reverse order with
respect to the values of xvar1, the plotting values supplied in
at1_list() must also be reversed. Reversal is not necessary if the
first FP-transformed variable preserves the order of xvar1. Any FP
transformation whose first power is negative, e.g. FP2(-2, -2), reverses
the order.

at2([%]at2_list) defines the plotting positions
for xvar2 through the numlist at2_list. If the prefix %
is included, at2_list is interpreted as percentiles of the distribution
of xvar2. If at2() is omitted, the observed values of xvar2
are used if feasible. Note that xvar2 is always treated as the secondary,
'by-variable' for plotting purposes.

See also the technical issue concerned with order-reversing transformations
described under at1(). It also applies to xvar2 and at2_list.

ci displays pointwise confidence interval(s) for the fitted values
on the margins plot. For legibility, if more than one line is specified,
each line is plotted on a separate graph.

Note that when >1 line is specified, the individual graphs are
by default scaled differently in each subgroup defined by xvar2.
The axis values depend on the ranges of x and y values in each subgroup.
To produce the plot, marginscontplot2 uses the Stata command
graph combine. You can force equal y-axis and/or x-axis
scaling across the graphs by using one of the options combopts(ycommon),
combopts(xcommon) or combopts(ycommon xcommon). See also
Advanced plot options.

margopts(string) supplies options to the margins command.
The option most likely to be needed is predict(xb), which means
that predicted values and hence margins are on the scale of the linear
predictor. For example, in a logistic regression model, the default
predictions are of the event probabilities. Specifying
margopts(predict(xb)) gives margins on the scale of the linear
predictor, i.e. the predicted log odds of an event.

Note that the margins are calculated with the default setting,
asobserved, for margins. See margins for further
information.

name(name [, replace]) stores the graph
of marginal effects in memory. See name option for details.

nograph suppresses the graph of marginal effects.

prefix(string) prefixes the names of created variables containing
margins and confidence intervals with string. Applies only with the
saving() option, otherwise ignored. May be useful if you are saving
results for different models in order to compare margins graphically.

saving(filename [, replace]) saves the calculated
margins and their confidence intervals to a file (filename.dta).
This can be useful for fine-tuning the plot or tabulating the results.

showmarginscmd displays the margins command that
marginscontplot2 creates and issues to Stata, to do the
calculations necessary for constructing the plot. This information
can be helpful in fine-tuning the command or identifying problems.

var1(# | var1_spec) specifies plotting values of xvar1.
If var1(#) is specified then # equally spaced values of
xvar1 are used as plotting positions, encompassing the observed range
of xvar1. Alternatively, var1_spec may be used
to specify transformed plotting values of xvar1. The syntax of
var1_spec is var1 [(var1a [var1b ... ])].
var1 is a variable holding user-specified plotting values of xvar1.
var1a is a variable holding transformed values of var1, and
similarly for var1b ... if required.

See also Remarks.

var2(# | var2_spec) specifies plotting values of xvar2.
If var2(#) is specified then # equally spaced values of
xvar2 are used as plotting positions, encompassing the observed range
of xvar2. Alternatively, var2_spec may be used
to specify transformed plotting values of xvar2. The syntax of
var2_spec is var2 [(var2a [var2b ... ])].
var2 is a variable holding user-specified plotting values of xvar2.
var2a is a variable holding transformed values of var2, and
similarly for var2b ... if required.

See also Remarks.

Advanced plot options

Remark: marginscontplot2 produces acceptable graphs with its default graph
option settings. This section is intended for people who wish to 'tweak'
the appearance of their graphs in a more detailed way.

Note that options areaopts() and lineopts(), described below,
may include general graph twoway options, for example title()
to change the graph title.

areaopts(area_options) supplies options of graph twoway area for
modifying the appearance of plots made including the ci option.
For example, suppose xvar1 = age is a continuous covariate and
xvar2 = race is a categoric variable with three levels. Imagine
we have fit the linear regression model

. regress map age i.race

to a continuous outcome variable called map. The simplest command to
plot fitted values of map for age by race, with confidence
intervals, is

. marginscontplot2 age race, ci

which would produce a combination of separate graphs depicting fitted values of
age together with a pointwise 95% confidence band in each subgroup
of race. Suppose we wish to change the default color of the two
boundary lines of the confidence intervals to cyan and make the lines dashed
rather than continuous. We can do this by including area_options
lcolor(cyan) and lpattern(-):

. marginscontplot2 age race, ci areaopts(lcolor(cyan) lpattern(-))

If we also wanted the central lines (i.e. the fitted values) to be colored
red, we could add in lineopts() the graph twoway line option
lcolor(red):

. marginscontplot2 age race, ci areaopts(lcolor(cyan) lpattern(-)) lineopts(lcolor(red))

Note that we use the lcolor() option twice to pinpoint different
components of the graph. Now, marginscontplot2 uses
graph combine to produce the final graph from the individual graphs
for the different levels of race. As for any graph created by
marginscontplot2, to store the final graph in memory, we could include
the name() option:

. marginscontplot2 age race, ci areaopts(lcolor(cyan) lpattern(-)) lineopts(lcolor(red)) name(my_graph)

combopts(combine_options) only affects composite graphs as
described under areaopts(area_options). combine_options are
options of graph combine. The most poplar such options are likely
to be saving(), ycommon, xcommon, and some of the
title_options. For example,

. marginscontplot2 age race, ci combopts(title(My graph) l1title(map) b2title(Age) saving(my_graph, replace))

lineopts(line_options) are options of graph twoway line which
modify the appearance of plotted line(s) of fitted values. See line options
for details of what is available. Most popular are likely to be lpattern(),
lwidth() and lcolor(). For example to change the fitted lines for the
three races in the example above to different line patterns in different colors,
we could enter

. marginscontplot2 age race, lineopts(lcolor(red cyan brown) lpattern(l - --))

Remarks

The version of var1() with var1_spec is appropriate for use after
any covariate transformation is used in the model and you want a plot with the
original (untransformed) covariate on the horizontal axis. This includes simple
transformations such as logs and more complicated situations. For example the
model may involve a fractional polynomial model in xvar1 using
fracpoly, mfp or fp. Alternatively, fractional polynomial
transformations of xvar1 may be calculated using fracgen or
fp generate, and the required model fitted to the transformed variables
before applying marginscontplot2. The same facility is available for the
var2() option. It works in the same way but with xvar2 instead of
xvar1.

marginscontplot2 has been designed to handle quite high-dimensional cases,
i.e. where many margins must be estimated. Be aware, however, that the number of
margins is limited by the maximum matrix size; see matsize. This can
be increased if necessary by using the set matsize # command.
marginscontplot2 tells you the smallest value of # needed to
accommodate the case in question.

Examples

Basic examples

sysuse auto, clear

regress mpg i.foreign weight

marginscontplot2 weight, name(my_graph)

marginscontplot2 weight, at1(2000(100)4500) ci

marginscontplot2 weight foreign, var1(20) at2(0 1)

marginscontplot2 weight foreign, var1(20) at2(0 1) ci combopts(ycommon imargin(small))

Example using a log-transformed covariate

gen logwt = log(weight)

regress mpg i.foreign c.logwt i.foreign#c.logwt

quietly summarize weight

range w1 r(min) r(max) 20

generate logw1 = log(w1)

marginscontplot2 weight (logwt), var1(w1 (logw1)) ci

Example using a fractional polynomial model

fracpoly: regress mpg weight foreign

marginscontplot2 weight (Iweig__1 Iweig__2) foreign, var1(20) ci

Example using the new fp fractional polynomial command

fp <weight>: regress mpg <weight> turn i.rep78

marginscontplot2 weight (weight_1 weight_2) rep78, at1(2000(500)5000)

marginscontplot2 weight (weight_1 weight_2) rep78, var1(20) ci

Do-it-yourself fractional polynomial example

fracgen weight -2 -2

quietly summarize weight

range w1 r(min) r(max) 20

generate w1a = (w1/1000)^-2

generate w1b = (w1/1000)^-2 * ln(w1/1000)

regress mpg i.foreign

marginscontplot2 weight (weight_1 weight_2), var1(w1 (w1a w1b)) ci

marginscontplot2 weight (weight_1 weight_2) foreign, var1(w1 (w1a w1b))

Simplified version of the above

fracgen w1 -2 -2

marginscontplot2 weight (weight_1 weight_2) foreign, var1(w1 (w1_1 w1_2))

Author

Patrick Royston

MRC Clinical Trials Unit at UCL

London, UK

j.royston@ucl.ac.uk

References

Royston, P. 2013. marginscontplot2: Plotting the marginal effects of continuous predictors.
Stata Journal, 13(3): 510-527.

Also see

Manual: [R] margins, [R] marginsplot, [R] fracpoly, [R] mfp

Online: margins, marginsplot, mfp, fracpoly, fp