*! Help file for iepowerdemo.ado version 1.42 1Feb2026

Title

iepowerdemo -- Visualize the statistical power of the estimator of the impact of a random treatment

Syntax

iepowerdemo
,
reps(#)
n1(#)
n2(#)
[
optional_options
]

Options

Required -options-
reps(#) Number of replications. This option determines the number of different samples are drawn and pairs of sample means computed.

n1(#) Size of the sample in group 1, conventionally the "Control Group".

n2(#) Size of the sample in group 2, conventionally the "Treatment Group".

Optional -options-
mu1(#) Population mean of the outcome in group 1 (Control Group)

mu2(#) Population mean of the outcome in group 2 (Treatment Group)

sigma1(#) Population standard deviation of the outcome in group 1 (Control Group)

sigma2(#) Population standard deviation of the outcome in group 2 (Treatment Group)

title(string) Title of the created histograms of the sampling distributions. See title_options.

xtitle(string) Title of the x-axis of the created histograms of the sampling distributions. See title_options.

filestub(stub) Optionally specify the stub for saved DTA and GPH files. The default stub is "obs_Ntotal", where Ntotal = n1 + n2.

level(stub) Optionally specify the confidence level, CLVL, (and thus the significance level or p-value = 1-CLVL) for rejection of the null hypothesis of equal means (or zero impact). The default is CLVL=95 (or p = 0.05).

showrep(rep#) By default, the results of each replication are hidden. Option -showrep(#)- displays the mechanics of drawing the sample, the difference in the means, testing whether the difference is statistically significant for a single replication, .

verbose Option -verbose- displays the mechanics for every replication. Since the number of replications is arbitrarily large, this option produces a great deal of output. Rarely used, except for debugging.

Discussion

The purpose of iepowerdemo is to visually demonstrate the impact of sample size
on the precision of impact estimation with data from a simulated random controlled trial or RCT.
iepowerdemo is intended for pedagogical presentations on statistical power.

iepowerdemo draws multiple replications of a random sample from a
population consisting of two groups, a "Control Group" and a "Treatment Group".
The definition of "impact" is the difference between the means in the two groups.

The program produces three annotated graphs, one of the two sampling distributions
of the means of the control and treatment groups, one of the distribution of the
differences between the means (i.e. the estimated impact) and one of the distinct distributions
of the differences that are not statistically signifcant and those that are significant.
The latter of these graphs constitutes a visualization of the simulated statistical power of the RCT
with the given population parameters, sample sizes and significance level.

This program requires the community-contributed program hist_overlay.

Examples

The DO-file, iepowerdemo_example.do,
available from CGD's Stata repository here,
contains the code to run the following
examples. First, clear memory.

. clear

. iepowerdemo , reps(200) n1(50) n2(75)

Using Stata's official histogram command, construct a histogram of the variable mpg.

.
. * Without options, the frequency histogram of the variable mpg is:
. histogram mpg, frequency name(hist1_0, replace)
(bin=8, start=12, width=3.625)

.
. * The data contains a dichotomous variable: -foreign-
. tab foreign, sum(mpg)

| Summary of Mileage (mpg)
Car origin | Mean Std. dev. Freq.

+

Domestic | 19.826923 4.7432972 52
Foreign | 24.772727 6.6111869 22

+

Total | 21.297297 5.7855032 74

.
. * Overlay the histograms of mpg for domestic and foreign cars
. * (Note that the frequency option is the default for -iepowerdemo-.)
. iepowerdemo mpg, over(foreign) name(hist2_0,replace)

.
. * Compare the results from -histogram- and -iepowerdemo- side by side
. graph combine hist1_0 hist2_0, ycommon name(no_options, replace)
click to see the combined graph

.
. * To make it easier to compare the two depictions of the data,
. * specify common starting points, widths and styles for the bars
. * and similarly formatted legends.
. histogram mpg, frequency start(10) width(2.5) fcolor(none) lcolor(black) ///
> legend(on order(1 "All cars") rows(1)) name(hist1_1, replace)
(bin=13, start=10, width=2.5)

.
. iepowerdemo mpg, over(foreign) start(10) width(2.5) name(hist2_1, replace)

.
. * Compare them side by side
. * The histograms now resemble one another.
. gr combine hist1_1 hist2_1, ycommon name(no_lbls, replace)
click to see the combined graph

.
. * Add labels to make it easier to read the height of the bars
. histogram mpg, frequency start(10) width(2.5) fcolor(none) lcolor(black) ///
> legend(on order(1 "All cars") rows(1)) addlabels name(hist1_2, replace)
(bin=13, start=10, width=2.5)

.
. iepowerdemo mpg, over(foreign) frequency start(10) width(2.5) addlabels name(hist2_2, replace)

.
. * Compare them side by side
. * Note that the heights of the two overlaid bars on the right
. * sum to the height of the corresponding bar on the left.
. gr combine hist1_2 hist2_2, ycommon name(withlbls, replace)
click to see the combined graph

.
. * It's apparent from the overlaid histogram that foreign cars
. * achieve higher mileage. To emphasize this, add a vertical line
. * at the means of the distributions
.
. * Compute the overall mean
. sum mpg

Variable | Obs Mean Std. dev. Min Max

+

mpg | 74 21.2973 5.785503 12 41

. local mpgall = `r(mean)'

. local mpgalltxt : di %9.1f `mpgall'

.
. * Compute mean for domestic cars
. sum mpg if foreign==0

Variable | Obs Mean Std. dev. Min Max

+

mpg | 52 19.82692 4.743297 12 34

. local mpgdom = `r(mean)'

. local mpgdomtxt : di %4.1f `mpgdom'

.
. * Compute mean for foreign cars
. sum mpg if foreign==1, meanonly

. local mpgfor = `r(mean)'

. local mpgfortxt : di %4.1f `mpgfor'

.
. * Add a vertical line to mark the overall mean and label the line
. * Superimpose a normal distribution.
. histogram mpg, frequency start(10) width(2.5) fcolor(none) lcolor(black) ///
> legend(on order(1 "All cars") rows(1)) addlabels ///
> normal xline(`mpgall',lcolor(black) lwidth(thick)) ///
> text(18 `mpgall' "Overall" "`mpgalltxt' mpg", orientation(vertical)) ///
> yscale(range(0 20)) name(hist1_3, replace)
(bin=13, start=10, width=2.5)

.
. * Add a vertical line to mark each of the two means and label them.
. * Use options -meanlines- and -meanopts- to place the vertical lines.
. * Superimpose a normal distribution on each histogram using options
. * -normalden- and -normopts-.
. iepowerdemo mpg, over(foreign) start(10) width(2.5) addlabels ///
> meanlines meanopts(lwidth(thick)) normalden normopts(lwidth(thick)) ///
> text(18 `mpgdom' "Domestic" "`mpgdomtxt' mpg", orientation(vertical)) ///
> text(18 `mpgfor' "Foreign" "`mpgfortxt' mpg", orientation(vertical)) ///
> yscale(range(0 20)) name(hist2_3, replace)

.
. * Compare the two histograms, this time on top of one another
. gr combine hist1_3 hist2_3, ycommon col(1) name(withlines, replace)
click to see the combined graph

.
. * For variables with right-skewed distributions, like -displacement-,
. * the option -xlog- plots the two histograms with respect to the log
. * of the variable being analyzed. The bars have equal widths on the log scale.
. * Options -meanlines- and -normalden- also use the log scale.
. * Stata's -histogram- comand does not have a comparable option.
. iepowerdemo displacement, over(foreign) addlabels xlog ///
> meanlines meanopts(lwidth(thick)) normalden normopts(lwidth(thick)) ///
> name(withxlog, replace)
click to see the combined graph

Returned results

The program returns the following results:

macros:
r(start) Starting value of the first bar
r(width) Width of the bins
r(barwidth) Width of the bars (by default equal to width of the bins)
r(mean1) Mean of observations in Group 0 as defined by ovar (With option meanlines)
r(mean2) Mean of observations in Group 1 as defined by ovar (With option meanlines)
r(normscale) Scaling factor for option normalden
r(maxbins) Maximum of the number of bins in the two histograms. Number of rows in r(bindata)

matrices:
r(bindata) Data on the heights and centers of both sets of bars

Requirements

Options xlog and powers require Nick Cox's program
niceloglabels.
See:

Cox, N. J. (2018) "Speaking Stata: Logarithmic binning and labeling", Stata Journal,
18:1

Author

Mead Over, Senior Fellow, Center for Global Development

Email: MOver@CGDev.Org if you observe any problems.