help quantilesets

Title

quantilesets -- Quantile sets for selected
probability levels

Syntax

Variables syntax

quantilesets varlist
[if] [in]
,
prob(numlist)
[
inclusive
method(name)
saving(filespec)
list_options
]

Groups syntax

quantilesets varname
[if] [in]
, over(groupvar)
prob(numlist)
[
method(name)
total
saving(filespec)
list_options
]

Description

quantilesets computes percentile or quantile sets. It is a
wrapper for the Mata function quantile() added to
Stata 19.50 on 12 November 2025. The help for quantile()
and the corresponding manual entry should be consulted for more detail.

Typically the user will specify one or more probability levels between 0
and 1 inclusive using the required option prob().

There are two syntaxes.

quantilesets varlist calculates results for one or more
variables varlist. This is called the variables syntax.

quantilesets varname, over(groupvar) calculates
results for one variable varname for each distinct value of
groupvar. This is called the groups syntax.

A quantile set consists of a temporary dataset consisting of some or
occasionally all of the following variables.

* varname is a string variable holding the name or names of the
variable(s) being summarized.

* varlabel is a string variable holding the variable label of each
variable being summarized. If no variable label has been defined, the
value is instead the variable name.

* (Groups syntax only) origgvar is a numeric or string variable
as specified in the over() option.

* (Groups syntax only) groupvar is a string variable holding the
name of the group variable specified in the over() option.

* (Groups syntax only) gvarlabel is a string variable holding the
variable label of the group variable groupvar specified in the
over() option. If no variable label has been defined, the value is
instead the variable name.

* (Groups syntax only) group is a numeric variable with value
labels describing each distinct value of groupvar. Each such
variable has integer values 1 up and value labels derived from the
variable specified.

* n is a numeric variable holding the number of observations used
in the estimate.

* One or more quantile variables named q1, q2, and so forth.
Conventions are best explained by example. Suppose the specification was
prob(0.25 0.5 0.75). Then there are three resulting quantile
variables named q1, q2, q3 and they have variable
labels 0.25 quantile, 0.5 quantile, 0.75 quantile.

* method is a string variable naming the estimation method used.
The default method choice is tukey.

Remarks

Quantiles, percentiles, and various Stata commands

As explained for example by Cox (2024), the term quantile has
acquired related but distinct meanings. One meaning refers to the values
of a variable sorted or ordered in magnitude, the order statistics,
especially when plotted, usually against the quantiles
of another variable or as estimated for a candidate fitted distribution.
This is the sense behind official commands quantile,
qqplot, qnorm and qchi, and behind community-contributed
commands such as qplot (discussed below), multqplot (Cox
2012, 2019), and qqplotg (Cox 2024). The term percentile is
also occasionally used in this sense (for example, Cleveland 1985).

The related but distinct meaning foremost in quantilesets is that
of summary statistics (or correspondingly parameters) defined by the
fraction or probability of values being lower, and thus also by the
complementary fraction of values being higher. Such statistics must be
calculated, or such parameters must be estimated, using a rule or recipe
which variously yields either original data values or points between
them. The simplest example of such a recipe is that for the median, as
given by the middlemost value if the number of values is odd and by the mean
of the two middlemost values (the comedians) if the number of values is even.
This recipe is explained to mathematical audiences as a convention and to less
mathematical audiences as a rule.

Much of the rationale for the Mata function quantile() and
thus for quantilesets is that several such rules or recipes exist,
which usually produce similar but not necessarily
identical results. Such varying methods are tied up with different
methods for calculating the corresponding cumulative probabilities, in a
graphical context often known as plotting positions, as quantiles are in
principle obtained by inverting the (cumulative) distribution function.
The documentation for quantile() flags Cunnane (1978) and Hyndman
and Fan (1996) as key references, but yet more approaches to quantile
estimation exist. See for example Harrell and Davis (1982) (and
correspondingly hdquantile from SSC) and Ma, Genton and Parzen
(2021).

In official Stata commands for estimating particular quantiles include
pctile, _pctile and centile. Other official
commands producing quantiles typically rest on one such command. See
also Ben Jann's mm_quantile() and related Mata functions from his
package moremata (SSC).

In practice the term percentile is typically used in this sense of
quantile, as a summary statistic or as an parameter estimate defined by
the percent of values lower. Usage has often morphed away from any
implication that there are 99 distinct percentiles for percents 1(1)99
(or 101 if the minimum and maximum are regarded by courtesy as the 0 and
100% percentiles). Thus many would feel no discomfort in regarding say
the 2.5% and 97.5% points as also being percentiles. For a menagerie of
related terms, from tertile onwards, see Cox (2016). To the list there
may be added pentile=quintile (5), decentile=decile (10),
hexadecile=suboctile (16), ventile=vigintile (20) and trentile (30).

Yet another meaning of quantile is to refer to the bins, classes, or
intervals they delimit, as wheh the first quartile is the lowest quarter
of a distribution.

Use of quantilesets

quantilesets by default lists its results. Although saving to a
permanent dataset is optional, that is the intended key to many useful
applications. Either the quantile dataset is what is needed or it may be
combined using append or merge with other datasets for
further analysis.

The approach is thus one of providing a building block that may be
useful directly or if combined with other building blocks. Flexibility
is needed because so many different problems may be of interest, not
just comparison of quantiles for different variables, or of quantiles
for one variable for different groups, but also of quantiles for several
variables and several groups; and so forth.

At first sight, a quantile set may seem repetitious. With a little
experience, you will see that such repetition is often helpful when
combining such sets. In any case, you can always ignore what you do not
need. Similarly, you can use rename and replace as you
wish downstream of this command.

Graphical and other applications lie downstream of this command,
although some suggestions are included in the examples. Possibilities
include twoway rcap, twoway rspike and twoway rbar
for plotting intervals between quantiles and twoway scatter for
plotting particular quantiles.

Helper commands include myaxis to sort on some criterion (Cox
2021) and nicelabels (Cox 2022) and niceloglabels (Cox 2018)
for automating axis labels.

The approach to correlation confidence intervals of Cox (2008) is
broadly similar. See also pctilesets, cisets,
momentsets or lmomentsets if installed.

Use with qplot

The command qplot is used in examples: see Cox (1999, 2005) and
search for updates. By default the horizontal axis is a probability
scale from 0 to 1 so (for example) 1.1 is a predictable place to add
something like a box plot on the right of each display, so long as each
bar is not too wide. For a normal quantile plot the range of standard
normal deviates depends on the sample size, as indicated by this Mata
output for a plotting position (rank - 0.5) / sample size. The largest
standard normal deviate plotted increases with sample size.

: n , (n :- 0.5) :/ n, invnormal((n :- 0.5) :/ n)
1 2 3
+-------------------------------------------+
1 | 10 .95 1.644853627 |
2 | 100 .995 2.575829304 |
3 | 1000 .9995 3.290526731 |
4 | 10000 .99995 3.890591886 |
+-------------------------------------------+

Comparison with pctilesets

quantilesets differs from the author's pctilesets as
follows.

* As stated quantilesets is a wrapper for Mata function
quantile() while pctilesets is a wrapper for
summarize.

* pctilesets offers no choice of estimation method, while
quantilesets offers several methods. That could be important if
you have a strong preference in principle for one method; or if you wish
to match a choice made in other software; or if you wish to compare
results obtained with different methods. Often differences will be
trivial, but not always, as with small datasets or those with gaps,
spikes or multiple modes.

* pctilesets as a wrapper for summarize offers only selected
percentiles, including the minimum and maximum. quantilesets
allows any probability level between 0 and 1 (inclusive) to be
specified.

* quantilesets does not support weights, while pctilesets
does support aweights and fweights.

Options

Option required with either syntax

prob() specifies one or more probability levels between 0 and 1
(inclusive) for estimation of quantiles. For example,
prob(0.25 0.5 0.75) specifies estimation of the quantiles often
known as lower (first) quartile, median, and upper (third) quartie. If
not presented in ascending order, levels will be sorted to ascending
order any way.

Options allowed with either syntax

method() requests use of a particular estimation method. The
default method is "tukey". See quantile() for
a list of allowed methods. See Hoaglin (1983, pp.44-49) for much more detail
on the Tukey method hinging on use of (rank - 1/3) / (sample size + 1/3)
as probability level (and from a different perspective Tukey, 1977, pp.496-497).

list_options are any options of list other than noobs
and subvarname that may be specified to tune listing of the
quantile set.

saving(filespec) specifies saving the quantile set to a file as a
Stata dataset. The suboption , replace must be specified to
overwrite an existing dataset.

Option allowed with the variables syntax

inclusive may be specified if you wish to work with several
variables together. By default, calculations are only made with
observations that have non-missing values for all variables specified.
This option overrides that default selection: hence for several
variables which observations with non-missing values are used will be
determined separately for each variable. In other jargon, this option
triggers casewise deletion, not listwise deletion or complete case
analysis. As a convenience for people familiar with that term, or with
other syntax used to this effect, cw and allobs are allowed
as synonyms.

Option required with the groups syntax

over(groupvar) must be specified to name the group variable.
Distinct groups of observations on groupvar will be used to produce
separate results for the main variable specified.

Option allowed with the groups syntax

total may be used with over(groupvar). It specifies that in
addition to output for each group, output be added for all groups
combined.

Examples

. sysuse auto, clear

. quantilesets mpg, prob(0 0.25 0.5 0.75 1) over(foreign) saving(results, replace)

. clonevar origgvar=foreign

. merge m:1 origgvar using results

. gen where = 1.1

. #delimit ;

. qplot mpg, ms(O) by(foreign, note("") legend(off))

addplot(scatter q3 where, ms(Dh) msize(medlarge) pstyle(p2)

xla(0 1 0.25 "0.25" 0.5 "0.5" 0.75 "0.75") xtitle(Fraction of data)

|| rbar q4 q2 where, fcolor(none) barw(0.12) pstyle(p2)

|| rspike q2 q1 where, pstyle(p2)

|| rspike q4 q5 where, pstyle(p2)) name(QB1, replace);

. #delimit cr

. replace where = 2.7

. #delimit ;

. qplot mpg, ms(O) by(foreign, note("") legend(off))

xla(-2/2) xtitle(Standard normal deviate)

addplot(scatter q3 where, ms(Dh) msize(medlarge) pstyle(p2)

|| rbar q4 q2 where, fcolor(none) barw(0.44) pstyle(p2)

|| rspike q2 q1 where, pstyle(p2)

|| rspike q4 q5 where, pstyle(p2)) trscale(invnormal(@))

name(QB2, replace);

. #delimit cr

. replace where = 0.5

. #delimit ;

. qplot mpg, ms(O) by(foreign, note("") legend(off))

xla(0 1 0.25 "0.25" 0.5 "0.5" 0.75 "0.75") xtitle(Fraction of data)

addplot(rbar q2 q3 where, barw(0.5) fcolor(none) pstyle(p2)

|| rbar q4 q3 where, fcolor(none) barw(0.5) pstyle(p2)

|| rspike q2 q1 where, pstyle(p2)

|| rspike q4 q5 where, pstyle(p2) below)

name(QB3, replace);

. #delimit cr

* For this dataset, see Mardia et al. (1979, 2024)

. use https://www.stata-journal.com/software/sj20-2/pr0046_1/mathsmarks, clear

. rename * (marks*)

. gen id = _n

. reshape long marks, i(id) j(subject) string

. myaxis subject2=subject, sort(median marks)

. qplot marks, by(subject2, row(1) compact) ytitle(Mathematics marks)

. quantilesets marks, over(subject2) prob(0 0.25 0.5 0.75 1) saving(results, replace)

. gen where = 1.1

. clonevar origgvar=subject2

. merge m:1 origgvar using results

. #delimit ;

. qplot marks, by(subject2, row(1) compact legend(off) note(""))

addplot(rspike q2 q1 where, pstyle(p2)

|| rspike q4 q5 where, pstyle(p2)

|| rbar q2 q4 where, barw(0.16) fcolor(none) pstyle(p2)

|| scatter q3 where, ms(Dh) msize(medlarge) pstyle(p2))

ytitle(Mathematics marks)

xla(0 0.25 "0.25" 0.5 "0.5" 0.75 "0.75" 1) xtitle(Fraction of data) name(QB4, replace);

. #delimit cr

Author

Nicholas J. Cox, Durham University

n.j.cox@durham.ac.uk

References

Cleveland, W. S. 1985.
The Elements of Graphing Data.
Monterey, CA: Wadsworth.

Cox, N. J. 1999.
Quantile plots, generalized.
Stata Technical Bulletin 51: 16-18.

Cox, N. J. 2005.
Speaking Stata: The protean quantile plot.
Stata Journal 5: 442-460.

Cox, N. J. 2008.
Speaking Stata: Correlation with confidence, or Fisher's z revisited.
Stata Journal 8: 413-439.

Cox, N. J. 2012.
Speaking Stata: Axis practice, or what goes where on a graph.
Stata Journal 12: 549-561.

Cox, N. J. 2016.
Letter values as selected quantiles.
Stata Journal 16: 1058-1071.

Cox, N. J. 2018.
Speaking Stata: Logarithmic binning and labeling.
Stata Journal 18: 262-286.

Cox, N. J. 2019.
Speaking Stata: Axis practice, or what goes where on a graph.
Stata Journal 19: 748-751.

Cox, N. J. 2021.
Speaking Stata: Ordering or ranking groups of observations.
Stata Journal 21: 818-837.

Cox, N. J. 2022.
Speaking Stata: Automating axis labels: Nice numbers and transformed scales.
Stata Journal 22: 975-995.

Cox, N. J. 2024.
Speaking Stata: Quantile-quantile plots, generalized.
Stata Journal 24: 514-534.

Cunnane, C. 1978.
Unbiased plotting positions-a review.
Journal of Hydrology 37: 205-222.
https://doi.org/10.1016/0022-1694(78)90017-3.

Harrell, F. E. and C. E. Davis. 1982.
A new distribution-free quantile estimator.
Biometrika 69: 635-640.

Hoaglin, D. C. 1983.
Letter values: A set of selected order statistics.
In Hoaglin, D. C., F. Mosteller and J. W. Tukey (Eds)
Understanding Robust and Exploratory Data Analysis.
New York: John Wiley, 33-57.

Hyndman, R. J. and Y. Fan. 1996.
Sample quantiles in statistical packages.
American Statistician 50: 361-365.

Ma, Y., M. G. Genton and E. Parzen. 2011.
Asymptotic properties of sample quantiles of discrete distributions.
Annals of the Institute of Statistical Mathematics 63: 227-243.

Mardia, K. V., J. T. Kent and J. M. Bibby. 1979.
Multivariate Analysis. London: Academic Press.

Mardia, K. V., J. T. Kent and C. C. Taylor. 2024.
Multivariate Analysis. Hoboken, NJ: John Wiley.

Tukey, J. W. 1977.
Exploratory Data Analysis. Reading, MA: Addison-Wesley.