*! version 1.1.0 E Brini, ST Borgen, NT Borgen 02july2024
help pheatplot

Title

pheatplot -- Visualizing statistical significance across coefficients

Syntax

pheatplot varname,
[
threshold(#)
interaction(varname)
frame(newframename)
pname(name [, replace])
bname(name [, replace])
heatoptsp(options)
heatoptsb(options)
pvalues(off)
savetable(filename [, save_options])
savegraph(filename.suffix [, replace])
differences
hexplot
mono]

options

threshold(#) sets the critical threshold value; default is threshold(.10).

interaction(varname) specifies the interaction variable, if
any.

frame(newframename) specifies the name of the frame that holds
coefficients, standard errors, p-values, and confidence intervals.

pname(name) provides a name for the heat plot of the p-values.

bname(name) provides a name for the heat plot of the coefficients.

heatoptsp(options) passes options along to the heat plot
of the p-values.

heatoptsb(options) passes options along to the heat plot
of the coefficients.

pvalues(off) removes the numeric display of p-values from heat plot of p-values.

savetable(filename) saves a table holding results.

savegraph(filename.suffix) exports to a file the heat plot of p-values.

differences requests that heat plot of differences between coefficients is displayed.

hexplot requests that hexagon plots are used instead of heat plots.

mono requests that heat plots are shown in grayscale color palette.

Description

pheatplot is a postestimation command that calculates pairwise comparisons
of estimates using lincom and provides a heat plot by color to visualize the
p-values of the difference between the categories of a factor variable or
their interaction effects. It can be used after all single-equation estimation
commands that allows for factor variable notation and
the use of the postestimation command lincom. The categorical variable that will be compared is
placed after the command name, followed by options. In the previous regression
model, the categorical variable must be included using factor variable
notation (fvvarlist).

See Brini, Borgen, and Borgen (2023)
for descriptions and examples of the pheatplot command.

Options

threshold sets the critical threshold value, with the color gradient differing
below and above this threshold. This allows the user to identify and communicate
whether differences are statistically significant at specific levels, while at
the same time avoiding strict cutoff values. The default is threshold(.10).

interaction(varname) specifies the interaction variable, if
any. Interactions must be included using factor-variable operators
(fvvarlist).

frame(newframename) specifies the name of the frame that holds
coefficients, standard errors, p-values, and confidence intervals.
Specifying {\tt frame()} will return a frame after the program ends.

pname(name) provides a name for the heat plot of the
p-values.

bname(name) provides a name for the heat plot of the
coefficients.

heatoptsp(options) affects rendition of the p-value plot. Options specified
here is passed along to the heat plot
of the p-values. See heatplot options for
list of available options.

heatoptsb(options) affects the rendition of the plot of differences
between coefficients. Options specified here are passed along to the heat plot
of the differences between coefficients. See heatplot options for list of available options. Use of heatoptsb() requires that the option differences is specified

pvalues(off) removes the numeric display of p-values in the heat plot
of the p-values. This option should be used in combination with
heatoptsp(values(options)) if the user wants to customize the display of p-values.

savetable(filename) saves a table in .docx format which includes the difference between
coefficients and the standard errors and p-values from testing whether there
are statistically significant differences between the coefficients. The save_options from putdocx can
be used to replace an exisiting file or append the active file to the end
of a exisiting file. See putdocx begin save_options for list of available options.

savegraph(filename.suffix [, replace]) exports to file the heat plot of p-values. The suffix could be (with output format in paranthesis)
ps (PostScript), eps (Encapsulated PostScript), svg (Scalable Vector Graphics),
emf (Enhanced Metafile), pdf (Portable Document Format), png (Portable Network Graphics),
tif (Tagged Image File Format), gif (Graphics Interchange Format), or jpg (Joint Photographic Experts Group).

differences requests that heatplot of differences between coefficients is displayed. The
default is that the plot of differences between coefficients is not shown.

hexplot requests that hexagon plots are used instead of heat plots. The default
is that the user-contributed command heatplot is used rather than hexplot.

mono requests that the heat plots are shown in grayscale color palette.

Examples

Setup.

. sysuse nlsw88, clear

. drop if inlist(occupation,9,10,12)

Test differences in occupation indicator variables.

. regress wage i.occupation

. pheatplot occupation

Test difference in union effects by occupation.

. regress wage i.occupation##i.union

. pheatplot occupation, interaction(i.union)

Test difference in age effects by occupation.

. regress wage i.occupation##c.age

. pheatplot occupation, interaction(c.age)

Test differences in occupation indicator variables after a logistic regression model.

. logit union i.occupation

. pheatplot occupation

Test differences in occupation indicator variables after margins.

. logit union i.occupation

. margins, dydx(occupation) post

. pheatplot occupation

Changing the threshold cutoff value.

. regress wage i.occupation

. pheatplot occupation, threshold(.05)

Requesting that the graph is shown using a color palette.

. regress wage i.occupation

. pheatplot occupation, color

Use alternative color palettes.

. regress wage i.occupation

. pheatplot occupation, heatoptsp(color(Blues))

Customizing the look of the graph using heatoptsp().

. use http://www.stata-press.com/data/mlmus2/gcse, clear

. regress gcse i.school

. pheatplot school, pvalues(off) heatoptsp(scale(0.7) ramp(scale(.7) ///

legend(symysize(.5) symxsize(.5)) space(12) right ///

label(#10) subtitle(P-value) format(%9.2f)) ylabel(2(3)65, nogrid)	///

xlabel(1(3)64, nogrid))

Stored results

pheatplot stores the following in r():

Matrices

r(pvalues) matrix holding p-values

r(differences) matrix holding differences between coefficients

Version requirements

The pheatplot command requires Stata 17.0 or later.

Package dependencies

pheatplot uses heatplot to visualize the statistical significance
of differencs between coefficients. To install this command, type:

. ssc install heatplot

Reference

Brini, Elisa, Solveig T. Borgen, and Nicolai T. Borgen (2023).
Avoiding the eyeballing fallacy: Visualizing statistical differences between
estimates using the pheatplot command. SocArXiv.
doi:10.31235/osf.io/fghcd

Jann, Ben (2019).
HEATPLOT: Stata module to create heat plots and hexagon plots. Statistical
Software Components S458598, Boston College Department of Economics.

Jann, Ben (2023).
Color palettes for Stata graphics: an update. The Stata Journal 23(2): 336–385.

Authors

Elisa Brini, University of Florence

elisa.brini@unifi.it

Solveig T. Borgen, University of Oslo

s.t.borgen@sosgeo.uio.no

Nicolai T. Borgen, University of Oslo

n.t.borgen@isp.uio.no