help for dstathttp://github.com/benjann/dstat/

Title

dstat -- Summary statistics and distribution functions

Syntax

Estimation

Summary statistics

dstat [summarize] [(stats)] varlist
[ (stats) varlist ... ]
[if] [in] [weight] [, options ]

Pairwise associations (wrapper for dstat summarize)

dstat pw varlist [if] [in] [weight] [,
statistic(stat)
options ]

Distribution functions

dstat subcmd varlist [if] [in] [weight] [, options ]

where subcmd is

density density function

pdf same as density

histogram histogram

proportion probability distribution

frequency same as proportion with option frequency

cdf cumulative distribution function

ccdf complementary CDF/survival function

quantile quantile function

lorenz lorenz curve

share percentile shares

tip TIP curve

varlist may contain factor variables (in most cases; an exception is dstat pw); see fvvarlist.

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

Postestimation

Replay results

dstat [, reporting_options ]

Draw graph

dstat graph
[, graph_options ]

Obtain (recentered) influence functions

predict {stub* |
newvar1 newvar2 ...} [if] [in]
[, predict_options ]

options Description

Main
nocasewise do not perform casewise deletion of observations

over(overvar[, opts]) compute
results for subpopulations defined by overvar; not allowed with dstat pw

total include results for total population

balance(spec) balance
covariates using reweighting; requires over()

reporting_options reporting options

novalues do not use values as coefficient names

vformat(fmt) format for coefficient name values

SE/VCE
vce(vcetype) variance estimation method;
vcetype may be none (skip variance estimation),
analytic, cluster clustvar, svy, bootstrap,
or jackknife

nose alias for vce(none)

[no]cov whether to store the full variance matrix or only the
standard errors

nobwfixed do not keep density bandwidth fixed across replications

generate(names[, opts]) store influence functions

rif(names[, opts]) store recentered influence functions

replace allow replacing existing variables

Quantile/density settings
qdef(#) quantile definition; # in {0,...,11}

hdquantile synonym for qdef(10) (Harrell-Davis quantiles)

hdtrim[(width)] apply trimming to the Harrell-Davis estimator

mquantile synonym for qdef(11) (mid-quantiles)

mqopts(options) options for mid-quantiles

density_options details of density estimation

Subcommand summarize
relax compute a statistic even if observations are out of support

by(varname) default secondary variable (for association and concentration measures)

pline(#|varname) default poverty line

pstrong use "strong" poverty definition

Subcommand pw
statistic(stat) type of association measure; default is statistic(corr)

lower lower-triangle elements only

upper upper-triangle elements only

diagonal include diagonal elements

Subcommand density
n(#) size of evaluation grid; default is n(99)

common use common evaluation points across subpopulations

[l|r]tight use tight evaluation grid

range(a b) use grid from a to b; default is to determine
grid range from data

at(numlist) custom grid of evaluation points

unconditional rescale results by relative size of subpopulation

Subcommand histogram
proportion estimate proportions instead of densities

percent estimate percent instead of densities

frequency estimate frequencies instead of densities

n(#|method) number of
histogram bins; default is n(sqrt)

ep use equal probability bins instead of equal width bins

common use common bin definitions across subpopulations

at(numlist) custom bin definitions

discrete treat data as discrete (calls dstat proportion)

unconditional rescale results by relative size of subpopulation

Subcommand proportion
percent estimate percent instead of probabilities

frequency estimate frequencies instead of probabilities

at(numlist) custom list of levels for which to estimate proportions

nocategorical allow variables that do not comply to Stata's rules
for factor variables

unconditional rescale results by relative size of subpopulation

Subcommands cdf and ccdf
percent estimate percent instead of probabilities

frequency estimate frequencies instead of probabilities

mid apply midpoint adjustment

floor use "lower-than" definition

n(#) size of evaluation grid; default is n(99)

common use common evaluation points across subpopulations

range(a b) use grid from a to b; default is to determine
grid range from data

at(numlist) custom grid of evaluation points

discrete treat data as discrete

ipolate obtain CDF by linear interpolation

unconditional rescale results by relative size of subpopulation

Subcommand quantile
n(#) size of evaluation grid; default is n(99)

range(a b) use grid within range from a to b, a and b
in [0,1]; default is range(0 1)

at(numlist) custom grid of evaluation points

Subcommand lorenz
percent report percent instead of proportions

generalized estimate generalized Lorenz curve

sum estimate total (unnormalized) Lorenz curve

gap estimate equality gap curve

absolute estimate absolute Lorenz curve

by(varname) estimate concentration curve with respect to specified variable

n(#) size of evaluation grid; default is n(101)

range(a b) use grid from a to b, a and b
in [0,1]; default is range(0 1)

at(numlist) custom grid of evaluation points

Subcommand share
proportion estimate proportions instead of densities

percent estimate percent instead of densities

generalized estimate generalized shares instead of densities

sum estimate totals instead of density

average estimate averages instead of densities

by(varname) estimate concentration shares with respect to specified variable

n(#) number of bins; default is n(20)

at(numlist) custom bin definitions

Subcommand tip
pline(#|varname) poverty line (required)

absolute estimate absolute TIP curve

pstrong use "strong" poverty definition

n(#) size of evaluation grid; default is n(101)

range(a b) use grid from a to b, a and b
in [0,1]; default is range(0 1)

at(numlist) custom grid of evaluation points

graph_options Description

merge merge results into a single subgraph

overlay synonym for merge

flip change how results are allocated to plots and subgraphs

[g|p]select(spec) select and order plots and subgraphs

cref include results from the the reference (sub)population

bystats[(arg)] group results by statistics; only relevant for dstat summarize

[no]step do/do not use step function; only relevant for dstat cdf

norefline suppress equality line; only relevant for dstat lorenz

refline(line_options) affect rendition of equality line; only relevant for dstat lorenz

coefplot_options options to be passed through to coefplot

predict_options Description

rif store recentered influence functions

scaling(total|mean) set the scaling of the influence functions

compact store influence functions in compact form; not allowed with balance() or unconditional

quietly do not display list of generated variables

Description

dstat provides a unified framework for the analysis of (univariate)
distributions. It supports the estimation of various distribution
functions (such as the PDF and CDF, quantiles, probabilities and
frequencies, histograms, Lorenz and concentration curves) and a large
collection of summary statistics (classical and robust measures of
location, scale, skewness, and kurtosis, measures of inequality,
concentration, and poverty).

dstat is an estimation command. Its results are stored
in e() and standard errors are provided for all
estimates. Variance-covariance estimation is based on influence functions
(Hampel 1974, Deville 1999) and fully supports complex survey data; see the vce()
option. Influence functions or recentered influence functions (RIFs) can be
generated for all statistics supported by dstat, either using the
generate() or rif() option, or
by applying predict after estimation.

dstat supports simultaneous estimation for multiple variables and
multiple subpopulations, and allows for covariate balancing or
standardization between subpopulations based on inverse probability
weighting (IPW) or entropy balancing. See the over()
and balance() options. Standard errors will take
account of the uncertainty induced by the balancing.

Basic functionality for graphing results is provided through the
graph() option or by applying command dstat graph
after estimation. dstat employs coefplot for
graphing, which needs to be installed on the system; see
ssc describe coefplot. Furthermore,
dstat requires the moremata package; see
ssc describe moremata.

Summary statistics

The syntax for specifying summary statistics and variables with
dstat summarize is

[ (stats) ] varlist [ (stats) varlist ... ]

where stats is a space-separated list of statistics as documented below
and varlist is a list of numeric variables, possibly including factor
variables (see fvvarlist). The default statistic is mean. Statistics
and variables may be repeated. dstat will rearrange the statistics by variables
and remove duplicate combinations.

The names of the statistics can be abbreviated and typed in lower or
uppercase letters (the names will be used as typed in the output; repeated
statistics with differently typed names will be treated as different
statistics). If abbreviation is ambiguous, the first matching statistic in
the sorted list of supported statistics will be used (with the following
exceptions: q or p can be used for quantile, d
for density, and f for freq). For example, to obtain the
geometric mean, you could type gmean, gm, GM, gMean,
gme, or any other variant including at least the first two letters.

Many of the statistics allow or require one or several arguments in
parentheses. Parentheses can be omitted if there is only a single numeric
argument and no space is included between the name and the argument. For
example, to obtain the 5% trimmed mean you could type trim(5) or
simply trim5 (omitting parentheses also works with numbers that
contain decimal places, that is, you could type trim5.5 to obtain the
5.5% trimmed mean; in this case, however, parentheses will be added in the
output).

stats Description

Points in the distribution
quantile(p) p/100 quantile; p in [0,100]

p(p) same as quantile()

hdquantile(p) p/100 Harrell/Davis (1982) quantile; p in [0,100]

mquantile(p) p/100 mid-quantile; p in [0,100]

density(x) kernel density at value x

hist(x1,x2) histogram density of data within (x1,x2]

[*]cdf(x) cumulative distribution (CDF) at value x; prefix * is empty for default,
m for mid-adjusted CDF, f for floor CDF

[*]ccdf(x) complementary CDF at value x; prefix * is empty for default,
m for mid-adjusted CCDF, f for floor CCDF

prop(x1[,x2]) proportion of data equal to x1 or within [x1,x2]

pct(x1[,x2]) percent of data equal to x1 or within [x1,x2]

freq[(x1[,x2])] overall frequency, or frequency of data equal to x1 or within [x1,x2]

count[(x1[,x2])] same as freq()

total[(x1[,x2])] overall total, or total of data equal to x1 or within [x1,x2]

min observed minimum (standard error set to zero)

max observed maximum (standard error set to zero)

range max-min (standard error set to zero)

midrange (min+max)/2 (standard error set to zero)

Location measures
mean arithmetic mean

gmean geometric mean (data must be positive)

hmean harmonic mean (data must be positive)

trim(p1[,p2]) trimmed mean with
p1/100 lower trimming and p2/100 upper trimming; p1 and p2 in
[0,50]; p2=p1 if omitted; default is p1=p2=25

winsor(p1[,p2]) winsorized mean with
p1/100 lower winsorizing and p2/100 upper winsorizing; p1 and p2 in
[0,50]; p2=p1 if omitted; default is p1=p2=25

median median; equal to q50

huber[(p)] Huber M estimate with gaussian efficiency
p in [63.7,99.9]; default is p=95

biweight[(p)] biweight M estimate with gaussian
efficiency p in [.01,99.9]; default is p=95

hl Hodges-Lehmann location measure (Hodges and Lehmann 1963)

Scale measures
sd[(df)] standard deviation; df applies
small-sample adjustment; default is df=1

variance[(df)] variance; default is df=1

mse[(x[,df])] mean squared deviation from value
x (mean squared error); default is x=0 and df=0

smse[(x[,df])] square-root of mean
squared deviation from value x; default is x=0 and df=0

iqr[n][(p1,p2)] interquantile range; default
is iqr(25,75) (interquartile range); specify iqrn for
normalized IQR, equal to 1/(invnormal(p2) - invnormal(p1)) * iqr

mad[n][(l[,t])] median (or mean if l!=0)
absolute deviation from the median (or mean if t!=0); specify madn for
normalized MAD, equal to 1/invnormal(0.75) * mad (or sqrt(pi/2) * mad if l!=0)

mae[n][(l[,x])] median (or mean if l!=0)
absolute deviation from value x; default is x=0; specify maen for
normalized MAE, equal to 1/invnormal(0.75) * mae or (sqrt(pi/2) * mae if l!=0)

md[n] mean absolute pairwise difference; equal to 2 * mean * gini; specify mdn for
normalized MD, equal to sqrt(pi)/2 * md

mscale[(bp)] M estimate of scale with breakdown
point bp in [1,50]; default is bp=50

qn Qn scale coefficient (Rousseeuw and Croux 1993)

Skewness measures
skewness skewness

qskew[(alpha)] quantile skewness (Hinkley 1975);
alpha in [0,50]; default is alpha=25

mc medcouple (Brys et al. 2004)

Kurtosis measures
kurtosis kurtosis

ekurtosis excess kurtosis; equal to kurtosis-3

qw[(alpha)] quantile tail weight; alpha
in [0,50]; default is alpha=25

lqw[(alpha)] left quantile tail weight; alpha
in [0,50]; default is alpha=25

rqw[(alpha)] right quantile tail weight;
alpha in [0,50]; default is alpha=25

lmc left medcouple tail weight measure (Brys et al. 2006)

rmc right medcouple tail weight measure (Brys et al. 2006)

Inequality measures
hoover Hoover index (Robin Hood index, Ricci-Schutz, Pietra index)

[a]gini[(df)] Gini coefficient; df applies
small-sample adjustment; default is df=0; specify agini for the absolute Gini coefficient

mld mean log deviation (MLD); equal to ge(0)

theil Theil index; equal to ge(1)

ge[(alpha)] generalized entropy (Shorrocks 1980)
with parameter alpha; default is alpha=1 (in which case
ge=theil)

atkinson[(epsilon)] Atkinson index with parameter
epsilon>=0; default is epsilon=1

cv[(df)] coefficient of variation; default is df=1;
cv(0)=sqrt(2*ge(2))

lvar[(df)] logarithmic variance; default is df=1

vlog[(df)] variance of logarithm; default is df=1

sdlog[(df)] standard deviation of logarithm; default is df=1

top[(p)] outcome share of top p percent; default
is p=10

bottom[(p)] outcome share of bottom p percent;
default is p=40

mid[(p1,p2)] outcome share of mid
p1 to p2 percent; default is p1=40 and p2=90

palma palma ratio; equal to top/bottom or sratio(40,90)

qratio[(p1,p2)] quantile ratio
q(p2)/q(p1); default is p1=10 and p2=90

sratio[(l1,u1,l2,u2)] percentile
share ratio; default is l1=0, u1=10, l2=90, u2=100; can also specify
sratio(u1,l2)

[*]lorenz(p) Lorenz ordinate, p in [0,100];
prefix * is empty for default, g for generalized, t for total,
a for absolute, e for equality gap

[*]share(p1,p2) percentile
share, p1 and p2 in [0,100]; prefix * is empty for default,
d for density, g for generalized, t for total, a for average

Inequality decomposition
d_gini[(by[,df])] where
d is b for the between-group Gini coefficient, or gw for the
weighted average of group-specific Gini coefficients; by specifies the group
variable (string allowed); default is as set by option by(); df applies
small-sample adjustment; default is df=0;
can also specify d_gini(df)

d_mld[(by)] where d is
b for the between-group MLD, w for the within-group MLD, or
gw for the weighted average of group-specific MLDs (gw_mld is
equivalent to w_mld); by as for d_gini

d_theil[(by)] where d
is b for the between-group Theil index, w for the
within-group Theil index, or gw for the weighted average of
group-specific Theil indices; by as for d_gini

d_ge[(by[,alpha])] where
d is b for the between-group generalized entropy, w for the
within-group generalized entropy, or gw for the weighted
average of group-specific generalized entropy; by as for d_gini;
can also specify d_ge(alpha)

d_vlog[(by[,df])] where
d is b for the between-group variance of logarithm, w for the
within-group variance of logarithm, or gw for the weighted average of
group-specific variance of logarithm; by as for d_gini;
can also specify d_vlog(df)

Concentration measures
gci[(by[,df])] Gini concentration index;
by specifies the sort variable; default is as set by option by();
df applies small-sample adjustment; default is df=0; can also
specify gci(df)

aci[(by[,df])] absolute Gini concentration index; syntax
as for gci

[*]ccurve(p[,by]) concentration curve ordinate,
p in [0,100]; prefix * is empty for default, g for generalized, t for total,
a for absolute, e for equality gap;
by as for gci

[*]cshare(p1,p2[,by]) concentration share,
p1 and p2 in [0,100]; prefix * is empty for default, d for density,
g for generalized, t for total, a for average;
by as for gci

Poverty measures
hcr[(pline)] head count ratio (i.e. proportion poor); pline specifies the
poverty line > 0; pline can be varname or #; default is as set by option pline()

[a]pgap[(pline)] poverty gap (proportion by which mean outcome of poor
is below pline); specify apgap for absolute poverty gap (pline - mean outcome of poor);
pline as for hci

[a]pgi[(pline)] poverty gap index; equal to hcr*pgap; specify
apgi for absolute poverty gap index, equal to hcr*apgap;
pline as for hci

fgt[(a[,pline])] Foster–Greer–Thorbecke index with a>=0
(Foster et al. 1984, 2010); default is a=0 (head count ratio); a=1 is equivalent to
pgi;
pline as for hci

sen[(pline)] Sen poverty index (Sen 1976; using the
replication invariant version of the index, also see Shorrocks 1995);
pline as for hci

sst[(pline)] Sen-Shorrocks-Thon poverty index
(see, e.g., Osberg and Xu 2008);
pline as for hci

takayama[(pline)] Takayama poverty index
(Takayama 1979);
pline as for hci

watts[(pline)] Watts index (see, e.g., Saisana 2014);
pline as for hci

chu[(a[,pline])] Clark-Hemming-Ulph poverty index with a in [0,100]
(Clark et al. 1981); default is a=50; a=0 is equivalent to
1-exp(-watts); a=100 is equivalent to fgt(1);
pline as for hci

[a]tip(p[,pline]) TIP ordinate,
p in [0,100]; specify atip() for absolute TIP ordinates;
pline as for hci

Association measures
corr[(by)] correlation coefficient;
by specifies the secondary variable; default is as set by option by()

slope[(by)] regression slope
(equal to mean difference if by is dichotomous); by as for corr

b[(by)] same as slope

cohend[(by[,df])] Cohen's d
(allowing unequal group sizes); df applies small-sample
adjustment; default is df=2; can also specify cohend(df);
by is assumed to be dichotomous (string allowed)

covar[(by[,df])] covariance; df applies small-sample
adjustment; default is df=1; can also specify covar(df);
by as for corr

rsquared[(by)] R squared, equal to corr^2;
by as for corr

spearman[(by)] Spearman's rank correlation;
by as for corr

taua[(by)] Kendall's tau-a (using fast algorithm by Newson 2006);
by as for corr

taub[(by)] Kendall's tau-b (using fast algorithm by Newson 2006);
by as for corr

somersd[(by)] Somers' D (using fast algorithm by Newson 2006);
by as for corr

gamma[(by)] Goodman and Kruskal's gamma (using fast algorithm by Newson 2006);
by as for corr

Categorical data (univariate)
hhi[n] Herfindahl–Hirschman index (Herfindahl index, Simpson index);
specify hhin for normalization (hhi-1/K)/(1-1/K), where
K is the number of categories

gimp[n] Gini impurity (Gini–Simpson index, Simpson's interaction index,
Blau index, Gibbs–Martin index); gimp = 1-hhi; gimpn = 1-hhin

entropy[(base)] Shannon entropy; base specifies
the base of the logarithm (default is natural logarithm)

hill[(q)] Hill number (true diversity,
effective number of species); q specifies the order of the diversity;
default is q=1 such that hill = exp(entropy); if q=0,
hill is equal to the observed number of categories

renyi[(q)] Rényi entropy;
equal to ln(hill(q)); default is q=1 such that
renyi = entropy

Categorical data (bivariate)
mindex[(by[,base])] mutual information index (M index);
by specifies the secondary variable (string allowed); default is as set by option by();
base specifies the base of the logarithm (default is natural logarithm);
can also specify mindex(base)

uc[l|r][(by)] uncertainty coefficient (H index);
ucl returns the asymmetric coefficient with respect to the left-hand
side variable (i.e. division by the entropy of the main variable),
ucr is with respect to the right-hand side variable (i.e. division by
the entropy of the secondary variable), uc returns the symmetric
uncertainty coefficient (weighted average of ucl and ucr);
by as for mindex

cramersv[(by)] Cramér's V;
by as for mindex

dissim[(by)] (generalized) dissimilarity index (Duncan's D);
by as for mindex

or[(by)] odds ratio; variables are
interpreted as true/false indicators (false if 0, else true); by as for mindex

rr[(by)] risk ratio; variables are
interpreted as true/false indicators (false if 0, else true); by as for mindex

Note on output formatting in Stata 15 (or in Stata 16 prior to the update of March 30, 2021): If
statistics with parameters in parentheses are requested, dstat summarize
may possibly display a somewhat disarranged output table. Type

. version 14: dstat summarize ...

to obtain an improved table in such a case.

Options

Main

nocasewise causes missing values to be excluded for each variable in
varlist individually. The default is to perform casewise deletion of
observations, that is, to restrict the sample to observations that are not
missing for any of the variables. If nocasewise is specified, the
overall estimation sample is still restricted by the if and in
qualifiers, the weights, and the variables specified in over() and
balance(), but not by missing values in the main varlist (or in
by(), by, pline(), or pline). For each variable
the subsample of all nonmissing values within the overall estimation sample
will then be used in the relevant computations.

over(overvar[, options])
computes results for each subpopulation defined by the values of
overvar. overvar must be integer and nonnegative. options
are as follows:

select(numlist) selects (and orders) subpopulations. numlist
specifies the values of the subpopulations to be included
and also determines the order of the subpopulations in the output. The basis
for estimation will always be the total sample including all subpopulations.

contrast[(#|lag|lead)] computes contrasts between
subpopulations or between subpopulations and the total population. If
contrast is specified without argument, the total population or
the first subpopulation (possibly after applying select())
will be used as the basis for the contrasts, depending on whether option
total has been specified or not. Alternatively, specify
the value of the reference subpopulation in parentheses (this may also be
a subpopulation that has been excluded by select()) or
type contrast(lag) or contrast(lead) to take stepwise contrasts
with respect to the previous or next subpopulation, respectively. contrast
implies common (if relevant).

The estimates from the reference (sub)population will be included among the
stored results (in logarithmic form if lnratio is specified), but
their display will be suppressed. Specify display
option cref to report these results in the output.

ratio requests that the contrasts are expressed as ratios. The
default is to express contrasts as differences. ratio implies
contrast.

lnratio requests that the contrasts are expressed as differences in
logarithms. The default is to express contrasts as raw differences. lnratio
implies contrast and takes precedence over ratio.

When applying lnratio you may also want to specify reporting option
eform to display results that are transformed back to
ratios. In fact, point estimates, standard errors, and confidence intervals
from lnratio with eform are identical to results
from ratio with option citype(log). An advantage of
lnratio, however, is that the null hypothesis for t-statistics and
p-values is ratio = 1 or, more precisely, ln(ratio) = 0 (i.e. no group
difference). For ratio the null hypothesis is ratio = 0, which
does not appear useful (this is why dstat suppresses t-statistics and
p-values in case of ratio). A disadvantage of lnrange is that it
cannot represent cases in which the comparison estimate and, hence, the ratio
is zero.

accumulate accumulates results across subpopulations
(running sum). Only one of contrast and accumulate is allowed.

Option over() is not supported by dstat pw.

total reports additional results across all subpopulations, including
subpopulations that may have been excluded by select(). total
only has an effect if over() is specified.

balance(spec) balances covariate distributions between
subpopulations using reweighting. balance() requires over(). The
syntax of spec is

[method:] varlist [, options]

where method is either ipw for inverse probability weighting based
on logistic regression (the default) or eb for entropy balancing using
mm_ebal() from moremata, and
varlist specifies the list of covariates to be balanced (factor-variable
notation is allowed). For information on inverse probability weighting
see, e.g., DiNardo et al. (1996) and teffects ipw. For entropy balancing see
Hainmueller (2012) and Section 3.8 in
Jann (2020). options are as follows:

reference(#) identifies the reference distribution. The default is
use the total across all subpopulations as the reference distribution,
including subpopulations that may have been excluded by select(). Specify
reference(#) to obtain the reference distributions from
observations for which overvar=#; this may also be a subpopulation
that has been excluded by select().

logit_options are options to be passed through to logit. logit_options
are only allowed if method is ipw.

btolerance(#), #>=0, specifies the tolerance for the entropy
balancing algorithm. The default is btolerance(1e-5). A warning
message is displayed if a balancing solution is not within the specified
tolerance. btolerance() is only allowed if method is eb.

noisily displays the output of the balancing procedure.

generate(newvar) stores the balancing weights in variable
newvar. This is useful if you want to check whether covariates have been
balanced successfully.

Balancing weights will only be computed once per subpopulation. If
casewise is specified, balancing will be based on the overall estimation
sample as defined in the description of the casewise option; the weights
will not be recomputed for each variable individually.

reporting_options are options affecting how results are reported. The options
are as follows:

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

citype(type) specifies the method for the computation of the
confidence interval limits. type can be:

normal normal CIs

logit logit transformed CIs; useful for statistics in [0,1]

probit probit transformed CIs; useful for statistics in [0,1]

atanh inverse hyperbolic tangent transformed CIs; useful for statistics in [-1,1]

log log transformed CIs; useful for statistics > 0

agresti Agresti-Coull CIs; useful for proportions

exact exact (Clopper-Pearson) CIs; useful for proportions

jeffreys Jeffreys CIs; useful for proportions

wilson Wilson CIs; useful for proportions

The default depends on subcommand and options. Use citype() to
override the default. For details on agresti, exact,
jeffreys, and wilson see the documentation of proportion.

dstat will store the confidence limits given level() and
citype() in e(ci). Replaying the results with different settings
will update e(ci). (In Stata 14, normal confidence intervals will be
displayed in the output table irrespective of the contents of e(ci).)

noheader suppress the output header.

notable suppresses the output table containing the estimated
coefficients. table enforces displaying the table.

[no]pvalues decides whether p-values and their test
statistics are reported in the coefficient table or not. The default is
nopvalues unless over(, contrast()) has been specified.

cref causes the estimates from the reference (sub)population to be
included in the coefficient tables. The default is to suppress these
results. cref is only relevant if over(, contrast()) has been
specified.

display_options are standard reporting options such as eform,
cformat(), or coeflegend; see [R] eform_option and
the Reporting options in [R] Estimation options.

graph[(graph_options)]
displays the results in a graph using coefplot. The coefficients
table will be suppressed in this case (unless option table is
specified). Alternatively, use command dstat graph to display the
graph after estimation.

novalues prevents using the values of the evaluation points as
coefficient names. This is not relevant for dstat summarize. If novalues
is specified, the coefficients will be named as stub#, where
# is consecutive number and stub is
d in case of dstat density,
h in case of dstat histogram,
p in case of dstat proportion,
c in case of dstat cdf and dstat ccdf,
q in case of dstat quantile,
l in case of dstat lorenz,
s in case of dstat share (and for dstat histogram and
dstat share the last coefficient, i.e. the upper limit of last bin, will be named
_ul).

vformat(fmt) sets the display format used to create coefficient names
from evaluation points. This is not relevant for dstat summarize. See
help format for available formats.

SE/VCE

vce(vcetype) determines how standard errors are computed. vcetype may be:

none
analytic
cluster clustvar
svy [svy_vcetype] [, svy_options ]
bootstrap [, bootstrap_options ]
jackknife [, jackknife_options ]

vce(none) omits the computation of standard errors. This saves computer
time.

vce(analytic), the default, computes standard errors based on
influence functions.

vce(cluster clustvar) computes standard errors based
on influence functions allowing for intragroup correlation, where
clustvar specifies to which group each observation belongs.

vce(svy) computes standard errors taking the survey design as set by
svyset into account. The syntax is equivalent to the syntax of the svy
prefix command; that is, vce(svy) is dstat's way to support
the svy prefix.

vce(bootstrap) and vce(jackknife) compute standard errors using
bootstrap or jackknife, respectively; see help vce_option.

nose is an alias for vce(none). nose overrides vce(analytic) and
vce(cluster), but has no effect if specified together with
vce(svy), vce(bootstrap), or vce(jackknife).

[no]cov determines wether the full variance-covariance matrix
of the estimates is stored in e(V), or whether only the standard
errors are stored in vector e(se). The default is cov (full
variance matrix) for subcommands summarize and pw, and
nocov (standard errors only) for all other subcommands. nocov
saves memory if the number of evaluation points is large (for example, if
you estimate the density using 400 points across two subpopulations, the
covariance matrix has 800 x 800 = 640'000 elements; the vector of standard
errors has only 800 elements). For vce(analytic) and
vce(cluster), option nocov also saves computer time (since the
computation of covariances is skipped; in the other cases, covariances are
removed after estimation). For vce(svy), option nocov also
removes auxiliary variance matrices such as e(V_srs). Note that
post-estimation commands that rely on covariances (or on auxiliary variance
matrices in case of svy) will not work after nocov has been
applied; specify option cov if you intend to use such post-estimation
commands (e.g., test or lincom) after subcommands other than
summarize or pw.

nobwfixed allows the bandwidth(s) for density estimation to vary
across replications. This is only relevant if density estimation is
requested (subcommand density or pdf; subcommand
summarize with at least one density() statistic), if the
bandwidth is not set to a specific value (or a list of specific values)
using option bwidth(), and if a replication technique is used for
standard error estimation, i.e. vce(bootstrap), vce(jackknife),
or vce(svy) with svy_vcetype other than
linearized. The default is to hold the bandwidth(s) fixed across
replications.

generate(names[, options]) stores the influence
functions that were used to compute the standard errors, where names
is either a list of (new) variable names or
stub* to create names stub1,
stub2, etc. options are rif to store RIFs,
scaling(total) or scaling(mean)
to determine the scaling, compact to merge the influence functions
across subpopulations, and quietly to suppress output; see
predict_options below.

rif(names[, options]) is an alias for
generate(names, rif [options]).

replace allows replacing existing variables.

Quantile/density settings

qdef(#) sets the quantile definition to be used when computing
quantiles, with # in {0,...,11}. The default is
qdef(2) (same as, e.g. summarize). Definitions 1-9 are as
described in Hyndman and Fan (1996), definition 0 is the "high" quantile,
definition 10 is the Harrell-Davis quantile (Harrell and Davis 1982),
definition 11 is the mid-quantile (Ma et al. 2011); see
mm_quantile() for more information. Apart from the
dstat quantile and statistic quantile(), option qdef() affects
all statistics that make use of quantiles (e.g. trim, winsor,
huber, biweight, mad, etc.).

hdquantile is a synonym for qdef(10) (Harrell-Davis
quantiles). Only one of hdquantile, mquantile, and qdef()
is allowed. The Harrell-Davis estimator typically leads to smoother
quantile functions than classical quantile definitions. Furthermore,
standard errors do not depend on density estimation and tend to be
more reliable than for other quantile definitions if there is heaping in the data.

hdtrim[(width)] applies trimming to the Harrell-Davis
quantile estimator as suggested by Akinshin (2021). If hdtrim is specified without
argument, the width of evaluation interval is set to 1/sqrt(n), where n
is the effective sample size. Alternatively, specify a custom width. Sensible values
for width lie between 0 and 1 (width>=1 uses the untrimmed estimator;
width<=0 sets the width to 1/sqrt(n)).

mquantile is a synonym for qdef(11) (mid-quantiles). Only one
of hdquantile, mquantile, and qdef() is allowed. The
mid-quantile estimator typically leads to smoother quantile
functions than classical quantile definitions. Ma et al. (2011) suggest
using the mid-quantile estimator for discrete data.

mqopts(options) provides additional settings for mid-quantiles that
are relevant for standard error estimation. options are as follows:

usmooth(#), with #<1, sets the degree of undersmoothing that is
applied when determining the sparsity function via density estimation.
The default is usmooth(0.2). The undersmoothing factor is computed as
n^(1/5) / n^(1/(5*(1-#)), where n is the effective sample size. Set # to 0
to omit undersmoothing; #<0 leads to oversmoothing. Note that
density_options have no effect on density estimation
for mid-quantiles.

cdf[(#)], with #>=0, determines the sparsity
function by differencing the ECDF instead of employing density
estimation. This may lead to somewhat more valid results in discrete data (i.e. data
with relatively few distinct levels), but results may be unreliable in
continuous data. Optional argument # sets the width of the integration
window that is used to interpolate across jumps in the ECDF (# is on
the probability scale; for example, a value of 0.01 is equivalent to a
window covering 1 percent of data mass). The default is # = 1 /
ceil(2 * n^(2/5)), where n is the effective sample size. Set #=0 to
omit integration (this corresponds to the formulas given in Ma et al. 2011;
the sparsity function will have sharp jumps).

density_options set the details of density
estimation. These settings are relevant for command
dstat density/pdf and statistic density() as well as for
the computation of influence functions that involve density
estimation (e.g., the influence function of a quantile). For more information
on density estimation see mm_density(),
Jann (2007), and
Wand and Jones (1995). The options are as follows:

bwidth(method[, adjust(#) rd])
specifies the type of automatic bandwidth selector for kernel density
estimation. Possible choices for method are:

silverman optimal of Silverman

normalscale normal scale rule

oversmoothed oversmoothed rule

sjpi Sheather-Jones solve-the-equation plug-in

dpi[(#)] Sheather-Jones direct plug-in,
where # specifies the number of stages of functional estimation;
default is 2

isj diffusion estimator bandwidth (Botev et al. 2010)

The default is bwidth(dpi(2)). Suboption adjust(#), with #>0, can be
used to adjust the automatic bandwidth by factor #. Suboption rd
applies relative-data correction to the automatic bandwidth (Cwik and Mielniczuk 1993).

bwidth(numlist) is an alternative to bwidth(method) and sets
the bandwidth to a specific value. If numlist contains multiple values,
the values are used one after the other across the variables and
subpopulations (recycling values if needed). The specified values must be larger
than zero.

kernel(kernel) specifies the kernel function. kernel may
be epanechnikov, epan2 (alternative Epanechnikov kernel
function), biweight, triweight, cosine,
gaussian, parzen, rectangle or triangle. The default
is kernel(gaussian).

adaptive(#) specifies the number of iterations used by the adaptive
kernel density estimator. The default is adaptive(0) (non-adaptive
density estimator).

exact causes the exact kernel density estimator to be used instead
of the binned approximation estimator. The exact estimator can be slow in large
datasets if the density is evaluated at many points.

napprox(#) specifies the grid size used by the binned approximation
density estimator (and by the data-driven bandwidth selectors). The default
is napprox(1024).

pad(#) specifies the padding proportion of the approximation grid. Default is
pad(0.1).

ll(#) specifies the lower boundary of the support of data and causes
boundary-correction to be applied to the density estimate. Error will be
returned if the data contains values smaller than #.

ul(#) specifies the upper boundary of the support of data and causes
boundary-correction to be applied to the density estimate. Error will be
returned if the data contains values larger than #.

boundary(method) sets the type of boundary correction. Choices are
renorm (renormalization method; the default), reflect (reflection method), or
lc (linear combination technique). This is only relevant if ll() or ul()
has been specified.

Subcommand summarize

relax continues computations even if there are observations outside
of the support for a specific statistic. Some statistics such as the
geometric mean, the MLD, or the Theil index require observations to be
within a specific domain (e.g. strictly positive). By default, dstat aborts
with error if observations violating such requirements are encountered. Specify
relax if you want to continue computations based on the valid
observations in such a case. Exclusion of invalid observations will be
applied to each statistic individually; that is, the invalid observations
will not be dropped from the overall estimation sample.

by(varname) specifies a default secondary variable for
inequality desomposition, concentration indices, and association measures.

pline(#|varname) specifies a default poverty line for poverty
measures, either as a single value or as a variable containing observation-specific
values.

pstrong selects the poverty definition to be applied (see Donaldson and
Weymark 1986). The default is to use the "weak" definition, that is, to treat
outcomes equal to the poverty line as non-poor. Specify pstrong to treat
these cases as poor ("strong" definition). The choice of definition is relevant
only for some of the poverty measures.

Subcommand pw

statistic(stat) selects the association measure to be
computed. stat may be any statistic listed under
Association measures or
Categorical data (bivariate)
in the above table of summary statistics (omitting argument
by). statistic(corr) is the default. Type, for example,
statistic(taub) to compute Kendall's tau-b. Arguments other than
by can be provided in parentheses as usual; for example, type
statistic(mindex(2)) to compute the M index with base 2.

Most supported statistics are symmetric in the sense that the upper and
lower triangles of the association matrix (i.e. the matrix of pairwise
associations among the variables in varlist) contain the same results
(i.e. the association between X and Y is the same as the association beteen
Y and X). For asymmetric statistics (e.g. slope) the column
(i.e. equation) variable is treated as the dependent variable.

lower requests that the lower-triangle elements of the association
matrix be computed. The default is to compute both the lower-triangle elements
and the upper-triangle elements.

upper requests that the upper-triangle elements of the association
matrix be computed. The default is to compute both the lower-triangle elements
and the upper-triangle elements.

diagonal includes the diagonal elements of the association
matrix (associations of the variables with themselves). By default,
diagonal elements are omitted.

Subcommand density

n(#) sets the number of points for which the density is to
be estimated. A regular grid of # points spanning the
data range (within subpopulation; plus some padding) will be used. The
default is n(99). Only one of n() and at() is allowed.

common requests that a common set of evaluation points is used across
all subpopulations. The default is to determine the evaluation points based on
the data range within subpopulation. If common is specified, the
evaluation points will be based on the data range in the total population.

[l|r]tight omits padding when determining the evaluation
grid. Specify tight to omit padding on both sides, that is, to use a grid
from the observed minimum to the observed maximum of the data. Specify
ltight to omit padding only on the left, that is, to use the observed
minimum as the lower bound of the grid. Specify rtight to omit padding
only on the right, that is, to use the observed maximum as the upper bound
of the grid. Option tight has no effect if range() or at()
is specified.

range(a b) specifies the range of the evaluation grid. The default is
is to determine the range of the grid from the data; see option n(). Option
range() overrides common. Only one of range() and
at() is allowed.

at(numlist) specifies a custom grid of evaluation points. Only
one of n() and at() is allowed.

unconditional rescales results such that the
density function integrates to the relative size of the subpopulation
instead of 1. This is only relevant if option over() has been
specified.

Subcommand histogram

proportion estimates proportions instead of densities.

percent estimates percent instead of densities.

frequency estimates frequencies instead of densities.

n(#|method) selects
(the method to determine) the number of histogram bins. Specify n(#)
to use # bins. Alternatively, specify n(method) to determine the
number of bins automatically, where method may be one of the following:

sqrt modified square-root choice as used by histogram

sturges Sturges' formula

rice Rice rule

doane Doane's formula

scott Scott's normal reference rule

fd Freedman–Diaconis' choice

ep power-maximizing number of equiprobable bins

The default is n(sqrt); see help histogram for details on this
rule. For the other rules see http://en.wikipedia.org/wiki/Histogram. The generated
bins will span the range of the observed data (within subpopulation).

ep uses equal probability bins (approximately) instead of equal
width bins.

common requests that a common set of bin definitions is used across
all subpopulations. The default is to determine the number of bins and the
bin boundaries based on the data within subpopulation. If common is
specified, the bin definitions will be based on the data in the total population.

at(numlist) specifies custom cutpoints for the bins (in ascending
order). If numlist contains n numbers, n-1 bins will be
created. Note that the constructed bins will cover all data only if the first
cutpoint is smaller than or equal to the minimum of the data and the last
cutpoint is larger than or equal to the maximum (dstat does not check
this condition and does not display a warning if the condition is violated).

discrete treats the data as discrete and estimates the probability of
each observed level in the data. The option is implemented as a
redirection to subcommand proportion with option nocategorical. Options
n() and ep are not allowed together with discrete; the other
options are as described for subcommand proportion.

unconditional rescales results by the relative size of
the subpopulation. This is only relevant if option over() has been
specified. unconditional is not allowed together with frequency.

Subcommand proportion

percent estimates percent instead of proportions.

frequency estimates frequencies instead of proportions.

at(numlist) provides a custom list of levels for which to estimate
proportions. The default is to use all levels observed in the data (across
subpopulations).

nocategorical allows outcome variables that do not comply to
Stata's rules for factor variables (e.g. variables that contain negative
or noninteger values). This also affects how the coefficients are
labeled in the output.

unconditional rescales proportions by the relative size of
the subpopulation. This is only relevant if option over() has been
specified. unconditional is not allowed together with frequency.

Subcommands cdf and ccdf

percent estimates percent instead of proportions.

frequency estimates frequencies instead of proportions.

mid applies midpoint adjustment to the estimated CDF. By default, the
CDF at evaluation point x is defined as the proportion of data that is
lower than or equal to x. If mid is specified, the CDF at
point x is reduced by one half the proportion of data equal to
x. mid only has an effect on the results for evaluation points
that have a match in the data (unless ipolate is specified; see below). Only
one of mid and floor is allowed.

floor defines the CDF at evaluation point x as the proportion
of data that is lower than x, rather than lower than or equal to
x. floor only has an effect on the results for evaluation points
that have a match in the data (unless ipolate is specified;
see below). Only one of floor and mid is allowed.

n(#) sets the number of points at which the CDF is to be
evaluated. A regular grid of # points spanning the
observed data range (within subpopulation) will be used. The default is
n(99). Only one of n() and at() is allowed.

common requests that a common set of evaluation points is used across
all subpopulations. The default is to determine the evaluation points based on
the data range within subpopulation. If common is specified, the
evaluation points will be based on the data range in the total population.

range(a b) specifies the range of the evaluation grid. The default is
is to determine the range of the grid from the data; see option n(). Option
range() overrides common. Only one of range() and
at() is allowed.

at(numlist) provides a custom list of points at which to evaluate
the CDF. Only one of n() and at() is allowed.

discrete treats the data as discrete. In this case, the CDF will
be estimated at each level observed in the data
(across all subpopulations). Option n() is not allowed if
discrete is specified.

ipolate obtains the estimates of the CDF by linearly interpolating
the values of the empirical CDF. That is, the estimates will lie
on the curve that linearly connects the points of the CDF if the CDF is
evaluated at each observed level in the data (within subpopulation; options
mid and floor have an effect on the location of these
points). By default, the estimates of the CDF are obtained according to the definitions
described above (see mid and floor).

unconditional rescales results by the relative size of
the subpopulation. This is only relevant if option over() has been
specified. unconditional is not allowed together with frequency.

Subcommand quantile

n(#) sets the number of quantiles to be computed. A regular grid
of # points from a+h to b-h will be used,
with h = (b-a)/(#+1) and a and b
as set by option range(). The default is
n(99). Only one of n() and at() is allowed.

range(a b) specifies the range of the evaluation grid, a and
b in [0,1]. The default is range(0 1). Only one of range()
and at() is allowed.

at(numlist) provides a custom list of probabilities at which to
compute quantiles. The specified values must be within [0,1]. Only one of
n() and at() is allowed.

Subcommand lorenz

percent expresses results in percent instead of
proportions. percent is not allowed with
generalized or absolute.

generalized estimates the generalized Lorenz curve.

sum estimates the total (unnormalized) Lorenz curve.

gap estimates the equality gap curve.

absolute estimates the absolute Lorenz curve.

by(varname) estimates the concentration curve with respect to
varname instead of the Lorenz curve.

n(#) sets the number of ordinates to be estimated. A regular grid
of # values from a to b will be used, with a and b
as set by option range(). The default is n(101). Only one of
n() and at() is allowed.

range(a b) specifies the range of the evaluation grid, a and
b in [0,1]. The default is range(0 1). Only one of range()
and at() is allowed.

at(numlist) provides a custom list of points at which to
estimate Lorenz ordinates. The specified values must be within [0,1]. Only one of
n() and at() is allowed.

Subcommand share

proportion estimates proportions instead of densities.

percent estimates percent instead of densities.

generalized estimates generalized shares instead of densities.

sum estimates totals instead of densities.

average estimates averages instead of densities.

by(varname) estimates the concentration shares with respect to
varname.

n(#) sets the number of bins. A regular grid of # bins between
0 an 1 will be used. The default is n(20).

at(numlist) specifies custom cutpoints for the bins (in ascending
order). The specified values must be within [0,1]. If numlist contains
n numbers, n-1 bins will be created. Note that the constructed
bins will cover all data only if the first cutpoint is 0 and the last
cutpoint is 1.

Subcommand tip

pline(#|varname) specifies the poverty line, either as a single
value or as a variable containing observation-specific
values. Option pline() is required.

absolute estimates the absolute TIP curve. Default is to estimate the
relative TIP curve.

pstrong selects the poverty definition to be applied (see Donaldson and
Weymark 1986). The default is to use the "weak" definition, that is, to treat
outcomes equal to the poverty line as non-poor. Specify pstrong to treat
these cases as poor ("strong" definition).

n(#) sets the number of ordinates to be estimated. A regular grid
of # values from a to b will be used, with a and b
as set by option range(). The default is n(101). Only one of n()
and at() is allowed.

range(a b) specifies the range of the evaluation grid, a and
b in [0,1]. The default is range(0 1). Only one of range()
and at() is allowed.

at(numlist) provides a custom list of points at which to
estimate the ordinates. The specified values must be within [0,1]. Only one of
n() and at() is allowed.

Graph options

merge causes results from different equations to be placed
in a single graph (as separate "plots", i.e. as separate series of results
displayed in a common style) instead of creating a separate subgraph for
each equation. This is only relevant if the results contain multiple
equations and if the equations are one-dimensional
(e.g. subpopulations); merge has no effect if the
equations are two-dimensional (subpopulations and variables).

overlay is a synonym for merge.

flip changes how results are allocated to plots and subgraphs. This is
only relevant if the results contain multiple equations. If the equations
are two-dimensional (subpopulations and variables), the default is to
create subgraphs by the secondary dimension (variables) and create
"plots" (series of results displayed in a common style) within subgraphs by
the main dimension (subpopulations). Specify flip to reverse this
behavior. If equations are one-dimensional, flip has the same effect
as merge.

[g|p]select(numlist|reverse)
selects and orders subgraphs and plots within
subgraphs. numlist specifies the indices of the subgraphs or plots to
be included. For example, in a situation where the default graph has three
subgraphs (containing one plot each), you could type select(3 1) to
omit the 2nd subgraph and reverse the order such that the 3rd subgraph comes
first. Instead of providing numlist, type select(reverse)
to reverse the order of subgraphs or plots.

select() applies to both, subgraphs and plots within subgraphs. If a
graph contains multiple subgraphs and multiple plots within subgraphs, use option
gselect() to select and order subgraphs, and use option pselect()
to select and order plots.

select(), gselect(), and pselect() only have an effect if
there are multiple elements to choose from. That is,
single subgraphs or single plots will always be displayed, irrespective of
what you type in these options.

cref causes results from the reference (sub)population to be
included in the graph. The default is to suppress these
results. cref is only relevant if over(, contrast()) has been
specified.

bystats[(main|secondary)] treats coefficients as equations and
equations as coefficients. This is only relevant after
dstat summarize and only has an effect if the results contain multiple
equations. The effect of bystats typically is that results are grouped
by statistics rather than by subpopulations or variables (the option may
also have the opposite effect depending on how exactly dstat returned its
results). Optional type bystats(main) (the default) or
bystats(secondary) to specify wether coefficients should replace the
main dimension or the secondary dimension of the equations, respectively. This
is only relevant if the equations contain two dimensions
(subpopulations and variables).

[no]step enforces or prevents using a step function to display
the distribution function. This is only relevant after dstat cdf
and dstat ccdf. The default is to display the CDF as a step function
if option discrete (but not ipolate) has been specified, and
else use straight lines. Specify nostep or step, respectively,
to override the default.

norefline suppresses the equality line (diagonal) that is printed
when plotting results from dstat lorenz (unless option
generalized, gap, or absolute has been specified).

refline(line_options) specifies options to affect the rendition of
the equality line; see line_options. This is only relevant after
dstat lorenz.

coefplot_options are options to be passed through to
coefplot. Use these options, for example, to set titles and axis
labels or to affect the overall look and size of the graph. The options can
also be used to change the rendering of the plotted results (e.g. colors,
line patterns, marker symbols, etc.). If a graph contains multiple plots
(multiple series of results displayed in a common style), option
p#() can be used to address the #th plot. For example,
you could type p2(recast(dropline) pstyle(p5) noci) to change the
plottype of the 2nd plot to dropline, change its pstyle
to p5 (instead of the default p2), and suppress its confidence
intervals.

Predict options

rif generates recentered influence functions (RIFs) instead of regular
influence functions. RIFs are defined such that their mean is equal to the
statistic in question (Firpo et al. 2009; also see Rios-Avila 2020)
and the standard error of the mean (as computed by
command mean) provides an estimate of the standard error of the
statistic. The default is to store influence functions defined in a way such
that their total is zero and the standard error of the total (as computed by
command total) provides an estimate of the standard error of the
statistic.

scaling(spec) determines the scaling of the generated
influence functions. spec can be total (scaling for
analysis by total) or mean (scaling for analysis by
mean). The default is scaling(total) for regular influence
functions and scaling(mean) for recentered influence functions
(i.e. if option rif is specified).

compact generates influence functions in compact form. compact
only has an effect if over() has been specified and is not allowed
with balance(), unconditional, over(, contrast), or
over(, accumulate). Furthermore, compact is not supported
for statistics that are not normalized by the sample size (i.e. frequencies
or totals).

The default is to generate one influence function for each single parameter
estimated by dstat. If over() is specified, this means that
each statistic in each subpopulation has its own influence
function. Specify compact to merge the influence functions across
subpopulations. In this case, over() has to be specified when
analyzing the influence functions.

quietly suppresses the list of generated variables that is displayed by
default.

Note that weights, if specified, will not be incorporated into the
influence functions, so that the weights can be
applied when analyzing the influence functions. The influence functions do,
however, incorporate the balancing weights (net of base weights)
from option balance().

Furthermore, note that dstat generates scores instead of
influence functions for statistics that are not normalized by the sample
size (i.e. frequencies or totals). The difference is that the total of an influence function
across the estimation sample is zero, whereas the total of the score is
equal to the statistic in question. Returning scores for frequencies and totals
ensures that standard errors obtained by total will be correct for these
statistics in complex survey designs.

Examples

Summary statistics

dstat summarize supports a long list of summary statistic. For example, the following
command computes the arithmetic mean, geometric mean, median, 5% trimmed mean, 5%
winsorized mean, 95%-efficiency Huber M estimate, and Hodges-Lehmann location of wages
for unionized and nonunionized workers:

. sysuse nlsw88, clear

. dstat (mean gmean median trim5 winsor5 huber95 hl) wage, over(union)

Results can be computed for multiple variables, and statistics may
differ across variables. The following command estimates the
Gini coefficient, mean log deviation, and variance of logarithms of wages,
the means of working hours and work experience, as well as the proportion of whites
(race=1), blacks (race=2), and others (race=3):

. dstat (gini mld vlog) wage (mean) hours ttl_exp (pr1 pr2 pr3) race

Distribution functions

dstat supports the estimation of several types of distribution
functions. For example, the density function of wages by union status can
be obtained as follows:

. sysuse nlsw88, clear
. dstat density wage, over(union) ll(0) graph

Option graph has been specified so that a graph is drawn. The coefficients
table will be suppressed in this case; specify option table to enforce displaying the
coefficients table. An alternative would be to
omit the graph option and then type dstat graph after estimation.
Option ll(0) has been specified because wages can only be positive. The option
causes density estimation to be restricted to the positive domain
and applies appropriate boundary correction.

In the example above, the density estimates for unionized and nonunionized
workers have been displayed in two separate subgraphs. Apply graph option
merge to overlay the two curves in a single coordinate system:

. dstat graph, merge

To see how the overall wage distribution is composed by the two
groups, we can, for example, rescale the density estimates by group size
using option unconditional and include the total density using option
total:

. dstat density wage, over(union) total unconditional ll(0) graph(merge)

Covariate balancing

The balance() option can be used to adjust results for differences in
covariate distributions when comparing subpopulations. By default,
dstat employs inverse probability weighting (IPW) to balance the
covariates and obtains the relevant reference distribution from the total
sample. That is, in each subpopulation the covariate distribution is
adjusted such that it resembles the covariate distribution observed in the
total population. Use the reference() suboption to change the reference
distribution.

For example, the mean difference of average wages between nonunionized and
unionized workers is as follows:

. sysuse nlsw88, clear
. dstat (mean) wage, over(union)
. lincom _b[1.union]-_b[0.union]

Controlling for education, working hours, work experience and tenure reduces
the mean difference by about a third (note that there has been a small change
in the estimation sample due to missing values; for a more valid comparison,
the raw difference should be computed based on the same sample as the
balanced difference):

. dstat (mean) wage, over(union) balance(grade hours ttl_exp tenure)

. lincom _b[1.union]-_b[0.union]

To evaluate how successful the balancing was, you can use suboption generate()
to store the balancing weights:

. dstat (mean) wage, over(union) balance(grade hours ttl_exp tenure, generate(wbal))

. tabstat grade hours ttl_exp tenure if wage<., by(union) (unbalanced)

. tabstat grade hours ttl_exp tenure [aw=wbal], by(union) (balanced)

. drop wbal

The balancing has only been partially successful. Perfect balancing
(with respect to the means) can be achieved by entropy balancing:

. dstat (mean) wage, over(union) balance(eb: grade hours ttl_exp tenure, generate(wbal))

. tabstat grade hours ttl_exp tenure [aw=wbal], by(union)

. drop wbal

Note that, instead of using lincom after estimation, you can also obtain group
differences directly using suboption contrast within the over()
option:

. dstat (mean) wage, over(union, contrast(0)) balance(eb:grade hours ttl_exp tenure)

Influence functions

dstat can store the influence functions or the recentered
influence functions (RIFs) of the computed statistics. The influence functions
or RIFs can then be used in further analyses. Here is an example of
RIF regressions (Firpo et al. 2009) for the Gini coefficient and the
mean log deviation:

. sysuse nlsw88, clear
. dstat (gini mld) wage, rif(gini mld)
. regress gini union south smsa, robust
. regress mld union south smsa, robust

The RIFs are also useful for decomposition analysis. In the following example
the wage gap between unionized and non-unionized workers is decomposed into
a part explained by differences in covariates and a residual (unexplained) part, using
reweighting based on entropy balancing and using the covariate distribution
of unionized workers as the reference distribution:

. dstat (mean) wage, over(union) balance(eb: grade hours ttl_exp tenure, reference(1)) rif(RIF0c)

. dstat (mean) wage if e(sample), over(union) rif(RIF0 RIF1)

. generate difference = RIF1 - RIF0
. generate explained = RIF0c - RIF0
. generate unexplained = RIF1 - RIF0c
. mean difference explained unexplained

Methods and formulas

(under construction)

Saved results

Depending on options, dstat stores a selection of the following
results in e().

Scalars

e(N) number of observations

e(W) sum of weights

e(N_over) number subpopulations

e(N_clust) number of clusters

e(N_vars) number of variables

e(N_stats) number of (unique) summary statistics

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

e(k_omit) number of omitted estimates

e(df_r) sample degrees of freedom

e(qdef) quantile definition

e(adaptive) number of iterations of adaptive density estimator

e(napprox) size of density estimation grid

e(pad) padding of density estimation grid

e(ll) lower boundary of the data support (density estimation)

e(ul) upper boundary of the data support (density estimation)

e(level) confidence level

Macros

e(cmd) dstat

e(subcmd) summarize, density, histogram, proportion, cdf, ccdf, quantile, lorenz, or share

e(predict) dstat predict

e(cmdline) command as typed

e(depvar) name(s) of analyzed variable(s)

e(nocasewise) nocasewise or empty

e(over) name of overvar

e(over_namelist) values of subpopulations

e(over_labels) labels of subpopulations

e(over_select) values of selected subpopulations

e(over_contrast) total, #, lag, lead, or empty

e(over_ratio) ratio or lnratio or empty

e(over_accumulate) accumulate or empty

e(over_fixed) fixed or empty

e(total) total or empty

e(unconditional) unconditional or empty

e(balance) list of balancing variables

e(balmethod) balancing method

e(balref) balancing reference

e(balopts) options passed through to balancing procedure

e(bwmethod) bandwidth selection as specified in bwidth()

e(kernel) kernel as specified in kernel()

e(exact) exact or empty

e(boundary) boundary correction method

e(hdtrim) hdtrim() as specified

e(mqopts) mqopts() as specified

e(novalues) novalues or empty

e(vformat) display format specified in vformat()

e(stats) list of (unique) summary statistics

e(slist) normalized specification of statistics and variables

e(percent) percent or empty

e(proportion) proportion or empty

e(frequency) frequency or empty

e(mid) mid or empty

e(floor) floor or empty

e(ipolate) ipolate or empty

e(discrete) discrete or empty

e(categorical) categorical or empty

e(ep) ep or empty

e(gap) gap or empty

e(generalized) generalized or empty

e(absolute) absolute or empty

e(average) average or empty

e(relax) relax or empty

e(byvar) name of variable specified in by()

e(pline) poverty line variable specified in pline()

e(pstrong) pstrong or empty

e(generate) name(s) of generated variable(s)

e(clustvar) name of cluster variable

e(vce) vcetype specified in vce()

e(vcetype) title used to label Std. Err.

e(citype) type confidence interval stored in e(ci)

e(wtype) weight type

e(wexp) weight expression

e(title) title in estimation output

e(properties) b or b V

Matrices

e(b) estimates

e(V) variance-covariance matrix of estimates

e(se) standard errors of estimates

e(ci) confidence intervals of estimates

e(nobs) number of observations per estimate

e(sumw) sum of weights per estimate

e(at) evaluation points of distribution function

e(omit) indicator for omitted estimates

e(id) subpopulation IDs of estimates

e(cref) contrast reference indicators

e(bwidth) kernel bandwidth(s) of density estimation

e(_N) number of observations by subpopulation

e(_W) sum of weights by subpopulation

Functions

e(sample) estimation sample

If vce() is svy, bootstrap, or jackknife, additional
results are stored in e(); see svy, bootstrap, and
jackknife, respectively.

References

Akinshin, A. (2021). Trimmed Harrell-Davis quantile estimator based on the
highest density interval of the given
width. arXiv:2111.11776 [stat.ME].

Botev, Z.I., J.F. Grotowski, and D.P. Kroese (2010). Kernel density
estimation via diffusion. Annals of Statistics
38(5): 2916-2957. DOI: 10.1214/10-AOS799.

Brys, G., M. Hubert, A. Struyf (2004). A Robust Measure of Skewness.
Journal of Computational and Graphical Statistics 13(4): 996-1017.

Brys, G., M. Hubert, A. Struyf (2006). Robust measures of tail weight.
Computational Statistics & Data Analysis 50: 733-759.

Clark, S., R. Hemming, D. Ulph (1981). On Indices for the Measurement of Poverty. The
Economic Journal 91(362): 515-526

Cwik, J., J. Mielniczuk (1993). Data-dependent bandwidth choice for a grade density
kernel estimate. Statistics & Probability Letters 16: 397-405.

Deville, Jean-Claude (1999). Variance estimation for complex statistics and
estimators: Linearization and residual techniques. Survey Methodology 25: 193-203.

DiNardo, J.E., N. Fortin, T. Lemieux (1996). Labour Market Institutions and
the Distribution of Wages, 1973-1992: A Semiparametric Approach. Econometrica
64(5): 1001-1046.

Donaldson, D., J.A. Weymark (1986). Properties of Fixed-Population Poverty Indices. International
Economic Review 27(3): 667-688.

Firpo, S., N.M. Fortin, T. Lemieux (2009). Unconditional Quantile
Regressions. Econometrica 77: 953-973.

Foster, J., J. Greer, E. Thorbecke (1984). A class of decomposable poverty
measures. Econometrica 52(3): 761-766.

Foster, J., J. Greer, E. Thorbecke (2010). The Foster–Greer–Thorbecke (FGT) poverty measures: 25 years
later. The Journal of Economic Inequality 8: 491–524.

Hainmueller, J. (2012). Entropy Balancing for Causal Effects: A Multivariate
Reweighting Method to Produce Balanced Samples in Observational Studies.
Political Analysis 20: 25-46.

Hampel, F.R. (1974). The Influence Curve and Its Role in Robust
Estimation. Journal of the American Statistical Association 69: 383-393.

Harrell, F.E., C.E. Davis (1982). A New Distribution-Free Quantile Estimator. Biometrika
69: 635-640.

Hinkley, D. V. (1975). On power transformations to symmetry. Biometrika
62(1): 101-111.

Hodges, Jr., J.L., E.L. Lehmann (1963). Estimates of location based on
rank tests. Annals of Mathematical Statistics 34(2): 598-611.

Hyndman, R.J., Fan, Y. (1996). Sample Quantiles in Statistical
Packages. The American Statistician 50: 361-365.

Jann, B. (2007). Univariate kernel density
estimation. DOI: 10.7892/boris.69421.

Jann, B. (2020). Influence functions continued. A framework for estimating standard errors in
reweighting, matching, and regression adjustment. University of Bern Social Sciences
Working Papers 35. Available from
http://ideas.repec.org/p/bss/wpaper/35.html.

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

Newson, R. (2006). Efficient Calculation of Jackknife Confidence
Intervals for Rank Statistics. Journal of Statistical Software 15(1).

Osberg, L., K. Xu (2008). How Should We Measure Poverty in a Changing World? Methodological
Issues and Chinese Case Study. Review of Development Economics 12(2): 419–441.

Rios-Avila, F. (2020). Recentered influence functions (RIFs) in Stata: RIF
regression and RIF decomposition. The Stata Journal 20(1): 51-94.

Rousseeuw, P.J., C. Croux (1993). Alternatives to the Median
Absolute Deviation. Journal of the American Statistical Association
88(424): 1273-1283.

Saisana M. (2014). Watts Poverty Index. In: A.C. Michalos (ed). Encyclopedia of Quality of Life and Well-Being
Research. Dordrecht: Springer. DOI: 10.1007/978-94-007-0753-5_3197

Sen, A. (1976). Poverty: An Ordinal Approach to Measurement. Econometrica 44(2): 219-231.

Shorrocks, A.F. (1980). The Class of Additively Decomposable Inequality Measures. Econometrica 48(3): 613-625.

Shorrocks, A.F. (1995). Revisiting the Sen Poverty Index. Econometrica 63(5): 1225-1230.

Takayama, N. (1979). Poverty, income inequality, and their measures: Professor Sen's
axiomatic approach reconsidered. Econometrica 47(3): 747-759.

Wand, M.P., M.C. Jones (1995). Kernel Smoothing. London: Chapman and Hall.

Author

Ben Jann, University of Bern, ben.jann@unibe.ch

Thanks for citing this software as follows:

Jann, B. (2020). dstat: Stata module to compute summary statistics and
distribution functions including standard errors
and optional covariate balancing. Available from
http://ideas.repec.org/c/boc/bocode/s458874.html.

Also see

Online: help for
centile,
ci,
correlate,
cumul,
histogram,
kdensity,
mean,
pctile,
proportion,
spearman,
summarize,
table,
tabstat,
tabulate,
teffects ipw,
total

Packages from the SSC Archive (type ssc describe name for
more information):
akdensity,
apoverty,
catplot,
cdfplot,
ci2,
dfl,
distplot,
duncan,
eqprhistogram,
fre,
glcurve,
ineqdeco,
kdens,
kmatch,
lorenz,
moremata,
povdeco,
poverty,
pshare,
reldist,
rif,
robstat,
seg,
somersd,
sumdist,
svygei_svyatk,
svylorenz