help pctilesets

Title

pctilesets -- Percentile or quantile sets for selected levels

Syntax

Variables syntax

pctilesets varlist
[if] [in]
[weight]
[
,
inclusive
pctile(numlist)
minimum
maximum
saving(filespec)
list_options
]

Groups syntax

pctilesets varname
[if] [in]
[weight]
, over(groupvar)
[
total
pctile(numlist)
minimum
maximum
saving(filespec)
list_options
]

aweights and fweights are allowed.

Description

pctilesets computes percentile or quantile sets.
It is a wrapper for summarize.
The help for summarize and the corresponding manual entry
should be consulted for more detail on statistical principles and procedures.

Typically the user will specify one or more of the options pctile(),
minimum and maximum to select extremes and/or any or all
of the percentiles for 1, 5, 10, 25 (lower quartile), 50 (median),
75 (upper quartile), 90, 95 and 99% cumulative probability.

There are two syntaxes.

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

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

A percentile 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.

* Any or all of min, p1, p5, p10, p25,
p50, p75, p90, p95, p99 and max holding results
for the measure concerned.

* weights is a string variable appearing if (and only if) weights were
specified as a record of such use.

Remarks

pctilesets by default lists its results. Although saving to
a permanent dataset is optional, that is the intended key to many
useful applications. Either the percentile dataset is what
is needed or it may be combined using append or merge
with other such sets 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 percentiles for different variables, or of percentiles
for one variable for different groups, but also of percentiles for several
variables and several groups; and so forth.

At first sight, a percentile 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 percentiles and twoway scatter for
plotting particular percentiles.

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 cisets or momentsets if installed.

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 |
+-------------------------------------------+

Options

Option allowed with either syntax

pctile() allows any or all of 1 5 10 25 50 75 90 95 99 indicating that
such percentiles be included in the results as calculated by summarize.
Any other integers between 2 and 98 will be ignored with a warning.

minimum requests that the minimum be included in the results.

maximum requests that the maximum be included in the results.

list_options are any options of list other than noobs that
may be specified to tune listing of the confidence interval set.

saving(filespec) specifies saving the percentile 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 compulsory 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

. pctilesets mpg, p(25 50 75) min max over(foreign) saving(foo, replace)

. clonevar origgvar=foreign

. merge m:1 origgvar using foo

. gen where = 1.1

. #delimit ;

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

addplot(scatter p50 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 p75 p25 where, fcolor(none) barw(0.12) pstyle(p2)

|| rspike p25 min where, pstyle(p2)

|| rspike p75 max 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 p50 where, ms(Dh) msize(medlarge) pstyle(p2)

|| rbar p75 p25 where, fcolor(none) barw(0.44) pstyle(p2)

|| rspike p25 min where, pstyle(p2)

|| rspike p75 max 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 p25 p50 where, barw(0.5) fcolor(none) pstyle(p2)

|| rbar p75 p50 where, fcolor(none) barw(0.5) pstyle(p2)

|| rspike p25 min where, pstyle(p2)

|| rspike p75 max 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)

. pctilesets marks, over(subject2) min max p(25 50 75) saving(foo, replace)

. gen where = 1.1

. clonevar origgvar=subject2

. merge m:1 origgvar using foo

. #delimit ;

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

addplot(rspike p25 min where, pstyle(p2)

|| rspike p75 max where, pstyle(p2)

|| rbar p25 p75 where, barw(0.16) fcolor(none) pstyle(p2)

|| scatter p50 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

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. 2018.
Speaking Stata: Logarithmic binning and labeling.
Stata Journal 18: 262-286.

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.

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.

Also see

help for summarize