help robbox

Title

robbox -- Generalized box plots

Syntax

Estimation:

robbox varlist [if] [in] [weight]
[,
options
]

Replay graph:

robbox [, graph_options ]

Replay table:

robbox, table

Generate variable(s) flagging outside values:

robbox, flag[(prefix or namelist)] [ replace ]

Generate variables containing results:

robbox, generate[(prefix or namelist)] [ nolabel replace ]

Store outside values in matrix e(outsides):

robbox, postoutsides

options Description

Main
standard standard box plot

adjusted skewness-adjusted box plot

general generalized box plot; the default

alpha(#) outside value percentage; not allowed with adjusted

bp(#) breakdown point in percent; only
allowed with general

delta(#) shifting constant; only
allowed with general

over(varname) compute results for subpopulations defined by
varname

cw perform casewise deletion of observations

Graph
nograph do not draw a graph

graph_options graph options

Reporting
notable suppress output table

Returns
flag[(spec)] store variables flagging outside values

generate[(spec)] store variables containing
results

replace allow overwriting existing variables

postoutsides store outside values in e(outsides)

pweights, iweights, and fweights are allowed; see weight.

graph_options Description

Main
vertical vertical box plot; the default

horizontal horizontal box plot

nooutsides do not show outside values

sort[(index)] sort boxes by median

descending use descending sort order

Labels
nolabel use names/values in default labels

labels(strlist) override default tick labels

llabels(strlist) override default legend labels

Rendering
boxwidth(#) width of boxes

overgap(#) extra gap between groups of boxes

medmarker indicate median by a marker instead of a line

med[#]opts(options) affect rendering of medians

box[#]opts(options) affect rendering of boxes

whisk[#]opts(options) affect rendering of whiskers

out[#]opts(options) affect rendering of outside values

plot[#]opts(options) affect rendering of all box plot elements

Other
addplot(plots) add other plots to the graph

twoway_options general twoway options, other than by()

Description

robbox is a command to produce (robust) box plots. Supported are the
standard box plot (equivalent to graph box), the skewness-adjusted box
plot based on the medcouple by Hubert and Vandervieren (2008), and the
generalized box plot based on Tukey's g-and-h distribution by Bruffaerts et
al. (2014). By default, robbox computes the generalized box plot.

The adjusted option of robbox requires robstat to be
installed; type ssc install robstat.

Options

Main

standard computes the standard box plot. This is equivalent to
graph box, as long as alpha() is not changed. Only one
of standard, adjusted, and general is allowed.

adjusted computes the skewness-adjusted box plot based on the medcouple,
as proposed by Hubert and Vandervieren (2008). boxplot calls
robstat to compute the medcouple. Only one of standard,
adjusted, and general is allowed.

general computes the generalized box plot based on Tukey's g-and-h
distribution, as proposed by Bruffaerts et al. (2014). This is the default.
Only one of standard, adjusted, and general is allowed.

alpha(#) specifies the outside value percentage, that is, the percentage
of observations classified as outside values under normal conditions. The default is

alpha = 200 * (1 - normal(z_0.75 + 1.5 * (z_0.75 - z_0.25)))

where z_p is the p-quantile of the standard normal distribution; this is
approximately equal to alpha(0.7). Option alpha() is not allowed
with adjusted.

bp(#) sets the breakdown point, in percent, that is used when fitting
the g-and-h distribution. The default is bp(10). Option
bp() is only allowed with general.

delta(#) sets the shifting constant used in the algorithm to fit the
g-and-h distribution. The default is delta(0.1). There is not much
reason to change this default. Option delta() is only allowed with
general.

over(varname) repeats the computations for each subpopulation defined by the
values of varname.

cw specifies casewise deletion of observations. Results will then be
be computed for the sample that is not missing for any of the variables in
varlist. The default is to use all the nonmissing values for each
variable.

Graph

nograph suppresses the graph.

graph_options are graph options as described below.

Reporting

notable suppresses the output tables.

Returns

flag[(spec)] creates variable(s) that flag the
outside values (1 = outside value, 0 else). spec is either a prefix
specified as prefix* or a space-separated list of names to be
used as variable names for the flag variables (the list must contain the
same number of names as varlist). If spec is
omitted, _flag_ is used as prefix.

generate[(spec)] creates 8 variables containing the
box plot results. This is useful if you want to create a custom graph of
the results. The 8 variables provide a group ID ("equation"), a within-group
ID ("coefficient"), the median, the lower hinge (lower edge of the box), the
upper hinge (upper edge of the box), the lower adjacent value (lower
whisker), the upper adjacent value (upper whisker), and the number of
observations. spec is either a prefix specified as prefix*
or a space-separated list of 7 names. If spec is omitted, the
following names will be used: _box_gid, _box_id,
_box_med, _box_lbox, _box_ubox, _box_lav,
_box_uav, and _box_N. If a prefix is specified, prefix
will be used instead of _box_.

replace allows flag() and generate() to overwrite existing
variables.

postoutsides stores the outside values in matrix
e(outsides).

Graph options

Main

vertical causes a vertical box plot to be drawn. This is the default.

horizontal causes a horizontal box plot to be drawn.

nooutsides omits the markers displaying the outside values.

sort[(index)] sorts the boxes by the value of the median. If
varlist contains multiple variables and over() has been
specified, you can provide index to select the variable determining
the sort order. For example, sort(2) would sort the over-groups
according to the medians of the second variable. If index is omitted, the
average over all variables is used.

descending uses descending sort order. The default is to use ascending
sort order. descending only has an effect if sort has been specified.

Labels

nolabel specifies that variable names and over-group values be used
as labels. The default is to use variable labels and value labels, if
such labels are available.

labels(strlist) specifies a space-separated list of custom tick labels to
be used instead of the default labels. Enclose
labels that contain spaces in double quotes,
e.g. labels("label 1" "label 2" ...). Default labels are used for
remaining ticks if the list contains less labels than there are ticks. Within
the list, you can specify "" to use a default label.

llabels(strlist) specifies custom legend-key labels. Enclose
labels that contain spaces in double quotes,
e.g. llabels("label 1" "label 2" ...). Default labels are used for
remaining keys if the list contains less labels than there are keys. Within
the list, you can specify "" to use a default label.

Rendering

boxwidth(#) sets the width of the boxes in percent of the available
space. The default is boxwidth(50). In this case, the space between
boxes will be equal to the box width; if you specify boxwidth(100)
there will be no space between boxes.

overgap(#) sets the extra gap that is inserted between groups of boxes
if varlist contains multiple variables and over() is
specified. The default is overgap(10), meaning that the extra space is set
to 10 percent of the distance between group centers. Specify overgap(0)
to omit the extra space.

medmarker causes the median to be indicated by a marker symbol inside the
box. The default is to indicate median by line.

med[#]opts(options) provides options that affect the
rendering of median lines or, if medmarker has been specified, median
markers; candidate options are line_options or
marker_options, respectively. Option medopts() will affect all
medians. If over() has been specified, you may additionally use med1opts(),
med2opts(), etc. to affect only the medians of the 1st, 2nd, etc. variable.

box[#]opts(barlook_options) provides options that affect the
rendering of the boxes. Option boxopts() will affect all
boxes. If over() has been specified, you may additionally use box1opts(),
box2opts(), etc. to affect only the boxes of the 1st, 2nd, etc. variable.

whisk[#]opts(options) provides options that affect the
rendering of the whiskers; candidate options are line_options and msize()
as described in twoway rcap. Option whiskopts() will affect all
whiskers. If over() has been specified, you may additionally use whisk1opts(),
whisk2opts(), etc. to affect only the whiskers of the 1st, 2nd, etc. variable.

out[#]opts(marker_options) provides options that affect the
rendering of the outside value markers. Option outopts() will affect all
outside value markers. If over() has been specified, you may additionally use out1opts(),
out2opts(), etc. to affect only the outside value markers of the 1st, 2nd, etc. variable.

plot[#]opts(options) provides options that affect the
rendering of all box plot elements; see, e.g., marker_options,
line_options, and barlook_options for candidate
options. Option plotopts() will affect all
plots. If over() has been specified, you may additionally use plot1opts(),
plot2opts(), etc. to affect only the plots of the 1st, 2nd, etc. variable.

Other

addplot(plot) provides a way to add other plots to the generated graph; see help
addplot_option.

twoway_options are any options documented in help twoway_options, other
than by().

Examples

Standard box plot

. sysuse nlsw88, clear
. robbox wage ttl_exp tenure, standard outopts(ms(oh))

Skewness-adjusted box plot

. robbox wage ttl_exp tenure, adjusted outopts(ms(oh))

Generalized box plot

. robbox wage ttl_exp tenure, outopts(ms(oh))

Horizontal orientation

. robbox wage ttl_exp tenure, outopts(ms(oh)) horizontal

Box plots by subpopulations (output table suppressed)

. robbox wage, over(industry) notable outopts(ms(oh)) horizontal

Remove outside values and sort by median

. robbox wage, over(industry) notable horizontal sort nooutsides

Multiple variables by subpopulations

. robbox wage tenure, over(race) notable horizontal outopts(ms(oh))

Multiple variables by subpopulations: change rendering for specific variable

. robbox wage tenure, over(race) notable horizontal outopts(ms(oh)) plot2opts(pstyle(p3)) out2opts(ms(x))

Change cap width of whiskers ...

. robbox wage ttl_exp tenure, outopts(ms(oh)) horizontal whiskopts(msize(ehuge))

... and use marker symbols for the median

. robbox wage ttl_exp tenure, outopts(ms(oh)) horizontal whiskopts(msize(ehuge)) medmarker medopts(ms(D) mcolor(white))

Label the outside values

. robbox tenure, over(race) outopts(mlabel(idcode))

Label only selected outside values

. generate str ID = string(idcode) if tenure>15
. robbox tenure, over(race) outopts(mlabel(ID))

Superimpose a density estimate using addplot()

. robbox wage, xtitle(wage) horizontal yscale(range(-3) off) ytitle(density, axis(2)) addplot(kdensity wage, lwidth(*2) yaxis(2) yscale(alt axis(2)))

The trick is to place the box plot and the density estimate on different Y-axes. Option
yscale(range(-4) off) suppresses the Y axis created by robbox and
adds space at the top by increasing the range.

Draw plot using coefplot (see ssc describe coefplot) ...

. robbox wage ttl_exp tenure, nograph notable

. coefplot, ms(d) ci(whiskers box) ciopts(recast(rcap rbar) fintensity(. 50) barwidth(. .5)) label

... including outside values

. robbox, postoutsides

. coefplot (., ms(d) ci(whiskers box) ciopts(recast(rcap rbar) fintensity(. 50) barwidth(. .5))) (., b(outsides) noci pstyle(p1) ms(oh)), nooffsets legend(off) label

Stored results

robbox stores the following in e():

Scalars

e(N) number of observations

e(N_vars) number of variables

e(N_over) number of subpopulations

e(k_eq) number of equations in e(b)

e(alpha) alpha parameter (general and standard only)

e(bp) breakdown point (general only)

e(delta) delta parameter (general only)

Macros

e(cmd) robbox

e(cmdline) command as typed

e(title) title in estimation output

e(method) standard, adjusted, or general

e(depvar) variable names

e(over) name of over() variable

e(over_namelist) values from over() variable

e(over_labels) labels from over() variable

e(wtype) weight type

e(wexp) weight expression

e(properties) b

Matrices

e(b) medians

e(box) lower and upper hinges

e(whiskers) lower and upper adjacent values

e(whiskers0) initial values of whiskers

e(N_out) number outside values

e(g) estimated g parameters (general only)

e(h) estimated h parameters (general only)

e(_N) numbers of observations

Functions

e(sample) marks estimation sample

If postoutsides is specified, robbox will additionally
store matrix e(outsides) containing the outside values.

References

Bruffaerts, C., V. Verardi, and C. Vermandele. 2014. A generalized boxplot for skewed
and heavy-tailed distributions. Statistics and Probability Letters 95: 110-117.

Hubert, M., and E. Vandervieren. 2008. An adjusted boxplot for skewed
distributions. Computational Statistics and Data Analysis 52: 5186-5201.

Authors

Ben Jann (University of Bern),
Vincenzo Verardi (University of Namur and Universite libre de Bruxelles),
Catherine Vermandele (Universite libre de Bruxelles)

Support: ben.jann@soz.unibe.ch

Thanks for citing this software as follows:

Jann, B., V. Verardi, C. Vermandele (2019). robbox: Stata module to compute
generalized box plots. Available from
http://ideas.repec.org/c/boc/bocode/s458620.html.

Also see

Online: help for
graph box

From the SSC Archive:
robreg,
robstat