*! version 1.0.0 30jan2020 author:

arhomme -- Arellano and Bonhomme (2017) quantile selection model (by Martin Biewen and Pascal Erhardt, 2020)

Syntax

Basic syntax

arhomme depvar indepvars,
select(varlist:varlist_s)

or

arhomme depvar indepvars,
select(=
varlist_s)

or

arhomme depvar indepvars,
select(depvar_s =
varlist_s)

Full syntax for Arellano and Bonhomme's selection corrected quantile estimation

arhomme depvar [indepvars] [if] [in]
[weight],
select([[depvar_s] =]
varlist_s])
[options]

options

Selection
* select() specify selection equation: dependent and independent variables

Grid Tuning
rhopoints(#) defines the number of candidate points for the copula parameter grid search; default is rhopoints(19)

taupoints(#) sets number of quantiles used to approximate the objective function; default is taupoints(3)

meshsize(#) grid scale parameter; default is meshsize(1)

centergrid(#) determines emphasis # of grid search; default is centergrid(0) for frank and gaussian, centergrid(1) for plackett and joema

frank Frank copula model; the default

gaussian Gaussian copula model

plackett Plackett copula model

joema Joe & Ma (2000) copula model

Standard Errors/Subsampling
nostderrors disables standard error computation; computes point estimates only

subsample(#) specifies sample size for m-out-of-n bootstrap; default is entire sample size n, i.e. conventional bootstrap

repetitions(#) perform # bootstrap replications, default is repetitions(100)

fillfraction(#) allow for up to a fraction of # of bootstrap replications to be replaced because of failed convergence, default is fillfraction(.3)

Instrument/Copula parameter
instrument(varname) sets a user defined instrument to estimate the copula parameter; default is propensity score from first stage probit model

copulaparameter(varname) defines pre-estimated copula parameter values per observation; allowed only in combination with option nostderrors

Reporting
quantiles(#[#[# ...]]) estimates # quantiles; default is quantiles(.1(.1).9)

graph prints graph of objective function to the output window; by default disabled

output([normal][bootstrap]) specifies whether the output table is based on asymptotic (normal) or bootstrap distribution; default is normal distribution

* select() is required. The full specification is

select([[depvar_s] =] varlist_s)

indepvars must contain at least one valid variable name

arhomme allows pweights; see weight.

Description

arhomme fits a conditional quantile regression in the presence of sample selection
using the method of Arellano and Bonhomme (2017).
Standard errors are computed by bootstrap or m-out-of-n bootstrap (a subsampling method, see Politis, Romano and Wolf, 1999).

Links to PDF documentation

link to Stata journal publication goes... here.

Some contents from publication above are not included in this help file.

Options for Arellano-Bonhomme selection model

Selection

select([[depvar_s] =] varlist_s)
specifies the variables and options for the selection
equation. It is an integral part of specifying the Arellano and Bonhomme (2017) model and is
required. The selection equation must contain at least one variable that is
not in the outcome equation (exclusion restriction).

If depvar_s is specified, it should be coded as 0 or 1, with
0 indicating an observation not selected and 1 indicating a selected
observation. If depvar_s is not specified, observations for which
depvar is not missing are assumed selected, and those for which
depvar is missing are assumed not selected.

Grid Tuning

rhopoints(#) [integer] determines the number of candidate points for the copula parameter grid search. When option frank is chosen, the
copula candidate values are constructed as follows. First, the unit interval is divided into
(# + 1) equidistant intervals. Then, the i-th candidate is defined as the i-th quantile of a
Cauchy distribution with scale meshsize and shift centergrid. With option gaussian the quantiles of a
sinus density with emphasis centergrid and range meshsize*(1-|centergrid|) are
built. The grid for the copula options plackett and joema is designed as the square root of the i-th
unit interval point divided by 1 minus this point. This method ensures that the resulting grid is more dense around centergrid. The user can shift
the focus of grid search by specifying the desired centergrid, by reducing (increasing) meshsize or
by increasing (reducing) rhopoints. Note that the default rhopoints(19) is likely to be too small for
many applications.

taupoints(#) [integer] specifies the number of quantiles for which the moment restriction is supposed to hold.
It is recommended to use this option in connection with graph. The resulting scatter plot
should suggest a smooth objective function (at least around the gravity center of search; sometimes
the objective function tends to be erratic towards outer values no matter how many taupoints are employed).
Increase taupoints to further smooth the objective function. The default taupoints(3) is a good start
in many applications, but a larger number of taupoints is recommended for more reliable estimates.

meshsize(#) [real] scales the grid search interval up(down). For large # the resulting grid
becomes less dense but searches a wider range. # is restricted to strictly positive real values for
options frank, plackett, joema and restricted to (0,1] when using gaussian. The default meshsize(1) tends to be
a good start.

centergrid(#) [real] sets the gravity center of the grid. If you already suspect the optimal copula
parameter to be a specific value, this option helps shifting the emphasis of your search. # is
restricted to (-1,1) with gaussian and to the positive real line for plackett and joema, and
unrestricted with frank.
If left unspecified, the grid will always be symmetric about the independence copula, i.e. centergrid(0)
for frank and gaussian, and centergrid(1) for plackett and joema.

frank specifies the Frank copula to model individually rotated quantiles. The copula parameter takes values on the entire real line,
with rho -> -infinity corresponding to the lower Fréchet-Hoeffding bound, rho=0 to the independence copula,
and rho -> +infinity to the upper Fréchet-Hoeffding bound.

gaussian specifies the Gaussian copula to model individually rotated quantiles. The copula parameter takes values on the interval (-1,1),
with rho -> -1 corresponding to the lower Fréchet-Hoeffding bound, rho=0 the independence copula,
and rho -> +1 equal to the upper Fréchet-Hoeffding bound.

plackett specifies the Plackett copula to model individually rotated quantiles. The copula parameter takes values on the positive real line,
with rho -> 0 corresponding to the lower Fréchet-Hoeffding bound, rho=1 to the independence copula,
and rho -> +infinity to the upper Fréchet-Hoeffding bound.
If standard errors are computed, the copula parameter is tested for rho=1 instead of rho=0. The p-value is reported accordingly.

joema specifies the Joe and Ma (2000) copula to model individually rotated quantiles. The copula parameter takes values on the positive real line,
with rho -> 0 corresponding to the lower Fréchet-Hoeffding bound, rho=1 to the independence copula,
and rho -> +infinity to the upper Fréchet-Hoeffding bound.
If standard errors are computed, the copula parameter is tested for rho=1 instead of rho=0. The p-value is reported accordingly.

Standard Errors/Subsampling

nostderrors disables the computation of standard errors. This option precludes the use of subsample(#) and repetitions(#).

subsample(#) [integer] draws samples of size # with replacement from the marked dataset. Standard errors
are computed by the m-out-of-n bootstrap method. If # is greater than or equal to the effective size of the entire
dataset the conventional bootstrap is executed.

repetitions(#) [integer] specifies the number of bootstrap replications to be used to obtain an estimate
of the variance-covariance matrix of the estimators. repetitions(100) is
the default, which is likely to be too small in many applications.

fillfraction(#) [real] determines up to which fraction of overall bootstrap repetitions the program replaces
subsamples in case of failed convergence. If this limit is reached, further failed subsamples are dropped without being replaced. fillfraction(.3) is
the default.

Instrument/Copula parameter

instrument(varname) [numeric] lets the user define a variable which serves as the instrument
varphi to estimate the copula parameter (equation (15) in Arrellano and Bonhomme, 2017).
The instrument has to be a function of varlist_s. The default is the propensity score.

copulaparameter(varname) [numeric] indicates that the copula parameter has already been estimated by the user
(for example, separately by sample subgroups in a first stage) and stored per observation in the variable varname. In this case, only step 3 of
Arrellano and Bonhomme (2017) is performed (estimation of the selection corrected quantile coefficients).
The values in varname are restricted to (-1,1) with option gaussian, to the
positive real line for plackett and joema, and unrestricted for frank. This option must be used in connection with nostderrors and
precludes the use of rhopoints(#), taupoints(#), meshsize(#), centergrid(#), subsample(#), repetitions(#), instrument, and graph.
The reason is that the user will have to code her own bootstrap procedure including all the different stages of her estimations (e.g., using bootstrap). It is only in this way that
the sampling variability of the pre-estimated copula parameters is accounted for.

Reporting

quantiles(#) [numlist] specifies the quantiles to be estimated. Valid inputs range from 0 to 1, exclusively, and in ascending order. The default values of 0.1(0.1)0.9 correspond to all deciles.

graph specifies that a scatter plot of all objective function values is automatically generated after estimation.

output([normal] [bootstrap]) defines whether the output table generated is based on the asymptotic, i.e. normal, or the bootstrap distribution. If both are specified, two separate output tables are produced.
Note that the first stage (probit) standard errors in the output are always asymptotic (coming from the default probit command). repetitions should be set to at least
500 when choosing output(bootstrap). If both normal and bootstrap are specified, then results based on the normal distribution are reported first.

Remarks

arhomme estimates gamma, b(U) and rho in the model:

(U-th conditional quantile regression equation: Y is depvar, X is varlist)

Y* = Xb(U)

(selection equation: Z is varlist_s and D depvar_s)

D=1(V<p(Z))

Y=Y* only observed if D=1

(distributional assumptions)

P[D=1|Z=z] = N(Z'gamma) (probit model)

U,V jointly uniform ~ C_{U,V|X}(u,v;rho) independent of Z

with C_{U,V|X}(u,v;rho) specified by choice of copula

Examples

Setup

. webuse womenwk

Obtain Arellano-Bonhomme's selection corrected estimates

. arhomme wage education age, select(married children education age) nostd quantiles(.25 .5 .75)

Define and use each equation separately

. global wage_eqn wage education age

. global seleqn married children education age

. arhomme $wage_eqn, select($seleqn) quantiles(.25 .5 .75)

Use a variable to identify selection

. generate works = (wage < .)

. arhomme $wage_eqn, select(works = $seleqn) quantiles(.25 .5 .75)

Tune grid settings

. arhomme $wage_eqn, select(works = $seleqn) centergrid(-2) meshsize(.8) taupoints(2) rhopoints(39) quantiles(.25 .5 .75)

Switch to Gaussian copula

. arhomme $wage_eqn, select(works = $seleqn) gaussian quantiles(.2(.2).8)

Reduce subsample size

. arhomme $wage_eqn, select(works = $seleqn) repetitions(250) subsample(500)

Generate objective function graph

. arhomme $wage_eqn, select(works = $seleqn) centergrid(-5) graph quantiles(.5) nostd

Stored results

arhomme stores the following in e():

Scalars

e(N) number of observations

e(sN) number of selected observations

e(rho) estimated copula parameter

e(Vrho) estimated variance of copula parameter

e(meshsize) measure of grid density

e(centergrid) emphasis of grid search

e(rhopts) number of rhopoints

e(taupts) number of taupoints

e(minFval) minimum of objective function

e(subsample) size of subsamples

e(repetitions) number of bootstrap repetitions

e(spearman) Spearman's rank correlation

e(kendall) Kendall's tau

e(blomqvist) Bomqvist's beta

e(fillfrac) fraction of maximally replaced subsamples

Macros

e(cmd) arhomme

e(cmdline) command as typed

e(depvar) name of dependent variable

e(wtype) weight type

e(wexp) weight expression

e(instrument) instrument expression

e(cparameter) copula parameter expression

Matrices

e(b) coefficient vector

e(V) variance-covariance matrix of the estimators

e(pvals) p-values of test for significance based on bootstrap distribution

e(confivals) confidence intervals of test for significance based on bootstrap distribution

e(bbetas) estimated quantile coefficients (column) of each bootstrap replication (row)

e(sbetas) e(bbetas) where each row is sorted in ascending order

Functions

e(sample) marks estimation sample

References

Arellano, M. and Bonhomme, S. 2017.
Quantile Selection Models with an application to understanding changes in wage inequality.
Econometrica 85(1): 1-28.

Joe, H. 2014.
Dependence modelling with copulas. New York: Chapman and Hall/CRC.

Joe, H. & Ma, C. 2000.
Multivariate survival functions with a min-stable property.
Journal of Multivariate Analysis 75: 13-35.

Politis, D.N., J.P. Romano, M. Wolf, 2014.
Subsampling. Heidelberg/New York: Springer.