*! version 2.0 09nov2023
help xtdhazard

Title

xtdhazard -- Instrumental Variables and Control Function Estimation of the Discrete-Time Hazard Model

Syntax

xtdhazard estimator depvar indepvars [if] [in] [weight] [, options]

estimator

2sls linear two-stage least squares

logit control function (two-stage residuals inclusion) logit

probit control function (two-stage residuals inclusion) probit

cloglog control function (two-stage residuals inclusion) complementary log-log

variables

depvar binary variable (indicating absorbing state)

indepvars explanatory variables

options

Model
difference(numlist) set order of differencing; difference(1), i.e. (only) using first-differences as instruments, is the default

instruments(varlist) additional, non-internal instruments

noabsorbing forces estimation if depvar does not indicate absorbing state

SE/Robust
vce(vcetype) vcetype may be robust, cluster clustvar, oim (not with 2sls), opg (not with 2sls), or unadjusted (only with 2sls);
vce(robust) is the default

Reporting
level(#) set confidence level; default as set by set level

display_options as for ereturn display

2sls
interactinst use squares and interactions of instruments as additional instruments

nofirststage do not save first-stage coefficients in e(G) and do not perform checks regarding first-stage

underid(string) call underid from within xtdhazard; string is the full syntax of underid

showtest report full results of underid

logit/probit/cloglog
order(#) specify order of control-function polynomial; order(1) is the default

fslink(name) specify first-stage link function for endogenous dummy regressors; name may be linear, logit, or probit; logit is the default

noresgenerate do not permanently save first-stage residuals; do not store in e(b) and report coefficients of first-stage residuals

resname(stub) permanently save first-stage residual as stub_varname; the default for stub is res

replace replace stub_varname if already existent

terza(2017|2023) compute standard errors following Terza (2017) or Terza (2023); 2023 is the default

noanalytic calculate cross-stage derivatives numerically

maximization_options as for logit, probit, and cloglog

The data needs to be xtset before using xtdhazard, timevar needs to be specified; see [XT] xtset.

indepvars may contain factor variables and and time-series operators; see fvvarlist and tsvarlist. factor variables and and time-series operators are not allowed for depvar.

bootstrap is allowed, by and svy are not allowed; see [U] prefix.

pweights, fweights, iweights, and aweights (only with 2sls) are allowed; pweights is the default.

If an estimator other than 2sls is specified, the do-file _llcfbin_v.do may be required to be stored in the ado-path.

Available postestimation commands are the same as for the command that correspond to the respective estimator;
see [R] ivregress postestimation, [R] logit postestimation, [R] probit postestimation,
and [R] cloglog postestimation.

Note, that with the estimators logit, probit, and cloglog, postestimation behavior of xtdhazard is heavily affected by the option noresgenerate.
This in particular applies to predict and margins after xtdhazard; see cfbinout.

Description

xtdhazard implements the linear (first) differences instrumental variables estimator,
suggested in Farbmacher & Tauchmann (2023) for dealing with unit-level unobserved heterogeneity (possibly correlated with indepvars) in the discrete-time hazard model.
xtdhazard also implements related non-linear control-function (cf) estimators.
These procedures address the issue that, conventional (linear) fixed-effects panel estimators (within-transformation, first-differences; see [XT] xtreg),
fail to eliminate unobserved time-invariant heterogeneity and are biased and inconsistent if depvar is a binary dummy indicating an absorbing state.
xtdhazard is essentially a wrapper for ivregress 2sls and, depending on which estimator is specified, for the community-contributed command cfbinout.
xtdhazard temporarily generates first and/or, depending on how difference(#) is specified, higher-order own-differences of indepvars, and uses them as instruments for indepvars.
With estimator 2sls, estimation is by 2sls for which xtdhazard calls ivregress.
With estimators logit, probit, or cloglog, xtdhazard, instead of ivregress, calls cfbinout to run a non-linear control-function (cf, two-stage residuals inclusion) regression;
cf. Wooldridge (2015).
Unlike conventional fixed effects estimation, these estimators (both, 2sls and cf) rest on the assumption that the unobserved heterogeneity is uncorrelated with the first (or higher-order) own-differences of indepvars.

Variables

Dependent Variable

depvar needs to be a binary (either numeric or string) indicator.
The (alphanumerically) smaller value indicates that a unit is still at risk, while the (alpha-numerically) larger value indicates that the absorbing state is reached.
A 0/1 indicator is hence the most obvious choice for coding depvar.
xtdhazard is meant for analyzing single spell settings, that is individual-level sequences of depvar, such as 0,..,0,1 and 0,..,0,0.
For individual-level sequences of the form 0,..,0,1,..,1, xtdhazard does not consider observations for periods later than the first occurrence of 1.
For multiple spell settings, that is sequences like 0,1,0,... or 1,0,1,..., better suited estimation procedures might be available.
For this reason, xtdhazard breaks and returns an error message if depvar is recognized to indicate a (potentially) repeated event, unless the option noabsorbing is specified.

Options

Model

difference(numlist) specifies the order of the differences-transformation that is applied to inpdepvars to generate the instruments.
The default is difference(1) that is first differences.
difference(2) makes xtdhazard use differences in differences as instruments, difference(3) differences in differences in differences, etc.
While considering higher-order differences allows for estimation under alternative weaker assumptions, it makes the identification rest on less variation.
If mumlist is a list of integers, xtdhazard uses simultaneously differences of different orders as instruments.
In such case the model is technically over-identified.

instruments(varlist) specifies further (non-internal) instruments that are used in addition to the internal instruments specified by difference(numlist).

noabsorbing forces xtdhazard to produce estimation results even if depvar is detected not to indicate an absorbing state; see variables.

SE/Robust

vce(vcetype) specifies the method used for estimating standard errors.
robust, cluster clustvar, and unadjusted are available as vcetype with the estimator 2sls.
robust, cluster clustvar, oim and opg are available as vcetype with the estimators logit, probit, and cloglog.
In either case, the default is robust.
Note that with logit, probit, and cloglog, robust and cluster, if specified, are applied to variance estimation in the first and the second-stage.
Yet, aggregating the two variance-covariance matrices to what is finally saved in e(V) still draws on ML theory of two-step estimation (Murphy & Topel (1985) and in particular Terza, 2016, 2017, & 2023),
unless the option noanalytic is specified; see cfbinout Options SE/Robust for details.
xtdhazard does not include an internal bootstrapping routine.
Yet the prefix command bootstrap still allows obtaining bootstrap standard errors.
When using bootstrap clustering at the level of panelvar is essential.
I.e. the bootstrap options cluster() and idcluster() are required.

Reporting

display_option: level(#), noci, nopvalues, noomitted, vsquish, noemptycells, baselevels, allbaselevels, nofvlabel, fvwrap(#), fvwrapon(style),
cformat(%fmt), pformat(%fmt), sformat(%fmt), and nolstretch.
They are essentially the same as for eretun display, to which they are passed through; see [R] eretun display

2sls

interactinst makes xtdhazard use the squares and cross-products of all instruments,
the differenced indepvars and possible additional instruments specified by instruments(varlist), as additional rhs variables in the first-stage regressions.

nofirststage makes xtdhazard not report and not save the coefficients of the first-stage regressions in e(G) and also not report any first stage diagnostics.
This reduces the run time of xtdhazard.
Using the option nofirststage is, however, not recommended because it withholds important information, in particular about possible perfect fits achieved in first-stage regressions.
A perfect in the first stage indicates that the instruments are only valid for the respective rhs variable, if that rhs variable is itself exogenous.

underid(string) makes xtdhazard call the community contributed command underid (Schaffer & Windmeijer, 2020) and report its output along with its own results.
string is the full syntax of underid including the leading command name.
underid implements various useful iv-estimation related tests.
If factor variables syntax is used, however, the use of underid in postestimation is hampered by the feature of xtdhazard to generate the (own-differences) instruments only temporarily.
(When generating the own-differences instruments, xtdhazard needs to find a workaround for combining factor variables syntax with the difference operator D..)
The option unterid allows for using underid after xtdhazard, albeit underid may fail in postestimation.
If no factor variables syntax is used, underid, as well as estat firststage, estat endogeneous, etc., can be used in postestimation in the same way as after ivregress 2sls.
Calling underid from within xtdhazard may greatly increase the run time.

showtest makes xtdhazard display the full output of underid but not only some key results.
showtest has no effect on the output from underid that is saved in e().
Specifying showtest has no effect, if underid(string) is not specified.

lofit/probit/cloglog

order(#) makes xtdhazard use not only the first-stage residuals as control-function but also, depending on how order(#) is specified, higher-order powers of them; cf. ivcloglog.
order(1), i.e. only using the non-transformed residuals, is the default.

fslink(name) specifies a link function for the first-stage.
The default is the fslink(logit) link, i.e. logit regressions are estimated at the first-stage for binary endogenous regressors.
If logit or probit is specified as first-stage link function, xtdhazard uses the respective non-linear outcome model for estimating the first-stage for binary endogenous regressors.
Specifying logit or probit as first-stage link function cfbinout use generalized residuals as auxiliary regressors at the second-stage.
(For logit the generalized residual takes the simple form of the difference between the observed outcome and the fitted success probability.)
With fslink(linear), cfbinout estimates linear first-stage regressions and uses conventional residuals as auxiliary second-stage regressors.
If varlist2 does not contain binary variables specifying fslink(name) has no effect.
If the nonlinear first-stage is subject to quasi-complete separation, xtdhazard equation-wise switches to a linear first-stage.

noresgenerate makes xtdhazard generate the first-stage residuals only temporarily and not report and save in e(b) their coefficients.
This is not only a reporting issue, but also affects the postestimation behaviour of xtdhazard.
With noresgenerate, xtdhazard behaves like ivprobit, twostep and ignores the control function in predicting probabilities and estimating marginal effects.
Without noresgenerate being specified, the predictions one gets from predict, from which in turn marginal effects are calculated by margins, are conditional on the values of the control function;
see a discussion of this issue on stata list.

resname(stub) specifies as stub the prefix for the names of the new variables, in which the first-stage residuals are saved.
If resname(stub) is not specified, res is used as prefix.
In other words, if indepvars consists of the two variables var1 and var2, resname(stub) makes xtdhazard generate the new variables stub_var1 and stub_var2.
If a higher-order control-function polynomial is requested by specifying order(#), the powers of the first-stage residuals receive the prefix-names stub2_, stub3_, etc.

replace allows cfbinout to replace existing variables that have the same name with the residuals of the first stage.
Specifying replace is particularly convenient, if one estimates different specifications of a model but does not want to save the first-stage residuals from all of them.

terza(2017|2023) specifies whether the method of variance-covariance estimation is the one originally proposed by Terza (2017) or the corrected version proposed by Terza (2023).
terza(2023) is the default, which, according to Terza (2023), has a much better basis in statistical theory.
Unlike terza(2017), terza(2023) requires not only calculating first but also second (cross-stage) derivatives of the pseudo-log-likelihood function and is computationally more demanding.
Choosing the (incorrect) 2017 method may be a work-around if cfbinout, terza(2023) fails or takes excessive time to run.
The two methods often give similar estimates. However, depending on the specific application, the difference between them can still be substantial.

noanalytic requests numerical calculation of the cross-stage derivatives of the (pseudo) log-likelihood function, using the Mata function deriv().
Analytically derived cross-stage derivatives are not available for fslink(probit), nor when order(#) is specified other than the default.
For these specifications, cfbinout automatically activates noanalytic and issues a respective message.
Calculating cross-stage derivatives numerically requires the Stata do file _llcfbin_v.do to be stored in the ado-path.
For large models and big data sets, calculating the cross-derivatives numerically may require substantial computing time.
noanalytic is immaterial if terza(2017) specified, since Terza's (2017) approach to variance-covariance estimation does not involve the calculation of cross-stage derivatives.

maximization_options (for the second stage) if estimator is either logit, probit, or cloglog:
difficult, technique(algorithm_spec), iterate(#), tolerance(#), ltolerance(#), nrtolerance(#), qtolerance, nonrtolerance,
and from(init_specs); see [R] maximize

Example

(Borrowed from Rabe-Hesketh & Skrondal, 2012)

Load data (promotion.dta) on pormotions of assistant professors (Long, Allison & McGinnis, 1993).

. use http://www.stata-press.com/data/mlmus3/promotion, clear

Prepare data for being used with discrete-time hazard model. (Code borrowed from Rabe-Hesketh & Skrondal, 2012, p. 763.)

. reshape long art cit, i(id) j(year)

xtset data.

. xtset id year

Generate variables y (binary depvar) and prestige (possibly time-varying indepvar).
(Code borrowed, with some modifications, from Rabe-Hesketh & Skrondal, 2012, p. 764.)

. generate y = (year == dur & event == 1) if year <= dur

. generate prestige = cond(year<jobtime,prest1,prest2)

Use linear first-differences IV estimator.

. xtdhazard 2sls y i.year undgrad phdmed phdprest art cit prestige

Same as above, but using the control-function logit estimator with control-function polynomial of order two.

. xtdhazard logit y i.year undgrad phdmed phdprest art cit prestige, replace order(2)

Use margins for estimating average partial effects on promotion hazard.

. margins, dydx(art cit prestige)

Saved results

2sls

xtdhazard 2sls saves the following in e()
(in major parts passed through from ivregress; descriptions partly borrowed from respective help file):

Scalars

e(N) number of observations (excluding waves eliminated by taking differences)

e(N_g) number of groups (cross-sectional units in panel)

e(N_clust) number of clusters (only saved with vcetype cluster)

e(difference) order of differencing (if not multiple differences used)

e(k_perfect) number of first-stage regressions yielding perfect fit (not saved with option nofirststage)

e(chi2) model chi-squared

e(p) model significance, p-value

e(r2) R-squared

e(r2_a) adjusted R-squared

e(rss) residual sum of squares

e(rmse) root mean squared error

e(mss) model sum of squares

e(df_m) model degrees of freedom

e(rank) rank of e(V)

e(level) confidence level

e(irregular) indicator saved with option noabsorbing:
0 if depvar is regular, 1 if depvar is irregular, -1 if depvar is regular but obs after absorbing state is reached enter estimation sample

e(wgtsum) sum of weights (only saved if weights are specified)

e(kappa) 1 (not applicable to 2sls)

e(iterations) 0 (not applicable to 2sls)

e(j_uid) chi-sq statistic for underidentification (if applicable passed through from underid)

e(df_uid) degrees of freedom of underidentification test (if applicable passed through from underid)

e(p_uid) p-value for underidentification test (if applicable passed through from underid)

e(j_oid) chi-sq statistic for overidentification (if applicable passed through from underid)

e(df_oid) degrees of freedom of overidentification test (if applicable passed through from underid)

e(p_oid) p-value for overidentification test (if applicable passed through from underid)

Macros

e(tvar) name of timevar

e(ivar) name of panelvar

e(predict) program used to implement predict

e(chi2type) Wald

e(depvar) name of depvar

e(vcest) vcetype specified in vce()

e(vcetype) title used to label Std. Err.

e(wtype) weight type (only saved if weights are specified)

e(wexp) = weight expression (only saved if weights are specified)

e(title) Own-differences IV estimation of linear discrete-time hazard model

e(cmdline) command as typed

e(cmd) ivregress

e(cmd2) xtdhazard

e(estimator) 2sls

e(link) linear

e(endog) endogenous rhs variables

e(exog) exogenous variables

e(perfect) perfectly predicted rhs variables

e(interactinst) interactions or nointeractions, depending on option interactinst

e(marginsnotok) predictions disallowed by margins

e(marginsok) predictions allowed by margins

e(predict) program used to implement predict

e(estat_cmd) program used to implement estat

e(footnote) program used to implement footnote display

e(properties) b V

e(rkstat) test statistic (if applicable passed through from underid)

e(vceopt) variance-covariance matrix options (if applicable passed through from underid)

e(rkopt) additional options (if applicable passed through from underid)

Matrices

e(b) vector of estimated coefficients

e(V) estimated coefficient variance-covariance matrix

e(G) matrix of estimated first-stage coefficient (not saved with nofirststage; column names may violate Stata's naming conventions for differences of factor variables)

e(V_modelbased) estimated model-based variance-covariance matrix

Functions

e(sample) marks estimation sample (excluding periods lost because of differencing the data)

logit/probit/cloglog

xtdhazard logit, xtdhazard probit, and xtdhazard cloglog save the following in e()
(in major parts passed through from logit, probit, and cloglog, respectively; descriptions partly borrowed from respective help file):

Scalars

e(N) number of observations (excluding waves eliminated by taking differences)

e(N_g) number of groups (cross-sectional units in panel)

e(N_clust) number of clusters (only saved with vcetype cluster)

e(difference) order of differencing (if not multiple differences used)

e(order) order of control-function polynomial

e(k_perfect) number of collinear first-stage residuals

e(chi2) model chi-squared

e(p) model significance, p-value

e(df_m) model degrees of freedom

e(rank) rank of e(V)

e(ll) pseudo log-likelihood (second stage)

e(ll_0) log likelihood, constant-only model

e(r2_p) pseudo-R-squared

e(level) confidence level

e(irregular) indicator saved with option noabsorbing: 0 if depvar is regular, 1 if depvar is irregular,
-1 if depvar is regular but obs after absorbing state is reached enter estimation sample

e(wgtsum) sum of weights (only saved if weights are specified)

e(converged) 1 if converged, 0 otherwise

e(rc) return code

e(k) number of parameters (second stage)

e(k_eq_model) total number of equations

e(k_eq) 1 number of equations (second stage)

e(k_dv) 1 number of dependent variables (second stage)

e(N_cds) number of completely determined successes (second stage)

e(N_cdf) number of completely determined failures (second stage)

e(p_exog) exogeneity test Wald p-value

e(df_exog) degrees of freedom for chi-squared test of exogeneity

e(chi2_exog) Wald chi-squared test of exogeneity

Macros

e(tvar) name of timevar

e(ivar) name of panelvar

e(predict) program used to implement predict

e(chi2type) Wald

e(depvar) name of depvar

e(vcest) vcetype specified in vce()

e(vcetype) title used to label Std. Err.

e(wtype) weight type (only saved if weights are specified)

e(wexp) = weight expression (only saved if weights are specified)

e(title) Own-differences instruments CF estimation of discrete-time hazard model

e(cmdline) command as typed

e(cmd) either logit, probit or cloglog

e(cmd2) xtdhazard

e(estimator) cf

e(link) link function, either logit, probit or cloglog

e(fslink) linear, fist-stage link-function

e(endog) endogenous rhs variables

e(exog) exogenous variables

e(generated) variables generated by cfbinout

e(perfect) perfectly predicted rhs variables

e(marginsnotok) predictions disallowed by margins

e(marginsok) predictions allowed by margins

e(predict) program used to implement predict

e(estat_cmd) program used to implement estat

e(properties) b V

e(opt) type of optimization (second stage)

e(user) name of likelihood-evaluator program (second stage)

e(ml_method) type of ml method (second stage)

e(technique) maximization technique (second stage)

e(which) max or min, whether optimizer is to perform maximization or minimization (second stage)

Matrices

e(b) vector of estimated coefficients

e(V) estimated coefficient variance-covariance matrix

e(G) matrix of estimated first-stage coefficients (column names may violate Stata's naming conventions for differences of factor variables)

e(V_modelbased) estimated model-based variance-covariance matrix

e(gradient) gradient vector (second stage)

e(ilog) iteration log (second stage)

e(rules) information about perfect predictors (second stage, not saved with estimator cloglog)

e(mns) vector of means of the independent variables

Functions

e(sample) marks estimation sample (excluding periods lost because of differencing the data)

References

Farbmacher, H. and Tauchmann, H. (2023). Linear Fixed-Effects Estimation with Non-Repeated Outcomes, Econometric Reviews 42(8), 635-654.

Long, J.S., Allison, P.D. and McGinnis, R. (1993). Rank Advancement in Academic Careers: Sex Differences and the Effects of Productivity, American Sociological Review 58, 703–722.

Murphy, K.M. and Topel, R.H. (1985). Estimation and Inference in Two-Step Econometric Models, Journal of Business & Economic Statistics 3(4): 370-379.

Rabe-Hesketh, S. and Skrondal, A. (2012). Multilevel and Longitudinal Modeling Using Stata, 3rd edition. College Station, Texas: Stata Press Publication.

Schaffer, M.E. and Windmeijer, F. (2020). underid: Postestimation tests of under- and over-identification after linear IV estimation, Statistical Software Components S458805, Boston College Department of Economics, revised 29 Sep 2020.

Terza, J.V. (2023). Simpler standard errors for two-stage optimization estimators revisited, The Stata Journal 23(4), 1057-1061.

Terza, J.V. (2017). Two-stage residual inclusion estimation: A practitioners guide to Stata implementation, The Stata Journal 17(4), 916-938.

Terza, J.V. (2016). Simpler Standard Errors for Two-stage Optimization Estimators, The Stata Journal 16(2), 368–385.

Wooldridge, J.M. (2015). Control Function Methods in Applied Econometrics, The Journal of Human Resources 50(2), 420-445.

Also see

Manual: [R] cloglog, [ST] discrete, [R] ivprobit, [R] ivregress, [ST] logit, [ST] probit,
[ST] stcox, [ST] streg, [ST] stset, [ST] stsplit, [XT] xtreg, [XT] xtset

Help: [R] cloglog, [R] ivprobit, [R] ivregress, [R] logit, [R] probit,
[ST] stcox, [ST] streg, [ST] stset, [ST] stsplit, [XT] xtreg, [XT] xtset

Online: cfbinout, dthaz, hshaz, ivcloglog, pgmhaz8, underid

Author

Harald Tauchmann

Friedrich-Alexander-Universität Erlangen-Nürnberg (FAU)

Nürnberg,
Germany

E-mail: harald.tauchmann@fau.de

Disclaimer

This software is provided "as is" without warranty of any kind, either expressed or implied. The entire risk as to the quality and
performance of the program is with you. Should the program prove defective, you assume the cost of all necessary servicing, repair or
correction. In no event will the copyright holders or their employers, or any other party who may modify and/or redistribute this software,
be liable to you for damages, including any general, special, incidental or consequential damages arising out of the use or inability to
use the program.

Acknowledgements

I gratefully acknowledge comments and suggestions by Helene Könnecke, Sabrina Schubert, Irina Simankova, Elena Yurkevich and the participants of the 2019 and 2024 German Stata Conferences.