help for reldisthttp://github.com/benjann/reldist/

Title

reldist -- Relative distribution analysis

Syntax

Estimation

Two-sample relative distribution (syntax 1)

reldist subcmd
varname
[if] [in] [weight], by(groupvar)
[ options ]

Paired relative distribution (syntax 2)

reldist subcmd
varname refvar [if] [in] [weight]
[, options ]

where subcmd is

pdf relative density

histogram relative histogram

cdf relative cumulative distribution

divergence divergence measures

mrp median relative polarization

summarize summary statistics of relative ranks

Replay results

reldist [, noheader notable display_options ]

Draw graph after estimation

reldist graph
[, graph_options ]

Obtain influence functions after estimation

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

options Description

Main
by(groupvar) binary variable that identifies the groups (syntax 1 only)

swap reverse order of groups (syntax 1 only)

pooled use pooled distribution as reference distribution (syntax 1 only)

balance(spec) balance
covariates using reweighting (syntax 1 only)

adjust(spec) location and scale adjustment (not allowed for mrp)

rank_options details about computation of relative ranks

replace allow replacing existing variables

Subcommand pdf
n(#) number of evaluation points; default is n(101)

at(numlist|matname) use custom evaluation grid on probability scale

atx[(spec)] evaluate relative density at outcome values

discrete treat data as discrete

categorical treat data as categorical

histogram[(#)] include
histogram using # bins; default is # = 10

alt use alternative estimation method for histogram

density_options density estimation options

graph[(graph_options)] display graph

ogrid(#) | noogrid set size of outcome label approximation grid

Subcommand histogram
n(#) number of histogram bins; default is n(10)

alt use alternative estimation method

discrete treat data as discrete

categorical treat data as categorical

graph[(graph_options)] display graph

ogrid(#) | noogrid set size of outcome label approximation grid

Subcommand cdf
n(#) number of evaluation points; default is n(101)

at(numlist|matname) use custom evaluation grid on probability scale

atx[(spec)] evaluate relative CDF at outcome values

alt use alternative estimation method

discrete treat data as discrete

categorical treat data as categorical

graph[(graph_options)] display graph

ogrid(#) | noogrid set size of outcome label approximation grid

Subcommand divergence
over(overvar) compute results for subpopulations defined by overvar

entropy or kl report Kullback-Leibler divergence (entropy); this is the default

chi2 or chisquared report the Chi-squared divergence

tvd or dissimilarity report the dissimilarity index (total variation distance)

all report all divergence measures

n(#) size of evaluation grid

alt use alternative estimation method for histogram

pdf use kernel density estimator instead of histogram

density_options density estimation options; only
relevant if pdf is specified

discrete treat data as discrete

categorical treat data as categorical

compare[(options)] compare divergence measures
between two models

Subcommand mrp
over(overvar) compute results for subpopulations defined by overvar

multiplicative use multiplicative (instead of additive) adjustment

logarithmic use logarithmic (instead of linear) adjustment

scale[(sd)] adjust scale between distributions

Subcommand summarize
over(overvar) compute results for subpopulations defined by overvar

statistics(statnames) report
specified statistics

generate(newvar) store the relative ranks in newvar

SE/CI
level(#) set confidence level; default is level(95)

vce(vcetype) variance estimation method;
vcetype may be analytic, cluster clustvar, svy, bootstrap,
or jackknife

nose do not compute standard errors

Reporting
citransform report transformed confidence intervals

noheader suppress display of output header

[no]table suppress/enforce display of coefficients table

display_options standard reporting options

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

density_options Description

bwidth(#|method) set bandwidth
to #, # > 0, or choose bandwidth selection method; default is bwidth(sjpi)

bwadjust(#) rescale bandwidth by #, # > 0

boundary(method) boundary correction method;
default is boundary(renorm)

adaptive(#) number of iterations of the adaptive
density estimator; default is adaptive(0)

kernel(kernel) type of kernel function; default is
kernel(gaussian)

napprox(#) grid size of approximation estimator; default
is napprox(512)

exact use the exact density estimator

graph_options Description

Main
refline(line_options) affect rendition
of parity line

norefline suppress the parity line

After subcommand pdf
cline_options affect rendition of PDF line

histopts(options) affect
rendition of histogram bars

nohistogram omit histogram bars

After subcommand histogram
barlook_options affect rendition of histogram bars

After subcommand cdf
noorigin do not add (0,0) coordinate

cline_options affect rendition of CDF line

Confidence intervals
level(#) set confidence level

citransform plot transformed confidence intervals

ci(name) obtain confidence intervals from e(name)

ciopts(area_options) affect rendition of confidence intervals

noci omit confidence intervals

Outcome labels
[y]olabel[(spec)] add outcome labels
on secondary axis

[y]otick(spec) add outcome ticks
on secondary axis

[y]oline(spec) add outcome lines
on secondary axis

[y]otitle(tinfo) title for outcome scale axis

General graph options
addplot(plot) add other plots to the generated graph

twoway_options any options other than by() documented in help
twoway_options

Description

reldist provides a set of tools for relative distribution analysis. For
background information see Handcock and Morris (1998, 1999). For methods and
formulas used by reldist see
Jann (2020).

o Command reldist pdf estimates the density function of the
relative distribution, possibly including a histogram of the relative density.

o Command reldist histogram estimates a histogram of the relative density.

o Command reldist cdf estimates the relative distribution function. This is
equivalent to a so-called probability-probability plot
(see ppplot from SSC).

o Command reldist divergence estimates the Kullback-Leibler divergence (entropy),
the Chi-squared divergence, or the dissimilarity index (total variation distance) of the
relative distribution.

o Command reldist mrp estimates the
median relative polarization index (MRP), as well as its decomposition into a
lower and and upper polarization index (LRP and URP).

o Command reldist summarize computes summary statistics such as the mean
or the median of the relative ranks, and can also be used to store the relative
ranks in a new variable.

o Command reldist graph plots the results after reldist pdf,
reldist histogram, or reldist cdf.

o Command predict calculates the influence functions of the estimated
statistics. Option scores is implied.

There are two syntaxes:

o In syntax 1, the distribution of depvar is
compared between two groups defined by the by() option
(two-sample relative distribution).

o In syntax 2, the distribution of
depvar is compared to the distribution of refvar within the same
sample (paired relative distribution).

reldist requires moremata to be installed on the system. See
ssc describe moremata.

Options

Main

by(groupvar) specifies a binary variable that identifies the two groups
to be compared. By default, the group with the lower value will be used as
the reference group. by() is required in syntax 1 and not allowed
in syntax 2.

swap reverses the order of the groups identified by by(). swap is
only allowed in syntax 1.

pooled uses the pooled distribution across both groups as reference
distribution. pooled is
only allowed in syntax 1.

balance(spec) balances covariate distributions between the
comparison group and the reference group using reweighting. balance()
is only allowed in syntax 1. 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),
varlist specifies the list of covariates to be balanced, and
options are as follows:

reference reweights the reference group. The
default is to reweight the comparison group. Option
pooled is not allowed with balance(, reference).

contrast compares the balanced distribution with to the unbalanced
distribution. Use this option to see how the balancing changes the
distribution. If contrast is specified together with reference,
the balanced reference distribution will be used as the comparison
distribution. If contrast is specified without reference, the
balanced comparison distribution will be used as the reference
distribution.

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
successfully balanced. An example is as follows:

. sysuse nlsw88, clear

. reldist summarize wage, by(union) balance(collgrad ttl_exp, generate(wbal))

. tabstat collgrad ttl_exp if wage<., by(union) nototal (unbalanced)

. tabstat collgrad ttl_exp [aw=wbal], by(union) nototal (balanced)

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

. drop wbal

. reldist summarize wage, by(union) balance(eb:collgrad ttl_exp, generate(wbal))

. tabstat collgrad ttl_exp [aw=wbal], by(union) nototal

adjust(spec) applies location, scale, and shape adjustments to
the comparison and reference distributions. adjust() is not allowed
with reldist mrp. The syntax of spec is

adjust [, options]

where adjust specifies the desired adjustments. adjust may contain
any combination of at most two of the following keywords:

location adjust location
scale adjust scale
shape adjust shape

By default, the specified adjustments are applied to the comparison
distribution. However, a colon may be included
in adjust to distinguish between distributions: Keywords before the
colon affect the comparison distribution; keywords after the colon affect
the reference distribution. For example, type
adjust(location scale) to adjust the location and scale of the
comparison distribution. Likewise, you could type adjust(:location scale) to
adjust the reference distribution. Furthermore,
adjust(location : shape) would adjust the location of the comparison
distribution and the shape of the reference distribution. options are
as follows:

mean uses the mean for the location adjustment. The default is to
use the median.

sd uses the standard deviation for the scale adjustment. The default is
to use the IQR (interquartile range).

multiplicative uses a multiplicative adjustment instead of an additive
adjustment. adjust may only contain one keyword in this case, either
location or shape. Error will be returned if the
location ratio between the comparison distribution and the reference
distribution is not strictly positive.

logarithmic performs the adjustments on logarithmically transformed
data. Error will be returned if the data is not strictly positive.

rank_options specify the details about the computation of relative
ranks. These options are irrelevant for reldist histogram,
reldist cdf, reldist divergence unless option pdf
is specified, and reldist pdf if discrete or categorical
is specified. The options are as follows:

nobreak changes how the relative ranks are computed in case of ties. By
default, reldist breaks ties for comparison values that have
ties in the reference distribution (in ascending order of weights, if
weights have been specified). This leads to improved results if there is
heaping in the data. Specify nobreak to omit breaking ties.

nomid changes how the relative ranks are computed in case of ties. By
default, reldist uses midpoints of the steps in the cumulative
distribution for comparison values that have ties in the
reference distribution. This ensures that the average
relative rank is equal to 0.5 if the comparison and reference distributions
are identical. Specify nomid to assign relative ranks based on full
steps in the CDF.

descending sorts tied observations in descending order of
weights. The default is to use ascending sort order. Option
descending has no effect on results if nobreak is specified or
if there are no weights.

nostable breaks ties randomly (within unique values of weights). The
default is to break the ties in the sort order of the data (within unique
values of weights). Option nostable has no effect on the results
reported by reldist. It may, however, affect the ranks stored by
option generate() or the influence functions stored by predict
(unless option nobreak is specified).

replace allows replacing existing variables. This is relevant for
generate() with reldist summarize and generate()
in balance().

For subcommand -pdf-

n(#) sets the number of evaluation points for which the PDF is to
be computed. A regular grid of # evaluation points between 0 and 1 will
be used. The default is n(101) (unless option discrete
or categorical is specified, in which case n() has no
default). Only one of n(), at(), and atx() is allowed.

at(numlist|matname) specifies a custom grid of
evaluation points between 0 and 1, either by providing a
numlist or the name of a matrix containing the values
(the values will be taken from the first row or the first column of the matrix,
depending on which is larger). Only
one of n(), at(), and atx() is allowed.

atx[(comparison|reference|numlist|matname)],
specified without argument, causes the relative PDF to be evaluated at each
distinct outcome value that exists in the data (possibly after applying
adjust()), instead of using a regular evaluation grid on the
probability scale. All outcome values across both distributions will be
considered. To restrict the evaluation points to outcome values from the
comparison distribution or from the reference distribution, specify
atx(comparison) or atx(reference), respectively. Alternatively,
specify a grid of custom values, either by providing a
numlist or the name of a matrix containing the values
(the values will be taken from the first row or the first column of the
matrix, depending on which is larger). Only one of n(), at(),
and atx() is allowed.

discrete causes the data to be treated as discrete. The relative PDF
will then be evaluated at each level of the data as the ratio of the
level's frequency between the comparison distribution and the reference
distribution instead of using kernel density estimation, and the result
will be displayed as a step function. If option n() or at() is
specified, the step function will be evaluated at the points of the
corresponding probability grid instead of returning the relative density
for each outcome level. Options nobreak, nomid, descending, and
density_options have no effect if
discrete is specified. Furthermore, options histogram() and
adjust() are not allowed.

categorical is like discrete, but additionally requests that
the data only contains positive integers. Factor-variable notation will be used to
label the coefficient in the output table.

histogram[(#)] computes a histogram in
addition to the PDF, where # is the number of bins. If # is omitted,
10 bins will be used.

alt uses an alternative estimation method for the histogram;
see histogram options below.

density_options set the details of kernel density estimation. The options
are as follows:

bwidth(#|method[, nord]) determines the bandwidth of the kernel, the
halfwidth of the estimation window around each evaluation point. Use
bwidth(#), # > 0, to set the bandwidth to a specific value. Alternatively,
type bwidth(method) to choose an automatic bandwidth selection
method. Choices 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), or
isj (diffusion estimator bandwidth). The default
is bw(sjpi).

By default, if estimating the density of the relative data, all bandwidth selectors
include a correction for relative data based on Cwik and Mielniczuk (1993). Specify
suboption nord to omit the correction.

bwadjust(#) multiplies the bandwidth by
#, where # > 0. Default is bwadjust(1).

boundary(method) sets the type of boundary correction method. Choices are
renorm (renormalization method; the default), reflect (reflection method), or
lc (linear combination technique).

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

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

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

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 to be evaluated at many points.

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

ogrid(#) sets the size of the approximation grid for outcome
labels. The default is ogrid(401). The grid is stored in
e(ogrid) and will be used by graph option
olabel() to determine the positions of outcome
labels. Type noogrid to omit the computation of the grid (no outcome
labels will then be available for the graph). Option ogrid() is only
allowed if the relative density is computed with respect an evaluation grid
on the probability scale. If the relative density is evaluated with respect to
specific outcome values (e.g. if atx() is specified), the outcome
labels will be obtained from the information stored in e(at).

For subcommand -histogram-

n(#) specifies the number of histogram bars. The reference distribution
will be divided into # bins of equal width. That is, each bin will
cover 1/#th of the reference distribution. The default is n(10).

alt uses an alternative estimation method. The default method obtains
the relative histogram by computing the empirical CDFs of both distributions at
all values that exist in the data (across both distributions). The
alternative method obtains the relative histogram based on the empirical CDF of
the relative ranks. In both cases, if necessary, linear interpolation will be used
to map the relative CDF to the evaluation points.

discrete causes the data to be treated as discrete. The relative density
will then be evaluated at each level of the data as the ratio of the
level's frequency between the two distributions and the width of bars will be
proportional to the reference distribution. Option alt has no effect and
options n() and adjust() are not allowed if discrete is specified.

categorical is like discrete, but additionally requests that
the data only contains positive integers. Factor-variable notation will be used to
label the coefficient in the output table.

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

ogrid(#) sets the size of the approximation grid for outcome
labels. The default is ogrid(401). The grid is stored in e(ogrid) and
will be used by graph option olabel() to determine
the positions of outcome labels. Type noogrid to omit the computation
of the grid (no outcome labels will then be available for the graph). ogrid()
is not allowed together with discrete or categorical.

Subcommand -cdf-

n(#) sets the number of evaluation points for which the CDF is to
be computed. A regular grid of # evaluation points between 0 and 1 will
be used. The default is n(101) (unless option discrete
or categorical is specified, in which case n() has no
default). Only one of n(), at(), and
atx() is allowed.

at(numlist|matname) specifies a custom grid of
evaluation points between 0 and 1, either by providing a
numlist or the name of a matrix containing the values
(the values will be taken from the first row or the first column of the matrix,
depending on which is larger). Only one of n(), at(), and atx()
is allowed.

atx[(comparison|reference|numlist|matname)],
specified without argument, causes the relative CDF to be evaluated at each
distinct outcome value that exists in the data (possibly after applying
adjust()), instead of using a regular evaluation grid on the
probability scale. All outcome values across both distributions will be
considered. To restrict the evaluation points to outcome values from the
comparison distribution or from the reference distribution, specify
atx(comparison) or atx(reference), respectively. Alternatively,
specify a grid of custom values, either by providing a
numlist or the name of a matrix containing the values
(the values will be taken from the first row or the first column of the
matrix, depending on which is larger). Only one of n(), at(),
and atx() is allowed.

alt uses an alternative estimation method. The default method obtains
the relative CDF by computing the empirical CDFs of both distributions at
all values that exist in the data (across both distributions). The
alternative method obtains the relative CDF based on the empirical CDF of
the relative ranks. In both cases, if necessary, linear interpolation will be used
to map the relative CDF to the evaluation points.

discrete causes the data to be treated as discrete. The relative CDF
will then be evaluated at each observed outcome value instead of using an
evaluation grid on the probability scale. Option discrete leads to the
same result as specifying atx. Option adjust() is not allowed
if discrete is specified.

categorical is like discrete, but additionally requests that
the data only contains positive integers. Factor-variable notation will be used to
label the coefficient in the output table.

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

ogrid(#) sets the size of the approximation grid for outcome
labels. The default is ogrid(401). The grid is stored in
e(ogrid) and will be used by graph option
olabel() to determine the positions of outcome
labels. Type noogrid to omit the computation of the grid (no outcome
labels will then be available for the graph). Option ogrid() is only
allowed if the relative CDF is computed with respect an evaluation grid
on the probability scale. If the relative CDF is evaluated with respect to
specific outcome values (e.g. if atx() is specified), the outcome
labels will be obtained from the information stored in e(at).

For subcommand -divergence-

over(overvar) computes results for each subpopulation defined
by the values of overvar.

entropy or kl computes the Kullback-Leibler divergence (entropy) of the
relative distribution. This is the default.

chi2 or chisquared computes the Chi-squared divergence of the
relative distribution.

tvd or dissimilarity computes the dissimilarity index (total variation distance) of the
relative distribution.

all computes all supported divergence measures. all is equivalent to
entropy chi2 tvd.

n(#) specifies the number of histogram bars or, if option pdf is specified, the
number of kernel density evaluation points used to estimate the relative distribution. The
default is n(20) or, if option pdf is specified, n(100).

alt uses an alternative estimation method for the histogram density;
see histogram options above.

pdf computes the divergence measures based on a kernel density estimate instead of a
histogram estimate.

density_options set the details of the the kernel density estimation. This is
only relevant if option pdf is specified. See density_options
above for available options.

discrete causes the data to be treated as discrete. The relative density
will then be evaluated at each level of the data as the ratio of the
level's frequency between the two distributions. Option alt has no effect and
options n(), pdf, and adjust() are not allowed if discrete is specified.

categorical is like discrete, but additionally requests that
the data only contains positive integers.

compare[(options)] estimates divergence measures for
two models of the relative distribution, a main model and an alternative model,
and also reports the difference between the two variants. options are
balance() and adjust() as described
above. balance() and adjust() specified as main options are applied
to the main model; balance() and adjust() specified within
compare() are applied to the alternative model.

For subcommand -mrp-

over(overvar) computes results for each subpopulation defined
by the values of overvar.

multiplicative applies multiplicative location adjustment. The
default is to use additive adjustment. Only one of
logarithmic and multiplicative is allowed.

logarithmic causes the location (and, optionally, scale)
adjustment to be performed on the logarithmic scale. Only one of
logarithmic and multiplicative is allowed.

scale[(sd)] adjusts the scale of the data before
computing the polarization indices. If scale is specified without argument,
the IQR (interquartile range) will be used; that is, the scale of the data will be
adjusted such that the IQR is the same in both distributions. Specify
scale(sd) to use the standard deviation instead of the IQR. scale()
is not allowed if multiplicative is specified.

For subcommand -summarize-

over(overvar) computes results for each subpopulation defined
by the values of overvar.

statistics(statname [...]) specifies a space separated list of
summary statistics to be reported. The default is statistics(mean). The
following summary statistics are supported:

mean mean

variance variance

sd standard deviation

median median; equivalent to p50

p# #th percentile, where # is an integer between 1 and 99

iqr interquartile range (p75-p25)

generate(newvar) stores the relative ranks in
variable newvar. Depending on adjust(), different observations
may be filled in.

SE/CI

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

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

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

The default is vce(analytic), which computes the standard errors based
on influence functions. Likewise, vce(cluster clustvar) computes
influence-function based standard errors allowing for intragroup correlation,
where clustvar specifies to which group each observation
belongs. In both cases, density_options specify
specify how auxiliary densities are estimated during the computation of the
influence functions (option boundary() will have no effect; unbounded support
is assumed for auxiliary densities).

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 reldist's way to support
the svy prefix. If svy_vcetype is set to linearized, the
standard errors are estimated based on influence functions; use
density_options to specify the details
of auxiliary density estimation in this case. For
svy_vcetype other than linearized, density_options
are not allowed.

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

If a replication technique is used for standard error estimation,
i.e. vce(bootstrap), vce(jackknife), vce(svy) with
svy_vcetype other than linearized,
the bandwidth used by reldist pdf will be held fixed across
replications (that is, if relevant, the bandwidth will be determined upfront
and then held constant). If you want to repeat bandwidth
search in each replication, use bootstrap, jackknife, or svy
as a prefix command.

nose prevents reldist from computing standard errors. This saves computer time.

Reporting

citransform reports transformed confidence intervals
depending on the type of the reported statistics (log
transform for PDF and histogram density, logit transform for CDF and
descriptive statistics, inverse hyperbolic tangent transform for
polarization indices). citransform only has an effect in Stata 15 or
newer.

noheader suppress the output header.

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

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

Options for reldist graph

Main

refline(line_options) specifies options to affect
the rendition of the parity line. See help line_options.

norefline suppresses the parity line.

After subcommand -pdf-

cline_options affect the rendition of the PDF line. See
help cline_options.

histopts(options) specifies options to affect the
rendition of the histogram bars (if a histogram was computed) and the
corresponding confidence spikes. options are as follows:

barlook_options affect the rendition of the histogram bars. See
help barlook_options.

ciopts(rcap_options) specifies options to affect the
rendition of the confidence spikes of the histogram bars. See help
rcap_options.

noci omits the confidence spikes of the histogram bars.

nohistogram omits the histogram bars.

After subcommand -histogram-

barlook_options affect the rendition of the histogram bars. See
help barlook_options.

After subcommand -cdf-

noorigin prevents adding a (0,0) coordinate to the plotted
line. If the first X-coordinate of the CDF is larger
than zero and the range of the CDF has not been restricted by at() or
atx(), reldist graph will automatically add a
(0,0) coordinate to the plot. Type noorigin
to override this behavior.

cline_options affect the rendition of the CDF line. See
help cline_options.

Confidence intervals

level(#) specifies the confidence level, as a percentage, for
confidence intervals.

citransform plots transformed confidence intervals
depending on the type of the reported statistics (log
transform for PDF and histogram density, logit transform for CDF).

ci(name) obtains the confidence intervals from
e(name) instead of computing them from
e(V). e(name) must contain two rows and
the same number of columns as e(b). For example, after
bootstrap estimation, you could type ci(ci_percentile) to plot
percentile confidence intervals. ci() and
level() are not both allowed.

ciopts(options) specifies options to affect the
rendition of the confidence intervals. See
help area_options or, after, reldist histogram
help rcap_options. Use option recast() to change the
plot type used for confidence intervals. For example, type
ciopts(recast(rline)) to use two lines instead of an area.

noci omits the confidence intervals.

Outcome labels

[y]olabel[(spec)] adds outcome labels on a secondary
axis. olabel() adds outcome labels for the reference distribution; yolabel()
adds outcome labels for the comparison distribution (only allowed after
reldist cdf). The syntax of spec is

[ ## | numlist ] [,
{ noprune | prune(mindist) }
at format(%fmt) suboptions ]

## requests that (approximately) # outcome labels be
added at (approximately) evenly-spaced positions; the default is
#6. Alternatively, specify numlist to generate labels for
given outcome values.

prune(mindist) requests that an outcome label (but not its tick) is to
be omitted if its distance to the preceding label is less than mindist
(an exception are labels that have the same position;
in such a case the largest label will be printed). The default is
prune(0.1); type prune(0) or noprune to print labels at
all positions. The difference between prune(0) and noprune is
that prune(0) will only print one label per position whereas
noprune prints all labels, including labels that have the same
position.

at causes numlist to be interpreted as a list of probabilities for which
outcome labels are to be determined. Labels obtained this way will not be pruned.

format(%fmt) specifies the display format for the outcome labels. Default
is format(%6.0g). See help format for available formats.

suboptions are as described in help axis_label_options.

Option [y]olabel() may be repeated. Use suboptions add
and custom to generate multiple sets of labels
with different rendering; see axis_label_options.

[y]otick(spec) adds outcome ticks on a secondary axis.
otick() adds outcome ticks for the reference distribution;
yotick() adds outcome ticks for the comparison distribution (only
allowed after reldist cdf). The syntax of spec is

numlist [, suboptions ]

where numlist specifies the outcome values for which ticks be generated
and suboptions are as described in help
axis_label_options. Option [y]otick() may be
repeated. Use suboptions add and custom to generate multiple
sets of ticks with different rendering; see axis_label_options.

[y]oline(spec) draws added lines at the positions of
the specified outcome values on a secondary axis. oline() adds
outcome lines for the reference distribution; yoline() adds outcome
lines for the comparison distribution (only allowed after
reldist cdf). The syntax of spec is

numlist [, suboptions ]

where numlist specifies the outcome values for which added lines be generated
and suboptions are as described in help
added_line_options. Option [y]oline() may be repeated
to draw multiple sets of lines with different rendering.

[y]otitle(tinfo) provides a title for the outcome scale
axis; see help title_options. otitle() is for the reference
distribution; yotitle() is for the comparison distribution (only
allowed after reldist cdf).

Technical note: The positions of the outcome labels, ticks, or lines are
computed from information stored by reldist in e(), either
from the quantiles stored in e(ogrid) or from the values stored
in e(at), depending on context. There is an undocumented command
called reldist olabel that can be
used to compute the positions after the relative distribution has been
estimated. Use this command, for example, if you want to draw a custom
graph from the stored results without applying reldist graph. The
syntax is as follows:

reldist olabel [ ## | numlist ] [,
{ noprune | prune(mindist) } at format(%fmt)
tick(numlist) line(numlist) y ]

where ## or numlist specifies the (number of) values for
which labels be generated, prune() determines the
pruning (see above), at changes the meaning of the main numlist (see above),
format() specifies the display format for the labels, tick()
specifies values for which ticks be generated, line()
specifies values for which added lines be generated, and y request outcome labels
for the Y axis of the relative CDF (only allowed after
reldist cdf). The command returns the following macros in r():

r(label) label specification for use in an xlabel() option

r(label_x) expanded and sorted numlist

r(tick) tick specification for use in an xtick() option

r(tick_x) expanded and sorted numlist from tick()

r(line) line specification for use in an xline() option

r(line_x) expanded and sorted numlist from line()

General graph options

addplot(plot) provides a way to add other plots to the
generated graph. See help addplot_option.

twoway_options are any options other than by() documented in help
twoway_options.

Examples

Relative density and histogram

Compare the wages of unionized and non-unionized workers:

. sysuse nlsw88, clear
. reldist pdf wage, by(union)

. reldist graph, ciopts(recast(rline) lp(dash) pstyle(p1))

To get an idea of the hourly wages that correspond to different positions in
the reference distribution, we can add outcome labels using the olabel
option:

. reldist graph, olabel otitle(hourly wage)

We can also provide a list of custom values for which outcome labels be
generated:

. reldist graph, olabel(1(1)40) otitle(hourly wage)

By default, labels that are close together will not be printed. Type
olabel(1(1)40, noprune) to print all 40 labels. Alternatively use suboption
prune() to set the minimum distance between labels
(default is prune(0.1)). Example:

. reldist graph, olabel(1(1)40, prune(0.04)) otitle(hourly wage)

To include a histogram in addition to the density curve, type:

. reldist pdf wage, by(union) histogram graph(ciopts(fc(%50) lc(%0)))

Or, to display only the histogram:

. reldist histogram wage, by(union) graph

Since unionized workers have, on average, higher wages than non-unionized workers,
we might want to adjust the location of their wage distribution to see
the difference in the distributional shape between the two groups, net of the
difference in location:

. reldist pdf wage, by(union) adjust(location) graph(ciopts(fc(%50) lc(%0)))

Interestingly, the distribution among unionized workers appears more polarized, at
least in the lower part of the distribution. However, this may be a
misleading result because, by default, reldist performs an
additive location shift (pushing low-wage earners among the unionized
to the very bottom of the distribution). Since wages can only be positive,
it probably makes more sense to use a multiplicative shift (i.e., to rescale the
wages proportionally):

. reldist pdf wage, by(union) adjust(location, multiplicative) graph(ciopts(fc(%50) lc(%0)))

We now see that the distribution among the unionized is less polarized than the
distribution among non-unionized workers, especially in the upper part of the
distribution.

Cumulative distribution

The cumulative relative distribution can be graphed as follows:

. sysuse nlsw88, clear

. reldist cdf wage, by(union) nose graph(olab(1(1)40) yolab(1(1)40) aspectratio(1))

After applying a multiplicative location shift, the relative distribution
looks as follows:

. reldist cdf wage, by(union) nose adjust(location, multiplicative) graph

Median relative polarization

An analysis of relative polarization between unionized and non-unionized workers by
qualification leads to the following results:

. sysuse nlsw88, clear

. reldist mrp wage, by(union) over(collgrad)

It appears that wage polarization is more pronounced among unionized workers than among the
non-unionized workers in the group of people without college degree. In the group of
people with college degree, polarization is higher among non-unionized workers. Again, this might
be an artifact due to the default additive location adjustment imposed by the MRP. A multiplicative
adjustment (i.e. rescaling wages proportionally) probably makes more sense:

. reldist mrp wage, by(union) over(collgrad) multiplicative

We now see that polarization is generally larger among the non-unionized workers, but there
are still some interesting differences. For people without college degree the wage distribution
is compressed mostly at the top, for people with college degree the
compression appears more pronounced in the lower part of the distribution.

Summary statistics

To obtain the mean an median rank of unionized workers in the
wage distribution of non-unionized workers by
qualification, type:

. sysuse nlsw88, clear

. reldist summarize wage, by(union) over(collgrad) stat(mean median)

Being unionized seems to pay off more for people without college degree than for
people with college degree.

Note that the mean of the relative ranks has an intuitive interpretation: it
is equal to the probability that a randomly chosen member of the
comparison group has an outcome value that is at least as large at the
outcome value of a randomly chosen member of the reference group (this is
equivalent to the Gastwirth index; see Gastwirth 1975). In the example
above, among people without college degree, the probability that a randomly
selected unionized worker earns at least as much as a randomly selected
non-unionized worker is 64%.

Paired data relative distribution (syntax 2)

reldist can also be used to compare the distributions of two variables within the
same sample of observations:

. webuse nlswork, clear
. keep idcode year ln_wage
. reshape wide ln_wage, i(idcode) j(year)
. reldist pdf ln_wage88 ln_wage78, graph

It appears that log wages in 1988 have been more
polarized than in 1978, which might be due to an age effect or a general increase
in wage inequality. The result is confirmed by the MRP:

. reldist mrp ln_wage88 ln_wage78

Covariate balancing

The balance() option can be used to balance covariate
distributions before computing the relative distribution. Example:

. sysuse nlsw88, clear

. reldist pdf wage, by(union) balance(grade i.race ttl_exp) notable

. estimates store balanced

. reldist pdf wage if e(sample), by(union) notable

. estimates store raw

. coefplot raw balanced, at(at) noci recast(line) lw(*2) yline(1)

We see that balancing the specified covariances makes the wage distribution between
unionized and non-unionized workers somewhat more equal, but not very much.

By default, inverse-probability weighting is used to balance the
covariates. See the balance()
option above for alternatives.

Location and shape decompositions

Handcock and Morris (1999) discuss location and shape decompositions defined in
a way such that for each outcome value the product of the location component
and the shape component equals the overall relative density. For example,
let f(y) be the density
of y in the comparison distribution, f0(y) be the
density of y in the reference distribution, f0L(y) be the
density of y in the location-adjusted reference distribution. The relative
density can then be written as

f(y) f0L(y) f(y)
----- = ------ x ------
f0(y) f0(y) f0L(y)

where the first term is the location component and the second term is the
shape component of the decomposition. The components of such a decomposition
can be computed by reldist using the adjust() option. It can be
tricky, however, to figure out how exactly the option has to be specified.
In the first term of the above decomposition (location component), we have to
compare the location-adjusted reference distribution with the unadjusted
reference distribution. Note that the location adjusted reference
distribution is the same as the shape (and scale) adjusted comparison
distribution. Hence, the first term can be computed using option
adjust(shape scale). For the second term, we compare the (unadjusted)
comparison distribution with the location-adjusted reference
distribution. This can be accomplished specifying adjust(:location)
(note the colon; see the description of the
adjust() option above). Example:

. sysuse nlsw88, clear

. reldist pdf wage, by(union) adjust(shape scale) graph

. reldist pdf wage, by(union) adjust(: location) graph

Similarly, to make the adjustments on the logarithmic scale, we could type

. reldist pdf wage, by(union) adjust(shape scale, logarithmic) graph

. reldist pdf wage, by(union) adjust(: location, logarithmic) graph

In the multiplicative case, no distinction is made between
scale and shape (i.e. the shape adjustment includes the scale), so that the
syntax would be:

. reldist pdf wage, by(union) adjust(shape, multiplicative) graph

. reldist pdf wage, by(union) adjust(: location, multiplicative) graph

In this situation, the multiplicative approach and the logarithmic approach lead to
equivalent results. The logarithmic approach, however, provides more flexibility because
it is possible to control the shape, net of scale. This is useful for more complicated
decompositions.

Note that the above decomposition might as well have been written as

f(y) f(y) fL(y)
----- = ----- x -----
f0(y) fL(y) f0(y)

where fL(y) is the density of y in the location-adjusted
comparison distribution. To obtain this variant of the decomposition specify
adjust(:shape scale) for the first term (location component)
and adjust(location) for the second term (shape component).

Methods and formulas

Methods and formulas used by reldist are documented in
Jann (2020).

Saved results

reldist stores the following results in e().

Scalars

e(N) number of observations

e(N1) number of observations in comparison group (syntax 1 only)

e(N0) number of observations in reference group (syntax 1 only)

e(by1) value of comparison group (syntax 1 only)

e(by0) value of reference group (syntax 1 only)

e(N_over) number over-groups (if over() has been specified)

e(n) number of evaluation points (pdf, cdf, and divergence only)

e(bwidth) bandwidth of kernel density estimator (pdf only)

e(bwadjust) bandwidth adjustment factor (pdf and divergence only)

e(adaptive) number of iterations of adaptive estimator (pdf and divergence only)

e(napprox) size of approximation grid (pdf and divergence only)

e(n_hist) number of histogram bins (pdf, histogram, and divergence only)

e(hwidth) width of histogram bins (pdf and histogram only)

Macros

e(cmd) reldist

e(subcmd) pdf, histogram, cdf, divergence, mrp, or summarize

e(cmdline) command as typed

e(depvar) name of dependent variable

e(by) name of groupvar (syntax 1 only)

e(by1lab) label of comparison group (syntax 1 only)

e(by0lab) label of reference group (syntax 1 only)

e(swap) swap or empty (syntax 1 only)

e(pooled) pooled or empty

e(refvar) name of refvar (syntax 2 only)

e(nobreak) nobreak or empty

e(nomid) nomid or empty

e(descending) descending or empty

e(nostable) nostable or empty

e(atopt) contents of at() option

e(atx) atx, comparison, reference or empty

e(atxopt) contents of atx() option

e(discrete) discrete or empty

e(categorical) categorical or empty

e(alt) alt or empty

e(origin) origin or empty

e(adjust) list of comparison distribution adjustments

e(refadjust) list of reference distribution adjustments

e(adjmean) mean or empty

e(adjsd) sd or empty

e(adjlog) logarithmic or empty

e(adjmult) multiplicative or empty

e(c_adjust) list of alternate comparison distribution adjustments (divergence only)

e(c_refadjust) list of alternate reference distribution adjustments (divergence only)

e(c_adjmean) mean or empty (divergence only)

e(c_adjsd) sd or empty (divergence only)

e(c_adjlog) logarithmic or empty (divergence only)

e(c_adjmult) multiplicative or empty (divergence only)

e(balance) list of balancing variables

e(balmethod) balancing method

e(balref) reference or empty

e(balcontrast) contrast or empty

e(balopts) options passed through to balancing procedure

e(compare) compare or empty

e(c_balance) list of alternate balancing variables (divergence only)

e(c_balmethod) alternate balancing method (divergence only)

e(c_balref) reference or empty (divergence only)

e(c_balopts) alternate options passed through to balancing procedure (divergence only)

e(over) name of overvar

e(over_namelist) values of over variable

e(over_labels) values of over variable

e(pdf) pdf or empty (divergence only)

e(boundary) boundary correction method (pdf and divergence only)

e(bwmethod) bandwidth selection method (pdf and divergence only)

e(kernel) kernel function (pdf and divergence only)

e(exact) exact or empty (pdf and divergence only)

e(statistics) names of reported statistics (summarize and divergence only)

e(generate) name of generated variable (summarize only)

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(at) evaluation points (pdf, histogram, and cdf only)

e(ogrid) outcome label approximation grid (pdf, histogram, and cdf only)

e(bwidth) bandwidths of kernel density estimators (divergence only)

e(_N) number of obs per over-group (if over() had been specified)

e(_N1) number of obs per over-group in comparison group (syntax 1 only)

e(_N0) number of obs per over-group in reference group (syntax 1 only)

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

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

Gastwirth, J.L. (1975). Statistical measures of earnings differentials. The
American Statistician 29: 32-35.

Handcock, M.S., M. Morris (1998). Relative Distribution Methods.
Sociological Methodology 28: 53-97.

Handcock, M.S., M. Morris (1999). Relative Distribution Methods
in the Social Sciences. New York: Springer.

Jann, B. (2020). Relative distribution analysis in Stata. University of
Bern Social Sciences Working Papers 37. Available from
http://ideas.repec.org/p/bss/wpaper/37.html.

Author

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

Thanks for citing this software as follows:

Jann, B. (2020). reldist: Stata module for relative distribution analysis. Available from
http://ideas.repec.org/c/boc/bocode/s458775.html.

Also see

Online: help for cumul, ppplot (from SSC), moremata