help cisets

Title

cisets -- Confidence interval sets for various summary statistics

Syntax

Confidence interval sets for means, normal distribution

Variables syntax

cisets means varlist
[if] [in]
[weight]
[
,
inclusive
level(#)
saving(filespec)
list_options
]

Groups syntax

cisets means varname
[if] [in]
[weight]
, over(groupvar)
[
total
level(#)
saving(filespec)
list_options
]

Confidence interval sets for means, Poisson distribution

Variables syntax

cisets means varlist
[if] [in]
[weight]
,
poisson
[
exposure(varname)
inclusive
level(#)
saving(filespec)
list_options
]

Groups syntax

cisets means varname
[if] [in]
[weight]
,
poisson
over(groupvar)
[
exposure(varname)
level(#)
saving(filespec)
list_options
]

Confidence interval sets for proportions

Variables syntax

cisets proportions varlist
[if] [in]
[weight]
[
,
inclusive
{
exact |
wald |
wilson |
agresti |
jeffreys
}
level(#)
saving(filespec)
list_options
]

Groups syntax

cisets proportions varname
[if] [in]
[weight]
,
over(groupvar)
[
{
exact |
wald |
wilson |
agresti |
jeffreys
}
level(#)
saving(filespec)
list_options
]

Confidence interval sets for variances

Variables syntax

cisets variances
varlist
[if] [in]
[weight]
[
,
inclusive
bonett
level(#)
saving(filespec)
list_options
]

Groups syntax

cisets variances
varname
[if] [in]
[weight]
,
over(groupvar)
[
total
bonett
level(#)
saving(filespec)
list_options
]

Confidence interval sets for standard deviations

Variables syntax

cisets variances
varlist
[if] [in]
[weight]
,
sd
[
inclusive
bonett
level(#)
saving(filespec)
list_options
]

Groups syntax

cisets variances
varname
[if] [in]
[weight],
sd
over(groupvar)
[
total
level(#)
saving(filespec)
bonett
list_options
]

Confidence interval sets for geometric means

Variables syntax

cisets gmean
varlist
[if] [in]
[weight]
[
,
inclusive
level(#)
saving(filespec)
list_options
]

Groups syntax

cisets gmean
varname
[if] [in]
[weight],
over(groupvar)
[
total
level(#)
saving(filespec)
list_options
]

Confidence interval sets for harmonic means

Variables syntax

cisets hmean
varlist
[if] [in]
[weight]
[
,
inclusive
level(#)
saving(filespec)
list_options
]

Groups syntax

cisets hmean
varname
[if] [in]
[weight]
,
over(groupvar)
[
total
level(#)
saving(filespec)
list_options
]

Confidence interval sets for centiles

Variables syntax

cisets centile
varlist
[if] [in]
[
,
centile(#)
inclusive
{
cci |
normal |
meansd
}
saving(filespec)
list_options
]

Groups syntax

cisets centile
varname
[if] [in]
,
over(groupvar)
[
centile(#)
{
cci |
normal |
meansd
}
total
level(#)
saving(filespec)
list_options}
]

aweights are allowed with cisets subcommands means for
normal data; gmean; and hmean.

fweights are allowed with cisets subcommands means;
proportions; variances; gmean; and hmean.

Weights are not allowed with subcommand centile.

Description

cisets computes confidence interval sets for population means,
proportions, variances, standard deviations, geometric means, harmonic
means, and centiles. It is a wrapper for variously ci (for
means, proportions, variances and standard deviations); ameans
(for geometric and harmonic means); and centile. The help for
these commands and the corresponding manual entries should be consulted
for more detail on statistical principles and procedures.

All syntaxes include cisets followed by a subcommand which
specifies a particular summary measure. There are two flavours of
commands otherwise:

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

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

A confidence interval 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.

* statname is a string variable holding a brief description of the
parameter being estimated by a point estimate and a confidence
interval. With the subcommand centile, the corresponding percent
is shown, either as specified with centile() or as defaulting to
50% (median).

* point is a numeric variable holding the point estimate of the
parameter being estimated.

* (subcommands means and proportions only)
se is a numeric variable holding the standard error reported.

* lb is a numeric variable holding the lower bound of the confidence
interval estimate.

* ub is a numeric variable holding the upper bound of the confidence
interval estimate.

* level is a numeric variable holding the confidence level used.

* options is a string variable appearing if (and only if) other
options have been specified as a record of such option choice.

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

Remarks

cisets by default lists its results. Although saving to
a permanent dataset is optional, that is the intended key to many
useful applications. Either the confidence interval 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 intervals for different variables, or of intervals
for one variable for different groups, but also of intervals for several
variables and several groups; comparison of parameters; comparison of
results for different confidence levels; comparison of different
methods; and so forth.

As in ci, variables that are not (0, 1) binary variables
are ignored with cisets proportions.

As in ameans, any zero or negative values are ignored
with cisets gmean and cisets hmean.

At first sight, a confidence interval 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 (lower and upper bounds) and twoway scatter
for the point estimates within.

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

In statistical graphics, showing confidence intervals - or their
antecedents and relatives under various names such as error bars - has
a history over decades, if not centuries. That history does not seem well
documented.

In terms of Stata's own twoway commands, use of something like
scatter to show a point estimate as a point or marker symbol is very
common, but not universal. Some authors argue that the importance of showing
estimates as intervals means that a point symbol should be suppressed. More
frequently, bars usually starting at zero are used to show point estimates.
When combined with capped or uncapped spikes, as mentioned just below, such
plots have been described pejoratively as dynamite, detonator or plunger plots
and often deplored.

Otherwise, showing the intervals with capped spikes using something
like twoway rcap seems the most common style; showing uncapped spikes
using something like twoway rspike next most common; and showing range bars,
whether coloured or blank, using something like twoway rbar seems less
common than either of those. The choice may seem a matter of style or personal
preference unless there is evidence that any form is most effective.
Wilkinson (1999, 2005) gives examples of all, including range bars.
See also Wilkinson (2006) on Pareto dot plots.

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 is a predictable place to add
a confidence interval on the right of each display, so long as any
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

Options allowed with all subcommands

level(#) specifies the confidence level, as a percentage, for confidence
intervals. The default is level(95) or as set by set level.

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 confidence interval 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 determine confidence intervals 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.

Options allowed with cisets mean

poisson specifies that the variables are
Poisson-distributed counts; exact Poisson confidence intervals will be
calculated. By default, confidence intervals for means are calculated based on
a normal distribution.

exposure(varname) is used only with poisson. You do not need
to specify poisson if you specify exposure();
poisson is assumed. varname contains the total exposure (typically a
time or an area) during or over which the number of events recorded was
observed.

Options allowed with cisets proportions

exact, wald, wilson, agresti, and jeffreys
specify how binomial confidence intervals are to be calculated. Only one of
these options may be specified.

exact is the default and specifies exact (also known in the literature
as Clopper-Pearson) binomial confidence intervals.

wald specifies calculation of Wald confidence intervals.

wilson specifies calculation of Wilson confidence intervals.

agresti specifies calculation of Agresti-Coull confidence intervals.

jeffreys specifies calculation of Jeffreys confidence intervals.

Options allowed with cisets variances

sd specifies that confidence intervals for standard deviations be
calculated. The default is to compute confidence intervals for variances.

bonett specifies that Bonett confidence intervals be calculated.
The default is to compute normal-based confidence intervals, which assume
normality for the data.

Options allowed with cisets centile

centile(#) specifies the centile or percentile to be reported.
The default is to display the 50th centile or percentile (median).
Specifying centile(5) requests that the fifth centile be reported.

Only one of the following options may be specified.

cci (conservative confidence interval) forces the confidence limits to
fall exactly on sample values. Confidence intervals displayed with the
cci option are slightly wider than those with the default.

normal causes the confidence interval to be calculated by using a formula
for the standard error of a normal-distribution quantile. The normal option
is useful when you want empirical centiles -- that is, centiles based on sample
order statistics rather than on the mean and standard deviation -- and are
willing to assume normality.

meansd causes the centile and confidence interval to be calculated based
on the sample mean and standard deviation, and it assumes normality.

Examples

. sysuse auto, clear

. cisets mean mpg, over(rep78) saving(foo, replace)

. d using foo

. cisets mean mpg price weight, saving(foo, replace)

. d using foo

. cisets prop foreign, over(rep78) jeffreys saving(foo, replace)

. d using foo

. cisets prop foreign, jeffreys saving(foo, replace)

. d using foo

. cisets var mpg, over(rep78) saving(foo, replace)

. d using foo

. cisets var mpg price weight, saving(foo, replace)

. d using foo

. cisets gmean mpg, over(rep78) saving(foo, replace)

. d using foo

. cisets gmean mpg price weight, saving(foo, replace)

. d using foo

. cisets hmean mpg, over(rep78) saving(foo, replace)

. d using foo

. cisets hmean mpg price weight, saving(foo, replace)

. d using foo

. cisets centile mpg, over(rep78) saving(foo, replace)

. d using foo

. cisets centile mpg price weight, saving(foo, replace)

. d using foo

. cisets centile mpg price weight, centile(75) saving(foo, replace)

. d using foo

. cisets centile mpg, over(rep78) total saving(foo, replace)

. u foo, clear

. replace statname = "median"

. twoway rspike ub lb group || scatter point group, pstyle(p1) msize(medlarge) ms(D)

xtitle("`=gvarlabel'") xla(1/6, valuelabel) legend(off) ytitle("`=varlabel'")

subtitle("`=statname's: `=level'% confidence intervals", place(w)) name(CI1, replace)

. twoway rspike ub lb group, horizontal || scatter group point, pstyle(p1) msize(medlarge) ms(D)

ytitle("`=gvarlabel'") yla(1/6, valuelabel) legend(off) xtitle("`=varlabel'")

subtitle("`=statname's: `=level'% confidence intervals", place(w)) ysc(reverse) xsc(alt) ysc(r(0.8 .)) name(CI2, replace)

. su ub, meanonly

. local ubmax = r(max)

. su lb, meanonly

. local lbmin = r(min)

. gen where = `lbmin' - (`ubmax' - `lbmin') / 10

. gen show_n = ("n = ") + strofreal(n)

. twoway rspike ub lb group || scatter where group, ms(none) mla(show_n) mlabpos(0) mlabc(black) mlabsize(medium)

|| scatter point group, pstyle(p1) msize(medlarge) ms(D) xtitle("`=gvarlabel'") xla(1/6, valuelabel) xsc(r(0.5, 6.5))

legend(off) ytitle("`=varlabel'") subtitle("`=statname's: `=level'% confidence intervals", place(w)) name(CI3, replace)

. twoway rbar ub lb group, lcolor(stc1) fcolor(none) barw(0.2)

|| scatter where group, ms(none) mla(show_n) mlabpos(0) mlabc(black) mlabsize(medium)

|| scatter point group, pstyle(p1) msize(medlarge) ms(D) xtitle("`=gvarlabel'")

xla(1/6, valuelabel) xsc(r(0.5, 6.5)) legend(off) ytitle("`=varlabel'") subtitle("`=statname's: `=level'% confidence intervals", place(w)) name(CI4, replace)

. webuse citytemp, clear

. cisets mean heatdd, over(division) saving(foo, replace)

. u foo

. myaxis group2=group, sort(mean point)

. twoway rspike ub lb group2 || scatter point group2, pstyle(p1) xla(1/9, valuelabel tlc(none))

ytitle(`=varlabel' (day {&degree}F)) subtitle("`=statname's: `=level'% confidence intervals", place(w)) legend(off) xsc(r(0.8 9.2)) name(CI5, replace)

. sysuse auto, clear

. cisets gmean price, over(foreign) saving(foo, replace)

. clonevar origgvar=foreign

. merge m:1 origgvar using foo

. gen where = 1

. qplot price, ms(O) by(foreign, legend(off) note(95% confidence intervals for geometric means))

xla(0 0.25 "0.25" 0.5 "0.5" 0.75 "0.75" 1)

ysc(log) yla(3000(2000)15000) ytitle(Price (USD)) xtitle(Fraction of data)

addplot(rbar ub lb where, barw(0.08) fcolor(none) pstyle(p2)

|| scatter point where, ms(D) msize(medlarge) pstyle(p2)) name(CI6, replace)

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.

Wilkinson, L. 1999.
The Grammar of Graphics.
New York: Springer. See pp.183, 223, 269, 271.

Wilkinson, L. 2005.
The Grammar of Graphics.
New York: Springer. See pp.102, 131, 218, 220, 461, 470, 478, 479, 480, 481, 522.

Wilkinson, L. 2006.
Revising the Pareto chart. American Statistician 60: 332-334.

Also see

help for ci

help for ameans

help for centile