help cdisthttp://github.com/benjann/cdist/

Title

cdist -- Counterfactual distribution estimation and decomposition of group differences

Syntax

Estimation

cdist [estimate] depvar [indepvars] [if] [in] [weight],
by(groupvar)
[
options
]

indepvars may contain factor variables; see fvvarlist.

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

Report decomposition after estimation

cdist decomp
[, decomp_options
reporting_options ]

Report linear combinations of results after estimation

cdist lincom explist
[, reporting_options ]

where explist is

([name:]exp) [([name:]exp) ... ]

with exp as a linear combination of equation names and name as an
optional name for the result to be used in the output (exp will
be used as name if name is omitted). Parentheses can be omitted if there are no
spaces in a specification. Unless restricted by keep() or
drop(), the equation names that can be used in
exp are as follows:

obs0 observed distribution of group 0

fit0 fitted distribution of group 0

adj0 composition-adjusted distribution of group 0

loc0 composition-adjusted and location-shifted distribution of group 0; only available if
jmp has been specified

obs1 observed distribution of group 1

fit1 fitted distribution of group 1

adj1 composition-adjusted distribution of group 1

loc0 composition-adjusted and location-shifted distribution of group 1; only available if
jmp has been specified

For example, type

. cdist lincom (Delta: fit0 - fit1) (Char: fit0 - adj0) (Coef: adj0 - fit1)

to decompose the group difference (Delta) into a part due to differences in
characteristics (Char) and a part due to differences in coefficients
(Coef). This is equivalent to the default decomposition obtained by
cdist decomp.

options Description

Main
by(groupvar) specifies two groups; by() is required

swap swap the groups

pooled adjust to the pooled characteristics distribution

jmp[(type)] include location-shifted
counterfactuals

Target statistics
statistics(stats) statistics to be calculated

islog use exp(depvar) to compute inequality statistics

percentile[(spec)] calculate
percentiles; alternative to statistics()

quantile[(spec)] calculate
quantiles; alternative to statistics()

pdf[(spec)] calculate
density function; alternative to statistics()

cdf[(spec)] calculate
distribution function; alternative to statistics()

qdef(#) quantile definition; # in {0,..,11}

Results
decomp[(options)] report decomposition

lincom(explist) report specified
linear combinations; see cdist lincom above

keep(eqlist) keep specified equations; may use * and ? wildcard characters

drop(eqlist) drop specified equations; may use * and ? wildcard characters

Estimation method
method(method) estimation
method; can be logit (distribution regression)
or qr (quantile regression process)

logfit use log-transformed outcome variable for model estimation

gsize(#) size of evaluation grid (number of models)

nobin do not apply linear binning; only relevant if method(qr)

bin(# [#]) details of linear binning; only relevant if method(qr)

nodots suppress progress dots

SE/VCE
vce(vcetype) variance estimation method; vcetype may
bootstrap or jackknife; see help vce_option

Generate
generate[(spec)] store
fitted and counterfactual distributions as variables

replace allow replacing existing variables

Reporting
level(#) set confidence level; default is level(95)

[no]header whether to display the table header

nolegend suppress lincom legend

notable suppress table of results

display_options standard display options

decomp_options Description

reverse report reverse decomposition

average report averaged decomposition

threefold report threefold decomposition

swap swap the groups

Description

cdist estimates counterfactual distributions using methods suggested
by Chernozhukov et al. (2013). The unconditional (counterfactual) distributions
are either obtained by distribution regression using logit models
or by a linear quantile regression process (using mm_qr() from
the moremata package).

For an alternative implementation of these (and related) methods
see package counterfactual by Blaise Melly (type
net from https://raw.githubusercontent.com/bmelly/Stata/main/; the
package also includes commands cdeco and cdeco_jmp to perform
counterfactual decompositions).

Dependencies

cdist requires moremata. Type

. ssc describe moremata

Options

Main

by(groupvar) specifies the variable that identifies the two groups to be compared. Option by()
is required.

swap swaps the groups identified by groupvar. By default, the lower value
of groupvar identifies group 0 and the higher value identifies group 1. Specify
swap to use the lower value for group 1 and the higher value for group 0.

pooled uses the distribution of characteristics in the pooled sample across
both groups when generating counterfactual predictions. The default is to use the
distribution of the opposite group in each case. Specify pooled if you
want to standardize both groups to the same overall distribution. pooled
is not allowed together with jmp.

jmp[(type)] causes composition-adjusted and
location-shifted counterfactual distributions to be computed in addition to
the composition-adjusted counterfactual distributions. These additional
distributions are needed for decompositions in the style of Juhn et
al. (1993), where the unexplained part is subdivided into a part due to
differences in (conditional) location and a part due to differences in
(conditional) residual distribution. If jmp is has been applied,
cdist decomp will report such a decomposition. Argument type can
be median to use median regression for the location model (the
default), or mean to use least-squares regression for the location
model. jmp is not allowed together with pooled.

Target statistics

statistics(stats) specifies the statistics to be reported. stats is
a space-separated list of a selection of the following statistics:

mean arithmetic mean

variance variance

sd standard deviation

median median

iqr[(lo up)] inter quantile range, i.e. p(up)-p(lo); default is iqr(25 75) (inter quartile range)

gini Gini coefficient

mld mean log deviation

theil Theil index

cv coefficient of variation

vlog variance of logarithms

sdlog standard deviation of logarithms

p(#) quantile (percentile) at percentage # in [0,100]

q(#) quantile at proportion # in [0,1]; q(#) = p(#*100)

qratio(lo up) quantile ratio, i.e. p(up)/p(lo); e.g., type qratio(10 90) for the D9/D1 ratio

Only one of statistics(), percentile(), quantile(), pdf(), and cdf()
is allowed. The default is statistics(mean).

islog indicates that depvar contains log-transformed values and
that the computation of inequality measures gini, mld,
theil, and cv should be based on back-transformed values.

percentile[(##|numlist)] reports quantiles (percentiles), either
at # equally-spaced percentages between 0 and 100, or at the percentages specified in numlist. Specifying
percentile without argument is equivalent to percentile(#9).

quantile[(##|numlist)] reports quantiles, either
at # equally-spaced proportions between 0 and 1, or at the proportions specified in numlist. Specifying
quantile without argument is equivalent to quantile(#9).

pdf[(##|numlist[, pdfopts])] reports density estimates, either
at # equally-spaced outcome values across the range of depvar, or at the outcome values
specified in numlist. Specifying pdf without argument is equivalent to
pdf(#9). pdfopts are as follows (see mm_density() for more information).

bwidth(#|method) sets the bandwidth to # or, alternatively,
specifies the type of automatic bandwidth selector to be used. method can be
silverman (optimal of Silverman),
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), or
isj (diffusion estimator bandwidth). The default is bwidth(dpi(2))

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).

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.

cdf[(##|numlist)] reports the cumulative distribution function, either
at # equally-spaced outcome values across the range of depvar, or at the outcome values
specified in numlist. Specifying cdf without argument is equivalent to
cdf(#9).

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). See
mm_quantile() for information on the
different definitions.

Results

decomp[(decomp_options)]
reports the decomposition of the gap between the two groups, rather than
observed and counterfactual values for each group. decomp_options select
the type of decomposition; see below.

lincom(explist) reports specified
linear combinations of results; see cdist lincom above

keep(eqlist) keeps the specified equations. Use this option to
save computer time if you are only interested in a selection of the results that are
returned by cdist by default. eqlist is a space-separated
list of equation names, possibly containing * and ? wildcard characters. See
cdist lincom above for the list of equation names used by cdist.

drop(eqlist) drops the specified equations. See keep() above.

Estimation method

method(method) selects the method by which the counterfactual
distributions are estimated. method can be logit
to use distribution regression based on logistic regression,
or qr to obtain counterfactual distributions based on
series of quantile regressions.

method(qr) uses preprocessing algorithms suggested by
Portnoy and Koenker (1997) and Chernozhukov (2022) to
speed up the computations. Should these algorithms fail, you can type
method(qr0) to use standard estimation without preprocessing.

When specifying a factor variable with method(logit), it is
advisable, for sake of accuracy of results, to set the base level to a
level that exists in both groups.

logfit performs model fitting based on log-transformed outcome values
and then back-transforms the resulting distributions to the original scale. This
may be useful when using method(qr); results
from method(logit) are insensitive to whether logfit
is specified or not (apart from roundoff error).

gsize(#) sets the size of the evaluation grid for distribution regression
or the quantile regression process (number of models estimated in each group). The default
is gsize(100). In case of method(logit), the realized evaluation grid
may be smaller than gsize() depending on the data.

nobin requests that the target statistics are computed from the
raw predictions rather than from linearly binned predictions. This
is only relevant if method(qr) has been specified.

bin(# [#]) sets the size (number of points) and padding percentage of the
approximation grid used for linear binning of predictions. The padding percentage
determines how much the approximation grid extends beyond the observed minimum and maximum
of depvar. The default is integrate(1000 5) (1000 evaluation points;
5 percent padding on each side). This is
only relevant if method(qr) has been specified.

nodots suppresses the progress dots in the results window.

SE/VCE

vce(vcetype) selects the variance estimation method. vcetype may
bootstrap or jackknife; see help vce_option. By default
variance estimation is omitted.

Generate

generate[(spec)] stores the fitted and counterfactual
distributions as variables. Two variables are generated per distribution: the
outcome values and the weights. spec is either an explicit list of variable
names or stub* to generate automatic names with a common prefix. Specifying
generate without argument is equivalent to
generate(_dstat_*).

replace allows replacing existing variables.

Reporting

level(#) specifies the confidence level, as a percentage, for
confidence intervals. The default is level(95) or as set by set level. This is only relevant if option vce() has been specified.

[no]header decides whether the table header is displayed or not.

nolegend suppresses legend providing information on the reported
linear combinations. This is only relevant if decomp() or lincom
has been specified or when displaying results from cdist decomp or
cdist lincom.

notable suppresses the output table containing the estimated results.

display_options are standard reporting options such as
cformat() or coeflegend; see
[R] Estimation options.

decomp_options

reverse reports the reverse decomposition. This is not allowed if
option pooled has been applied.

average reports the averaged decomposition. This is not allowed if
option pooled has been applied. Only one of average and
threefold is allowed.

threefold report the threefold decomposition. This is not allowed if option jmp or
option pooled has been applied. Only one of average and
threefold is allowed.

swap interchanges the roles of the two groups.

Examples

Twofold decomposition using distribution regression:

. sysuse nlsw88, clear
. generate lnwage = ln(wage)

. cdist lnwage tenure ttl_exp grade, by(union) statistics(mean variance iqr(10 90))

. cdist decomp
. cdist decomp, reverse
. cdist decomp, average

JMP type decomposition using quantile regressions:

. cdist lnwage tenure ttl_exp grade, by(union) method(qr) jmp statistics(mean variance iqr(10 90))

. cdist decomp
. cdist decomp, reverse
. cdist decomp, average

Returned results

cdist stores the following results in e().

Scalars

e(N) number of observations

e(N0) number of observations in group 0

e(N1) number of observations in group 1

e(by0) value identifying group 0

e(by1) value identifying group 1

e(gsize) target grid size (number of regressions)

e(gsize0) realized grid size in group 0

e(gsize1) realized grid size in group 1

e(qdef) quantile definition

e(pdf_bwidth) bandwidth used for density estimation (if relevant)

e(pdf_adaptive) number of iterations of adaptive density estimator (if relevant)

e(pdf_ll) lower boundary of support for density estimation (if relevant)

e(pdf_ul) upper boundary of support for density estimation (if relevant)

e(bin) size of binning grid (if relevant)

e(bin_pad) padding percentage of binning grid (if relevant)

e(k) number of coefficients per equation in e(b)

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

Macros

e(cmd) cdist

e(cmdline) command as typed

e(depvar) name of outcome variable

e(indepvars) names of covariates

e(by) name of group variable

e(pooled) pooled or empty

e(jmp) median, mean, or empty

e(statistics) specification from statistics()

e(islog) islog or empty

e(stats_nolog) statistics affected by islog

e(coeftype) quantile, percentile, pdf, cdf, or empty

e(pdf_kernel) kernel used for density estimation (if relevant)

e(pdf_bwmethod) bandwidth selector used for density estimation (if relevant)

e(pdf_boundary) boundary correction method used for density estimation (if relevant)

e(method) logit or qr

e(logfit) logfit or empty

e(eqnames) names of equations in e(b)

e(generate) names of generated variables

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 matrix of estimates (if VCE is applied)

e(at) evaluation points of estimates (if relevant)

e(B0) coefficients individual regressions in group 0 (if estimated)

e(AT0) evaluation points of regressions in e(B0)

e(B1) coefficients individual regressions in group 1 (if estimated)

e(AT1) evaluation points of regressions in e(B1)

e(B0loc) coefficients of location regression in group 0 (if estimated)

e(B1loc) coefficients of location regression in group 1 (if estimated)

Functions

e(sample) estimation sample

If option decomp() or option lincom() is specified or, equivalently,
if post-estimation command cstat decomp or cstat lincom is applied,
the following results are added or updated.

Scalars

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

e(k_eq_0) number of equations in e(b_0)

Macros

e(lincom) the transformation specification

e(eqnames) names of equations in e(b)

e(eqnames_0) names of equations in e(b_0)

Matrices

e(b) transformed estimates

e(b_0) untransformed estimates

e(V) variance matrix of transformed estimates (if VCE applied)

e(V_0) variance matrix of untransformed estimates (if VCE applied)

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

References

Chernozhukov, Victor, Iván Fernández-Val, Blaise Melly. 2013. Inference on
Counterfactual Distributions. Econometrica 81(6):2205–2268.

Chernozhukov, Victor, Iván Fernández-Val, Blaise Melly. 2022. Fast
algorithms for the quantile regression process. Empirical Economics 62(1):7–33.

Juhn, Chinhui, Kevin M. Murphy, Brooks Pierce. 1993. Wage Inequality and the Rise
in Returns to Skill. Journal of Political Economy 101(3):410-442.

Portnoy, Stephen, Roger Koenker. 1997. The Gaussian hare and the Laplacian
tortoise: computability of squared-error versus absolute-error
estimators. Statistical Science 12(4):279-300.

Author

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

Thanks for citing this software as follows:

Jann, B. (2023). cdist: Stata module for counterfactual distribution estimation
and decomposition of group differences. Available from
https://ideas.repec.org/c/boc/bocode/s459187.html.

Also see

Online: help for
logit, qreg, counterfactual (if installed),
cdeco (if installed), oaxaca (if installed),
moremata (if installed)