*! 14Jan2012
help cdreg

Title

Linear Regression under Measurement Error using Auxiliary Information

Syntax

cdreg
depvar
[indepvars]
[if] [in]
[weight]
[, options]

Basic Syntax
parameters(matname) name of vector that contains the parameters of the conditional distribution. Required unless model(auto) is used.

model(string) parametric family of the conditional distribution used for measurement error and optionally non-response

condvars(varlist) list of variables used to predict the true value if the observed value is not missing. Needs to include a name for the unobserved variable as first element.

mvars(varlist) list of variables used to predict the true value if the observed value is missing. Default is constants only.

masspoint needs to be specified if conditional density contains a mass point

variance(string) adjust variance for estimation error of the parameters of the conditional distribution.

keep keeps the variable that contains the conditional mean of the unobserved variable

regress_options options passed to regress

Advanced Syntax
condmean(string) can be used to provide an analytic formula for the conditional mean of the mismeasured variable if model() is not used.

nrmean(string) can be used to provide an analytic formula for the conditional mean for the non-respondents if model() is not used.

draws(#) number of draws per observation used to simulate conditional mean if neither model() nor condmean()/nrmean() is specified. Default is 40.

predictors(string) comma separated string that contains the number of predictors (incl. constant) for each parameter of the conditional density. Needs to be specified if parameters() does not contain equation names.

mixfunc(pointer) pointers to the functions used in the conditional density for measurement error.

mixpar(string) vector specifying the number of input arguments for the functions in the measurement error part of the likelihood function.

mixtransf(string) specifies parameter transformations for measurement error that need to be implemented before drawing from the conditional density.

wgttrfunc(pointer) pointer to function used to transform weights of mixture components for measurement error

mpfunc(pointer) pointer to the function that transforms the mass point into a probability.

nrfunc(pointer) pointers to the functions used in the conditional density for missing values

nrpar(string) vector specifying the number of input arguments for the functions in the non-response part of the likelihood function.

nrtransf(string) specifies parameter transformations for missing values that need to be implemented before drawing from the conditional density.

nrwgttrfunc(pointer) pointer to function used to transform weights of mixture components for missing values

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

Description

cdreg consistently estimates linear regression models including a variable that is only observed with error using parameter
estimates of the conditional density of the true value given the observed value. Please see the papers in the References
below for more details on the method and how it can be used.

Options

The basic syntax can be used if the conditional distribution comes from (mixtures of) several common parametric distributions. The advanced syntax needs to be used if the parameter vector passed to
cdreg characterizes other densities.

Basic Syntax

parameters(matname) needs to contain the name of the vector in memory in which the parameter estimates of the conditional distribution are stored. The ordering of the parameters in the vector needs
to be as follows:

[mass point parameters] [non-response parameters] measurement error parameters

If the model for non-response or measurement error contains mixtures of densities, it is assumed that the vector does not contain a weight for the first component (as it is implicitly denfined by the other weights)
and the weight of each component is located after the parameters of the component, i.e.:

param for component 1, param for component 2, weight for component 2, param for component 3, weight for component 3, ...

If the vector has equation names, cdreg can infer predictors() from these names, so it does not have to be specified. parameters() is required unless model(auto) is used.

model(string) can be used to specify several parametric models for measurement error and missing values. Can contain one or two of the following options, where the first specifies the model for
measurement error and the second specifies the model for missing values. The options are:

auto: obtains all information from e(). To be used after conddens, does not require second entry for missing values.

normal: (mixture of) normal densities

ltrnorm, rtrnorm, trnorm: truncated normal distributions (left, right and both sides).

mixltrnorm, mixrtrnorm, mixtrnorm: 2 component mixtures of truncated normal distributions (left, right and both sides).

exp: (mixture of) exponential densities with location parameter

weibull: (mixture of) weibull densities with location parameter

t: (mixture of) generalized t-distribution(s) with scale and location parameter, df is constrained to be >=1

mixweit: mixture of a weibull distribution with location parameter and a generalized t-distribution with scale and location parameter

Note: model() does not set which parameters are predicted by the data and which are constants. If this information cannot be obtained from the equation and parameter names of parameters(), it
needs to be entered manually using predictors(). See predictors() for more detail. model() overrides all advanced options required by the specified model except for
predictors. Combining it with advanced options that are not required by the model (such as parameter transformations) should be done with caution.

condvars(varlist) list of the predictors for the missing variable. Needs to include the name of the missing variable (as used
after cdreg) in the first place, followed by the predicting variables in the same order as the appear in the parameter vector specified
in parameters.

mvars(varlist) can be used to specify a list of variables that predicts the true value if the observed value is missing. The default is to use constants only for the parameters in the model for missing values.

masspoint needs to be specified if the conditional density contains a mass point at true=observed to inform program that the parameter vector contains parameters for a masspoint.

variance(string)This option should be used with caution. The two-step variance seems to work, I am not so sure about the bootstrap.

adjusts SEs for the estimation error of the parameter estimates of the conditional distribution. If string is the name of a stata matrix, it will use it as the variance matrix of the parameters in parameters
to calculate SEs for 2-Step estimators as in Newey and McFadden (1994). If the first word of string is bootstrap, it bootstraps SEs by re-sampling, drawing a new parameter vector of the conditional density from its
asymptotic distribution in every iteration. The second entry needs to be the name of the Stata matrix containing the asymptotic variance matrix of the parameter vector specified in parameters. It can include up
to three additional elements to control the re-sampling process: # of draws (default is 50), cluster variable, strata variable (required in that order, intermediate ones cannot be omitted).

keep cdreg calculates or simulates the conditional mean of the unobserved variable, but drops this variable after estimation. Specifying keep overrides this, so the variable remains in the dataset.

regress_options if any options not described here are specified, they will be passed to regress. See regress for more details on which options are allowed.

Advanced Syntax

condmean(string) Can be used to specify the conditional mean function manually. This has to be a string of code mata can evaluate. Please look at the way the local "cm" is defined in
cdreg.ado for some examples. It will likely depend on the matrix of parameters the program creates from the parameter vector (Xb) and the probability of the mass point if specified (mp).

nrmean(string) Can be used to specify the conditional mean function for missing values manually. Please see the description above.

draws(#) If neither model() nor condmean() (and nrmean() are specified, cdreg uses random draws from the conditional density to compute its cnditional mean for each observation.
draws() gives the number of draws per observation, the default is 40.

predictors(string) specifies how many elements of the vector in parameters() belong to each parameter of the conditional distribution. E.g. if the first parameter of the conditional distribution is
predicted by 4 variables and a constant, the first entry of predictors() should be 5, it should be 1 if the first parameter is a constant. Consequently, the sum of the entries of predictors() should be
the same as the length of the parameter vector in parameters(). Required if the parameter vector does not contain equation names that allow cdreg to infer this information.

mixfunc(pointer) should contain pointers to the functions used in the measurement error part of the conditional density (e.g. mixffunc(&rgent() &rgent() for a mixture of two generalized t-distributions.
cdreg will use these pointers to make draws from the conditional density in order to simulate its conditional mean. Note that Stata does not allow pointers to functions that are built-in, so one has
to define a separate function for these. See Pointers to Functions for more details. The functions specified in mixfunc() are reused if the number specified does not match the length
of the parameter vector.

mixpar(string) String of numbers specifying the number of input arguments for each function in mixfunc(). It is assumed that each entry of mixpar() except for the first one is followed by a weight
in the parameter vector in parameters(). mixpar will be repeated to make the number of arguments match the length of the parameter vector if possible. For example, the normal density requires two inputs (mean and
variance), so if the conditional distribution is normal, use mixpar(2). A mixture of two normals can be specified by mixpar(2,2) or mixpar(2), a mixture of a normal and a 3-parameter t distribution
requires mixpar(2,3).

mixtransf(string) mixtransf() can be used to transform parameters before they are used in the functions in mixfunc(). E.g. if the conditional distribution is normal with mean log(Xb), a
log transformation for the first parameter needs to be specified. Each transformation requires three entries in mixtransf(): the first gives the position of the function in mixfunc(), the second
the position of the parameter in that function and the third contains either a pointer to the transformation function or a number (which is added to the parameter). E.g. to take the inverse logit of the second
argument of the first function in mixfunc(), use

mixtransf(1,2,&invlogit())

To implement multiple transformations, simply add more entries to the list, e.g. to additionally add 5.13 to the first parameter of the second function in mixfunc(), use

mixtransf(1,2,&invlogit(),2,1,5.13)

The same parameter can be transformed multiple times with transformations implemented in the order they appear in mixtransf(). Entries are repeated if entries in mixpar() are repeated.

wgttrfunc(pointer) Can be specified if the weights of the mixture distribution for measurement error need to be transformed. Note that the same transformation is applied to all weights, so contrary to
mixtransf(string), wgttrfunc() should only contain the pointer to the function that transforms the weights (e.g. wgttrfunc(&invlogit()).

mpfunc(pointer) specifies pointer to the function that transforms the mass point into a probability, i.e. F() such that Pr(true=observed)=F(Xb). The default is the Probit function (normal cdf).

nrfunc(pointer) Analog of mixfunc() for missing values, see there for details. Contrary to mixfunc(), nrfunc() is not repeated, so it always needs to contain as many entries as there
are components in the mixture for non-response.

nrpar(string) Analog of mixpar() for missing values, see there for details. Contrary to mixpar(), nrpar() is not repeated, so it always needs to contain as many entries as there
are components in the mixture for non-response.

nrtransf(string) Analog of mixtransf() for missing values, see there for details. Like with the options above, entries are not repeated, so all transformations have to be specified.

nrwgttrfunc(pointer) Analog of wgttrfunc() for missing values, see there for details.

Remarks

Variance Estimation

variance() can be used according to the description above to correct the SEs for the estimation of the first stage parameters. The
version that implements the asymptotic formula from Newey and McFadden (1994) calculates the required matrices of derivatives
analytically based on the conditional density specified. Given the complexity of these derivatives, I can't rule out any typos, but I have
used it quite a bit and have not encountered and suspicious results. On the other hand, the bootstrap option draws new parameters from
a joint normal distribution with the specified variance matrix. My impression is that there is some systematic drift in the way Stata
samples these draws, which sometimes leads to odd results. Please use it with caution and let me know if you find any mistakes or have
any suggestions.

Variables predicting parameters

cdreg uses all variables in observed predictors as predictors for the mass point and all parameters for which predict!=1 of the measurement error model. Similarly, all
variables in mvars() are used as predictors for all parameters of the non-response model that are not constants. If some variables are to be excluded from some parameter equations, the corresponding entry
in the parameter vector should be a zero, it should not be excluded from the vector.

Pointers to Functions

In order to integrate over the conditional distribution, cdreg produces random draws from the conditional distribution for each observation. To do so, it needs to be supplied with pointers to the mata
functions that generate random draws from the (components of) the conditional density. A pointer to a function is the mata name of the function prefixed with "&" and followed by "()", i.e. &invlogit() is a
pointer to matas "invlogit" function. See Pointers for more details. These pointers are automatically set with model(), but need to be supplied through mixfunc() and nrfunc()
when using the advanced syntax. The functions should take as many inputs as specified in mixpar() and nrpar() and need to return vectors of random draws from the density that have the same length
as the input vectors. Since Stata does not allow pointers to built in functions (such as rt(), rnormal, etc.), these have to be replaced by user defined functions. E.g. to use a standard t-distribution,
first define the function as follows in mata:
function mrt(df) return(rt(df))
and then run cdreg with option mixfunc(&mrt()). The same applies to functions used for parameter transformations. The following random number functions are already defined in cdreg because the
original functions are built-in functions:

mrnormal(a,b): produces random draws from a normal density with mean a and sd b

rexploc(a,b): produces random draws from an exponential density with location parameter a and scale parameter b.

rweibloc(a,b,c): produces random draws from a weibull density with location parameter a, shape parameter b and scale parameter c

rgent(a,b,c): produces random draws from a generalized t-distribution with location parameter a, scale parameter b and degrees of freedom c (constrained to be >=1)

The following transformation functions are also already defined:

mabs(a): returns the absolute value of a

mneg(a): returns the negative value of a (-1*abs(a)).

mexp(a): returns e^a

Other

If you find any mistakes or have any suggestions for improvements, please send me an email to mittag@uchicago.edu. Feel free to use, change or mutilate this program
for private purpose, but please don't steal it, give due credit.

Examples

Basic Syntax

Regression of unobserved dependent variable income on varlist using obs_inc race age gender as predictors and parameters of a mixture of two normal distributions with mass point stored in matrix "par"

. cdreg income varlist, parameters(par) model(mixnorm) mass condvars(income obs_inc race age gender)

Regression of depvar on the unobserved variable obs_inc using obs_inc race age gender and parameters of a mixture of two t-distributions with mass point stored in matrix "par"

. conddens obs_inc race age gender, parameters(par) model(mixt) condvars(income inc_obs race age gender)

Saved results

cdreg saves all results of regress in e(), see regress for details.

References

Newey, Whitney K., and Daniel L. McFadden. 1994. "Large Sample Estimation and Hypothesis Testing." In Handbook of Econometrics. Vol. 4, ed. Robert F. Engle and Daniel L. McFadden, Chapter 36, 2111-2245. Amsterdam: Elsevier.

Mittag, N. 2013. "A Method of Correcting for Misreporting Applied to the Food Stamp Program." Unpublished Manuscript

Mittag, N. 2013. "Imputations: Benefits, Risks and a Method for Missing Data." Unpublished Manuscript

Author

Nikolas Mittag, University of Chicago
mittag@uchicago.edu