help dfbr

Title

dfbr -- Distribution-free estimation of heteroskedastic
binary response models

Syntax

Sieve nonlinear least squares estimation (default)

dfbr depvar indepvars [if] [in]
[, sieve basis(basis_vars) options]

Local nonlinear least squares estimation

dfbr depvar indepvars [if] [in], local
[normal bandwidth(#) options]

Description

dfbr implements two semiparametric distribution-free estimators
for binary response models with heteroskedasticity:
the sieve nonlinear least squares (SNLLS) estimator of Khan (2013) and
the local nonlinear least squares (LNLLS) estimator of Blevins and Khan (2013).

The sieve nonlinear least squares estimator is the default, but it may
be specified explicitly using the sieve option.
The user may supply a set of basis variables such as polynomial terms
of the independent variables using the basis option.
If no basis elements are provided, then the given independent
variables and a constant are used.

The local nonlinear least squares estimator may be selected using
the local option.
By default the regression function proposed by Blevins and Khan (2013)
is used and dfbr will automatically calculate the feasible optimal
bandwidth.
Alternatively, the user may override this choice by supplying a
custom bandwidth using the bandwidth option.

To select the jackknife local nonlinear least squares estimator with
the normal cdf as the regression function, both the local and
normal options must be given together.
The jackknife weights and bandwidth constants are chosen automatically
and need not be provided, however, custom bandwidth constants can be
given using the k1 and k2 options, with the corresponding
weights being calculated to statisfy the constraints.

For all three estimators, bootstrap estimated standard errors are
reported by default.
Both the number of replications and the random number generator
seed can be specified.
In all cases the coefficient on the last independent variable is
normalized to one.

Dependencies

dfbr requires the moremata package to be installed
(Jann, 2005). See ssc describe moremata for more details
or type ssc install moremata to install.

Options

The dfbr command accepts several options, listed below first
with options specific to either SNLLS and LNLLS, followed by options
common to both estimators.

Sieve nonlinear least squares

sieve specifies the sieve nonlinear least squares estimator
(default).

basis(basis_vars) provides a list of variables to
use in the linear-in-parameters sieve approximation of the scaling
function.
An intercept term is automatically included in the scale equation
and need not be specified along with the other variables.
If this option is omitted, then a constant and the provided
independent variables are used.

Local nonlinear least squares

local specifies the local nonlinear least squares estimator,
using the alternative nonlinear regression function by default.

normal uses the jackknife local nonlinear least squares estimator
with the standard normal cdf as the nonlinear regression function.
The rule of thumb jackknife weights and rate constants described in
Blevins and Khan (2013) are used.

bandwidth(#) specifies the bandwidth.
If this option is omitted the feasible optimal bandwidth will be
used, following a procedure analogous to that of
Horowitz (1992).
This option has no effect if normal is specified.

k1(#) overrides the first bandwidth constant for the jackknife
estimator and must be specified along with k2(#).

k2(#) overrides the second bandwidth constant for the jackknife
estimator and must be specified along with k1(#).

Common options

noconstant suppresses the constant term (intercept) in the
linear index.

brep(#) specifies the number of bootstrap replications
used to estimate standard errors.
If standard errors are not needed, specify brep(0) to skip
the bootstrap step entirely and report only the estimated coefficients.
Corresponding to Stata's bootstrap, the default value is
brep(50), but this may be too low for many applications.

seed(#) sets the seed of the random number generator used for
bootstrap replications.
This is useful for generating reproducible results.

level(#) sets the confidence level.
The default is level(95) or the global default if changed
using set level.

nmiter(#) sets the number of initial Nelder-Mead iterations.
See [M] optimize for additional details.

nmdelta(#) sets the step sizes for constructing the initial
Nelder-Mead simplex.
See [M] optimize for additional details.

Saved results

dfbr stores the results below in e() upon completion.
After sieve estimation, only the index coefficients are stored in
e(b), with estimated variance-covariance matrix e(V),
but if the estimated sieve parameters are required, the vector of all
parameters is stored in e(alpha) with corresponding
variance-covariance e(V_alpha).

Scalars

e(N) number of observations

e(K) number of coefficients

e(brep) number of bootstrap replications

e(level) confidence level

e(h) bandwidth (local only)

e(k1) jackknife bandwidth constant (local normal only)

e(k2) jackknife bandwidth constant (local normal only)

e(w1) jackknife weight (local normal only)

e(w2) jackknife weight (local normal only)

Macros

e(method) sieve or local

e(cmdname) dfbr

e(depvar) name of dependent variable

e(vce) bootstrap

e(basis) sieve basis (sieve only)

e(properties) b V

Matrices

e(b) coefficient vector

e(V) variance-covariance matrix of the estimators

e(BS) bootstrap replicates

e(start) optimization starting values

e(alpha) estimated parameters alpha (sieve only)

e(V_alpha) variance-covariance matrix for alpha (sieve only)

e(BS_alpha) bootstrap replicates for alpha (sieve only)

Functions

e(sample) marks estimation sample

Examples

We generate a random sample of 1000 observations from a simple binary
response model with normally distributed regressors.
The uniformly distributed error term is first normalized to have mean
zero and variance one and then scaled by a nonnegative function of both
regressors to introduce heteroskedasticity.
We normalize the coefficient on the last independent variable to one
in the data generating process to make the true values and estimates
comparable without scaling.

. set obs 1000

. generate x1 = invnorm(uniform())

. generate x2 = 1 + invnorm(uniform())

. generate u = u = (sqrt(12)*uniform() - sqrt(12)/2) * exp(x1*abs(x2))

. generate y = -0.1 + 0.3 * x1 + x2 - u > 0

The simplest usage is to simply invoke dfbr with only the
dependent and independent variables and no additional options:

. dfbr y x1 x2

To estimate the model using the sieve nonlinear least squares
estimator with second-order polynomial terms, we can first generate the
additional basis variables and then invoke dfbr with the
sieve option:

. generate x1x2 = x1 * x2

. generate x1_2 = x1^2

. generate x2_2 = x2^2

. dfbr y x1 x2, sieve basis(x1 x2 x1x2 x1_2 x2_2)

In Stata 11 and later, one can use factor variable notation to
automatically generate the basis terms without actually generating
and storing any additional variables:

. dfbr y x1 x2, sieve basis((c.x1 c.x2)##(c.x1 c.x2))

This is equivalent to using the manually generated basis
x1 x2 x1x2 x1_2 x2_2 from before.
See [U] fvvarlist for additional details on factor variables.

To estimate the model using the local nonlinear least squares
estimator with the default bandwidth and report standard errors estimated
using 200 bootstrap replications:

. dfbr y x1 x2, local brep(200)

A custom bandwidth can be chosen using the bandwidth option:

. dfbr y x1 x2, local bandwidth(0.1)

To use the jackknife LNLLS estimator, which uses the normal cdf as the
regression function, invoke dfbr with the local and
normal options:

. dfbr y x1 x2, local normal

Implementation Details

For each estimator, dfbr uses six starting values and
returns the best estimate.
Two starting values are the constant vectors of all zeros and
all ones.
The remaining four are based on other, easier to calculate
estimators: ordinary least squares (OLS), least absolute
deviations (LAD), probit, and logit.
These values are stored in e(start).

The bootstrap standard errors and confidence intervals reported
by dfbr are calculated in the same way as those produced
by Stata's bootstrap command.
That is, they are based on the variance matrix of the bootstrap
replicates.
In particular, the reported standard errors are square roots of
the diagonal elements of the variance matrix and the confidence
intervals are based on a normal approximation (i.e., using
the standard errors and critical values of the standard normal
distribution).
The bootstap replicates are stored in the e(BS) matrix
to allow further processing, if desired.

For example, to convert the columns of the e(BS) matrix
to variables in the current dataset named coeff1, coeff2,
and so on, use the svmat command after executing dfbr:

. dfbr y x1 x2, local brep(500)

. matrix BS = e(BS)

. svmat BS, names(coeff)

. summarize coeff*

. correlate coeff*, covariance

For the local nonlinear least squares estimator, we first obtain
an estimate b_1 using the default bandwith, h_1 = _N^(-1/5).
This estimate is then used to estimate the optimal bandwidth h_2,
using a procedure analogous to that of Horowitz (1992).
This procedure was also written in Mata for ease of implementation
and for performance reasons.
Finally, using the bandwidth h_2, we obtain the reported estimates b_2.
This process can be skipped and a custom bandwidth can be used instead
by specifying the bandwidth option.

By default, for each starting value the program begins with at most
10 * K Nelder-Mead iterations, followed by a complete run of BFGS
with analytic gradient and Hessian calculations.
This procedure is more robust to poor starting values that
might be in non-concave regions of the objective function, while
switching to a more accurate gradient-based method before reporting
the final estimates.
The maximum number of initial Nelder-Mead iterations can be adjusted
using the nmiter option, where using nmiter(0) skips this
initial step completely.
The initial Nelder-Mead simplex step sizes are set to a vector of ones
by default, but can be set to a vector equal to some constant delta
using nmdelta(delta) option.
The maximum number of BFGS iterations can be controlled by using
set maxiter.

Suggested Citation

When using dfbr in published work, please cite either the
Stata Journal paper (Blevins and Khan, 2013a) or the relevant
paper for the specific estimator used (or both). The sieve nonlinear
least squares estimator was developed by Khan (2013) and the local
nonlinear least squares estimator by Blevins and Khan (2013b).

References

Blevins, J. R. and S. Khan (2013a).
Distribution Free Estimation of Heteroskedastic Binary Response Models
in Stata.
Stata Journal 13, 588-602.

Blevins, J. R. and S. Khan (2013b).
Local NLLS Estimation of Semiparametric Binary Choice Models.
Econometrics Journal 16, 135-160.

Horowitz, J. L. (1992).
A Smoothed Maximum Score Estimator for the Binary Response Model.
Econometrica 60, 505-531.

Jann, B. (2005).
moremata: Stata module (Mata) to provide various functions.
Available from
http://ideas.repec.org/c/boc/bocode/s455001.html.

Khan, S. (2013).
Distribution Free Estimation of Heteroskedastic Binary Response Models
Using Probit Criterion Functions.
Journal of Econometrics 172, 168-182.

Acknowledgments

We are grateful to Jonah Gelbach, Phil Haile, and Jeff Wooldridge for
useful comments which helped improve dfbr.

Also see

Aritcle: Blevins and Khan (2013).

Authors

Jason R. Blevins
Department of Economics, The Ohio State University
email: jrblevin@sdf.org
web: http://jblevins.org/

Shakeeb Khan
Department of Economics, Duke University
email: shakeebk@duke.edu
web: http://econ.duke.edu/~shakeebk/