help mcmccqreg

Title

mcmccqreg -- Powell's mcmc-simulated censored quantile regression

Syntax

mcmccqreg
depvar
[indepvars] [if] [in] ,
[censorvar(varname)
tau(#)
draws(#)
burn(#)
thin(#)
arate(#)
sampler(string)
dampparm(#)
from(rowvector)
fromvariance(matrix)
jumble
noisy
saving(filename)
replace
median
]

Description

mcmccqreg can be used to "fit" Powell's (1984, 1986) censored median regression model, or, in more general terms
censored quantile models, using adaptive Markov chain Monte Carlo sampling from the conditional parameter
distribution. The basis for the method is discussed in some detail in
Chernozhukov and Hong (2003), and an intuitive, low-level sketch is given in Baker (2013).

mcmccqreg allows construction of what Chernozhukov and Hong (2003) refer to as
a Laplacian estimator of the censored quantile regression model. The joint distribution of the parameters
is simulated using adaptive MCMC (Markov chain Monte Carlo) methods through application of the mata package amcmc()
(help mf_amcmc or help mata amcmc() from within the Mata system if installed).
mcmccqreg produces parameter estimates, but these
"estimates" are in fact summary statistics from draws from the distribution.
Detailed analysis of the draws remains in the hands of the user.

Syntax

mcmccqreg is invoked in the usual way - the command name, followed by the
dependent variable, followed by the independent variables.
No further information need be specified, but users will in virtually every case want to change default settings for the adaptive
Markov Chain Monte Carlo draws - information pertaining to the number of draws, how frequently draws are accepted,
which draws are to be retained upon completion of the algorithm, etc. Default values are described below.

Options

censorvar(varname) Specifies the name of the (left) censoring variable. The censoring variable can vary by observation. If this option
is not specified, it is assumed that the censoring point for all observations is zero.

tau(#) specifies the quantile of interest and should be between zero and one. In the event that the user chooses a value of tau(#)
that is too low, in the sense that all observations at this quantile are censored, a cautioning message is produced, but
drawing nonetheless proceeds. The mnemonic "tau" is used in analogy to the ancillary argument of the check function used to define the
objective function in Chernozhukov and Hong (2003).

draws(#) specifies the number of draws that are to be taken from the joint parameter distribution implied by the model.
The default is 1000.

burn(#) specifies the length of the burn-in period; the first # draws are discarded upon completion
of the algorithm and before further results
are computed. The default is 0.

thin(#) specifies that only every #th draw is to be retained, so if thin(3) is specified, only every third draw is retained.
This option can be used to ease autocorrelation in the resulting draws, as can the option jumble, which randomly mixes draws.
Both options may be applied.

arate(#) specifies the desired acceptance rate of the adaptive MCMC drawing, and should be a number between zero and one, but
is typically in the range .234 to .4 - see Baker (2013) for details. The default is .234.

sampler(string) specifies the type of sampler used. It may be set to either
global or mwg. The default is global, which means that proposed draws
are drawn all at once; if mwg - an acronym for "metropolis within Gibbs" - is instead chosen,
each random parameter is drawn separately as an independent
step conditional on other random parameters in a nested Gibbs step. The default is global, but
mwg might be useful in situations in which initial values are poorly scaled. The workings of
these options are described in greater detail
in Baker (2013).

dampparm(#) is a parameter that controls how aggressively the proposal distribution is adapted
as the adaptive MCMC drawing continues. If set close to one, adaptation is agressive in its early phases
in trying to achieve the acceptance rate specified
in arate(#). If set closer to zero, adaptation is more gradual.

from(string) specifies a row vector of starting values for parameters in order.
In the even that these are not specified, starting
values are obtained via linear regression [regress] R.

fromvariance(string) specifies a covariance matrix for the draws. from(string) can be specified without this,
in which event a covariance matrix scaled to initial regression parameters is used.

saving(string) specifies a location to store the draws from the distribution. The file will contain just the draws after any burn in period
or thinning of values is applied. replace specifies that an existing file is to be overwritten, while append specifies that
an existing file is to be appended, which might be useful if the user wishes to combine results from multiple runs from different
starting points.

noisy specifies that a dot be produced every time a complete pass through the algorithm is finished. After 50 iterations, a "function value"
ln_fc(p) will be produced, which gives the joint log of the value of the posterior choice probabilities evaluated at the latest parameters. While
not an objective function per se, the author has found that drift in the value of this function indicates that the algorithm has not yet converged
or other problems.

median specifies that the criterion function described in Powell (1984) be used instead of the more general form described in
Chernozhukov and Hong (2003). Results are the same as if tau(.5) had been specified and the more complex objective function had been multiplied
by a factor of two.

Examples

Estimating a censored quantile model at the 60% quantile.
The censoring value defaults to zero. 20000 draws are taken, the first 999 draws are dropped, results are jumbled, and every fifth draw is kept.
The first 1000 draws are dropped, and then every fifth draw is retained. Draws are saved as draws.dta:

. webuse laborsub, clear

. mcmccqreg whrs kl6 k618, tau(.6) saving(draws) replace thin(5) burn(999) draws(20000) jumble

Same as above, using a metropolis-within-gibbs sampler, and with an explicit censoring variable:

. webuse laborsub, clear

. gen c=0
{rest}
. mcmccqreg whrs kl6 k618, tau(.6) sampler("mwg") censorvar(c) saving(draws) replace thin(5) burn(999) draws(20000) jumble

Powell's (1984) median estimator:

. webuse laborsub, clear

. mcmccqreg whrs kl6 k618, median sampler("mwg") censorvar(c) saving(draws) replace thin(5) burn(999) draws(20000) jumble

As a last example, it is sometimes useful to estimate a preliminary model using metropolis-within-gibbs sampling, which can often
find the right range for parameters from not-necessarily-great starting values, and then proceed
using a global sampler, which can be much faster. These general ideas are sketched in Baker (2013):

. webuse laborsub, clear

. quietly mcmccqreg whrs kl6 k618, median sampler("mwg") saving(draws) replace thin(5) burn(999) draws(20000) jumble

. mat beta=e(b)

. mat V=e(V)

. mcmccqreg whrs kl6 k618, median from(beta) fromv(V) sampler("global") saving(draws) replace thin(5) burn(999) draws(20000) jumble

Saved results

mcmccqreg saves the following in e():

Scalars

e(N) number of observations

e(df_r) Degrees of freedom

e(draws) Number of draws

e(burn) Burn-in observations

e(thin) Thinning parameter

e(damper) Damping parameter

e(opt_arate) Desired acceptance rate

e(arates_mean) Acceptance rate average (multiple rates only if mwg sampler used)

e(arates_max) Max. acceptance rate for parameters

e(arates_min) Min. acceptance rate for parameters

e(draws_retained) Draws retained after burn-in and thinning

Macros

e(saving) File containing results

e(sampler) Sampler type

e(depvar) Dependent variable

e(indepvars) Independent variables

e(cmd) "mcmccqreg"

e(title) "Powell's mcmc-estimated censored quantile estimator"

e(properties) "b V"

Matrices

e(b) mean parameter values

e(V) variance-covariance matrix of parameters

e(V_init) Initial variance covariance matrix of random parameters

e(b_init) Initial mean vector of random parameters

e(arates) Row vector of acceptance rates of fixed parameters

Functions

e(sample) marks estimation sample

Comments

The basic algorithms used in drawing are described in some detail in Baker (2013). The user might gain a fuller understanding of the options
arate, damper, draws, burn and other options controlling adaptation of the proposal distribution
from a reading of this document.

mcmccqreg requires that the package of Mata functions amcmc be installed, and also requires installation of Ben Jann's moremata
set of extended Mata functions.

Caution!!! - While summary statistics of the results of a drawing are presented in the usual Stata format,
mcmccqreg provides no guidance as to how one should actually go about selecting the number of draws, how draws should be processed,
monitoring convergence of the algorithm, or presenting and interpreting results. Even though the methods are technically not Bayesian
, one would do well to consult
a good source on Bayesian methods such as Gelman et. al. (2009) concerning the practical aspects of
processing results from draws. Of course, Stata provides a wealth of tools for summarizing and plotting
the results of a drawing.

Reference

Baker, M. J. 2013. Adaptive Markov chain Monte Carlo sampling and estimation in Mata. Hunter College working paper 440.

Chernozhukov, V. and H. Hong. 2003. An MCMC approach to classical estimation. Journal of Econometrics 115, 293-346.

Gelman, A., J. B. Carlin, H. S. Stern, and D. B. Rubin. 2009. Bayesian data analysis, 2nd. ed. Boca Raton: Chapman and Hall.

Powell, J. L. 1984. Least absolute deviations estimation for the censored regression model
Journal of Econometrics 25, 303-25.

Powell, J. L. 1986. Censored regression quantiles. Journal of Econometrics 32, 143-55.

Author

This command was written by Matthew J. Baker (matthew.baker@hunter.cuny.edu),
Hunter College and The Graduate Center, CUNY. Comments, criticisms, and suggestions for improvement are welcome.

Also see

Manual: qreg, quantile

Online: amcmc, moremata

Other: (if installed)
mf_amcmc, moremata.