Help for ivcloglog version 2.0.1William Liu (刘威廉) 17 November 2023

ivcloglog -- Complementary log-log model with endogenous covariates (either continuous or functions of observed continuous covariates), instrumented via the control function approach (i.e., 2SRI)

(For more on the complementary log-log model, see [R] cloglog.)

Quick Start

Syntax when the endogenous variables are the auxiliary dependent variables:

ivcloglog
binary_outcome_var
[controls]
[if] [in]
,
auxiliary(endogenous_vars = instruments [, noconstant])
[noconstant
order(integer)
vce(vcetype)
difficult_vce
nogenerate
vhatname(string)
showstages]

Syntax when the endogenous variables are not the auxiliary dependent variables but are functions of them:

ivcloglog
binary_outcome_var
[controls]
[if] [in]
,
auxiliary(auxiliary_dependent_vars = instruments [, noconstant])
endogenous(endogenous_vars)
[noconstant
order(integer)
vce(vcetype)
difficult_vce
nogenerate
vhatname(string)
showstages]

Detailed Syntax

ivcloglog
depvar
[varlist_exog]
[if] [in]
,
auxiliary(varlist_auxdep = varlist_inst [, noconstant])
[endogenous(varlist_endog) other_2ndstage_options display_options}]

options

Required
auxiliary(...) Supply first-stage (auxiliary-model) equations.

These are all assumed to share the same instruments, and second-stage controls (except _cons) are automatically included as regressors.

The dependent variables are taken to be the endogenous variables unless alternative ones are provided using endogenous(varlist).

Optional, 1st-stage
noconstant Request that no constant be added as a first-stage variable.

Optional, 2nd-stage
endogenous(...) Supply endogenous variables if they are not the dependent variables of the first-stage equations.

noconstant Request that no constant be added as a second-stage variable.

order(integer) Specify the desired order (i.e., degree) of the control function polynomial; 1 by default.

vce(vcetype) Specify the desired type of variance-covariance estimate (VCE); the default is vce(robust).

difficult_vce Request different code for obtaining the variance-covariance matrix estimate; use this if (and only if) the default fails.

nogenerate Request that the control functions not be added to the dataset.

vhatname(string) Supply name of first-stage residuals; default is "vhat".

showstages Request that the output from the first-stage regress regressions and second-stage cloglog regression be shown.

Reporting
... Standard display options (i.e., "reporting options") are also allowed; see [R] Estimation options.

by is allowed; see [D] by.

varlist_exog, varlist_inst, and varlist_endog may contain factor variables; see [U] fvvarlist.

depvar, varlist_exog, varlist_auxdep, varlist_inst, and varlist_endog may contain time-series operators; see [U] tsvarlist.

Duplicate variables (i.e., the same variable names appearing more than once) in varlist_exog, varlist_auxdep, varlist_inst, and varlist_endog are ignored.

Dependencies

(1) moremata, available on SSC

Description

ivcloglog is essentially the same thing as ivprobit, twostep but for the cloglog model; see [R] ivprobit and [R] cloglog.
ivcloglog estimates a complementary log-log model with instrumenting of endogenous variables via the control function approach (also known in statistics as 2SRI - two-stage residuals inclusion).
This just means that transformed versions of the residuals of the first stage regressions (i.e., the "auxiliary models") are included as regressors in the second stage (i.e., the "primary model").
In the case of ivcloglog, a linear first stage and polynomial control functions are used - the latter just means that powers of the residuals are used.

An important use case is that ivcloglog allows users to estimate a Prentice and Gloeckler (1978) discrete-data proportional hazards model with endogenous covariates (either continuous or functions of observed continuous covariates),
just like how the basic version of the model (i.e., with all covariates exogenous) can be estimated using cloglog.

For more information, see the mutually complementary Liu (2023) and Palmer (2023). Liu (2023) is a theory guide and Palmer (2023) is an empirical guide with a real-data application to loan default.

A Brief Introduction to the Prentice and Gloeckler (1978) Model

The Prentice and Gloeckler (1978) discrete-data (i.e., discrete- and grouped-time) proportional hazards model
is a flexibly parametric survival model for discrete-time data that is analogous to Cox's (1972) continuous-time proportional hazards model.
One convenient way to estimate it involves expressing it as a complementary log-log model (Allison, 1982; Jenkins, 1995).
This can be done through a few steps:

(1) If not the case already, format the data as a panel (typically unbalanced) where the observations for each entity i end after event occurrence. In a panel, this means dropping observations after event occurrence.

(2) If not the case already, generate the outcome variable - a binary indicator for event occurrence that is 1 in the time period of the event and 0 otherwise.

(3) Using the resulting dataset, simply estimate a cloglog model using the aforementioned outcome variable and with fixed effects for each time period included as controls.

(For a user-created command that automates these steps and estimates a model with exogenous covariates, see pgmhaz8 [Jenkins, 2004].)

The process for estimating a model with endogenous covariates is identical, except with the use of ivcloglog instead of cloglog.

Options

Required Options

auxiliary(varlist = varlist) supplies the first-stage equations (i.e., the "auxiliary models").
Specifically, each auxiliary-model dependent variable is linearly regressed on the instruments: the first-stage controls and external instruments (named so since the first-stage controls are technically instruments too);
you must specify what auxiliary-model dependent variables and instruments are to be used.
(The dependent variables go on the left side of the "=" and the instruments go on the right side.)
Powers of the residuals from the first-stage regressions are then included as regressors in the second stage (i.e., the "primary model").
Like ivprobit, all equations are assumed to share the same instruments,
and all second-stage controls are included as first-stage regressors.
See Remarks - Inclusion of Second-Stage Controls in the First Stage in this help file for the reasoning behind the latter.

Optional Options

noconstant requests that no constant be added as a variable in the first or second stage, depending on where the option is supplied.

endogenous(varlist) supplies the endogenous variables.
By default, the endogenous variables are assumed to be the first-stage (auxiliary-model) dependent variables;
if this is not the case, use this option to supply the names of the endogenous variables.
ivcloglog will include these variables in the second stage rather than the auxiliary-model dependent variables.

order(integer) specifies the desired order (i.e., degree) of the control function polynomial. This is 1 by default, which represents a linear control function.
This means that, for each first-stage (auxiliary-model) equation eq, only vhatname_eq_1 will be included as a variable in the second stage.

vce(vcetype) specifies the desired type of variance-covariance estimate (VCE); the default is vce(robust). Currently, vcetype is only allowed to be robust or cluster.

difficult_vce requests different code for obtaining the variance-covariance matrix estimate; use this if (and only if) the default fails.
The "only if" is because the default code is slightly faster.
Currently, this option is only implemented for one-way clustered standard errors.

The default code involves handing the analytical derivatives of the "residual functions" to Stata.
(Stata "residual functions" equal the moment functions after being multiplied by the respective regressors.)
Stata will then automatically calculate the VCE sandwich formula estimator as part of the gmm call.
The default code can fail due to floating-point imprecision.

As an example, consider having many fixed effect levels and observations.
Without transforming the data, these fixed effect levels will correspond to very sparse columns in the data matrix.
Unfortunately, for nonlinear models, there is no general way of transforming the data to get an equivalent model, so we have to use that data matrix.
(In contrast, in a linear model, you can just do the "within transformation": demeaning the data in groups specified by the levels of the fixed effects).
Consequently, the matrix of moment function derivatives G may be near-singular: the sparse columns in the data matrix mean that changing
the corresponding fixed effect parameters affects the moment functions very little, resulting in near-zero columns in G.
Stata may interpret these near-zero columns as actually zero, declare that G is singular,
and refuse to solve GVG' = Omega (this is just the sandwich formula for just-identified GMM rearranged) for the VCE matrix V.

On the other hand, difficult_vce requests that the VCE be manually calculated with a custom Mata subroutine.
The key difference is that it will use lusolve() with a tolerance of zero to solve GVG' = Omega.
The tolerance is just the threshold at which Stata declares that A in some linear system of equation AX = B is singular.
ivcloglog already checks the data matrix for collinearity with _rmcoll, so checking G for singularity
is unnecessary and can only result in problems like the example above.
(It is trivial to prove that the data matrix being full rank implies that G is full rank too.)
Although the singularity-checking in lusolve() cannot be disabled, the next best thing is to set the tolerance to zero.
This means only treating 0 as zero rather than also floating-point numbers that are close enough to zero.

nogenerate requests that the control functions not be added to the dataset.
Specifically, the control functions are composed of powers of the first-stage residuals;
these powers of the first-stage residuals will be kept if nogenerate is not supplied.

vhatname(string) provides the names for the "vhats", the residuals of the first stages.
Specifically, the control function for first-stage (auxiliary-model) equation eq is composed of powers of vhat with names taking the form vhatname_eq_power.
The default vhatname is "vhat".

showstages requests that the output from the first-stage regress regressions and second-stage cloglog regression be shown.
All this does is prevent quietly from being added in front of them. showstages allows you to examine the original output.
It can contain useful information, such as which variables were omitted due to being perfect predictors (in the second stage) or due to collinearity (in the first stage).
Note that the standard errors for the cloglog output will be incorrect.

Remarks

Allowable Endogenous Covariates

ivcloglog assumes that the auxiliary-model dependent variables are continuous. The explanation for this is as follows (Liu, 2023):
It is well-known that we can always run a linear first stage if the second stage is linear (Angrist & Pischke, 2009; Kelejian, 1971).
Even if the true auxiliary model (i.e., "first stage") is non-linear, assuming that the true primary model (i.e., "second stage") is linear, under typical 2SLS assumptions, the resulting estimates will still be consistent.
This is why running a non-linear first stage in such a scenario is considered a "forbidden regression" (Angrist & Pischke, 2009; Hausman, 1975) -
if you did so, the resulting estimates would be much less robust to misspecification since their consistency is only guaranteed under strong assumptions.
Unfortunately, when the primary model is non-linear, this result no longer applies, and we cannot freely impose a linear auxiliary model.
This means that the use of non-continuous auxiliary-model dependent variables will render the ivcloglog results inconsistent, though it may be possible to interpret them as an approximation to the ground truth.

Consequently, endogenous covariates in ivcloglog must be either continuous or discrete but functions of the auxiliary-model dependent variables.
For example, the binary variable 1(x>0) is an allowed endogenous variable if and only if x is observed and is supplied as an auxiliary-model dependent variable.
If x is not observed, then 1(x>0) is just a regular binary variable and is not allowed as an endogenous variable.
For an example, see Examples - A Discrete Endogenous Covariate with Instrumenting via a Linear Control Function.

First-Stage Standard Errors

The first-stage standard errors from the gmm call will be larger than those from the regress call.
This is because they are adjusted for the fact that we are also doing second-stage estimates.
However, this is unnecessary because the first-stage estimates are unaffected by the second-stage estimates.
The SEs from regress should be preferentially used (except in the unlikely case that you wish to compare the first-
and second-stage parameter estimates, which would require one, consistent definition of variance and covariance).

Selecting a Variance-Covariance Matrix Type

Because the cloglog model is a binary outcome model that assumes i.i.d. observations,
a correctly specified model will always have homoskedastic standard errors (Wooldridge, 2010).
These are simply standard errors (SEs) that are calculated under this assumption of i.i.d. observations.

In practice, it is impossible to perfectly specify any model; consequently, you may wish to use other, more robust SEs.
Of course, if you need non-homoskedastic SEs, then your point estimates will in typically be biased and inconsistent.
Nevertheless, using more robust SEs under misspecification will still imperfectly increase the robustness of your hypothesis testing, improving inference.
Specifically, whilst the true coverage probability of a given hypothesis test statistic will typically not converge to the nominal coverage probability,
it will typically at least converge to somewhere closer when using more robust SEs.

oim, opg, jackknife, and bootstrap) are all valid choices for vcetype but are not yet implemented for ivcloglog.
oim and opg correspond to the assumption of i.i.d. observations (which results in homoskedastic standard errors).
They should not be confused with vce(unadjusted), which not only assumes i.i.d. observations but also that the moment functions are linear.
This is nonsensical for ivcloglog, so vce(unadjusted) is disallowed.

Choosing Factor Variable Base Categories

ivcloglog calls gmm; consequently, ivcloglog can sometimes throw a factor variable base category conflict error due to the way gmm is programmed.
This occurs when the same control variable has different base categories specified in two or more first- or second-stage equations.
One situation where that can happen is when the collinearity-checking drops different levels of a factor variable in different equations.
The root cause of the factor variable base category conflict error is that, via the gmm call, all parameter estimates are stored in the same matrix but with their equation names stripped.
This causes Stata to produce a factor variable base category conflict error because it incorrectly thinks that you are trying to estimate a single equation with multiple base categories specified for the same control variable.
To get around this Stata bug, either use the b. prefix (to select the same base category) or the ibn prefix (to request no base category) for that control variable in all equations.
The latter option is often easier.
See [U] fvvarlist for help with factor variable syntax.

Perfect Predictors

"Perfect predictors" are variables with (positive or negative) infinite coefficients. These variables and the observations where they are non-zero are excluded.
The reasoning is that the hill-climbing numerical algorithms in Stata's maximum likelihood estimation procedures will result in estimates that diverge to infinity, so excluding these variables improves numerical stability.
However, if you just exclude these variables, you would get incorrect estimates, so we also need to exclude the corresponding observations where these variables are non-zero.
This is because the infinite coefficients imply that the effects of these observations "drown out" the effects of everything else in the likelihood.
In other words, such observations produce score contributions of zero for all other variables,
so we can exclude these observations without changing the theoretical probability limit of the estimates whilst improving the numerical convergence.
See [R] probit for related, simpler discussion.

Note: non-binary variables omitted due to being perfect predictors may not be correctly acknowledged as such by Stata.
_rmcoll may instead claim that they are omitted due to collinearity.

Inclusion of Second-Stage Controls in the First Stage

Just like ivprobit, all second-stage controls are included in the first stage for robustness.
(The only exception is the constant term optionally provided by Stata, _cons, which can be omitted in the first stage with the option noconstant.
Only do this if the constant term would otherwise be collinear with other variables,
e.g., fixed effects, and you want to drop the constant instead of one of those other variables.)
This is important for instrumental variable models in general because it improves efficiency and robustness.
Adding more valid instruments obviously improves the efficiency, but the reason why doing so improves the robustness may be less obvious.
The reasoning is analogous to that for 2SLS.
For 2SLS under standard assumptions, including the second-stage controls in the first stage guarantees that they will be orthogonal to the first-stage error term,
which shows up in the new, composite second-stage error term.
As a result, this orthogonality condition does not need to be separately assumed.
Similarly, for the complementary log-log model instrumented via the control-function approach (ivcloglog) under standard assumptions,
including the second-stage controls in the first stage guarantees that the new second-stage error term will be standard Gumbel after conditioning on all of the second-stage covariates (Liu, 2023).
Consequently, the condition that this error term remains standard Gumbel after including the second-stage controls in the conditioning does not need to be separately assumed.

Strictly speaking, it is only important that the second-stage controls be inputted into the first stage;
it is still perfectly fine if some of them are dropped in the first stage due to collinearity (Liu, 2023).
This is because conditioning on a set of variables implies that you can include any linear combination of them in the conditioning without affecting the result.
More specifically, any covariates that are dropped due to collinearity can be expressed as linear combinations of the retained covariates -
but, this means that conditioning on the included covariates is equivalent to also conditioning on the dropped variables as well!

One-Sample Estimation

ivcloglog makes sure that the first-stage and second-stage regressions all use the same sample. This is not strictly necessary - for example, see Angrist and Krueger (1995).

Examples

A Basic Model with Instrumenting via a Linear Control Function

This setup is exactly the same as Example 2 in the [R] ivprobit pdf manual, except that the second stage is cloglog rather than probit.

. use "https://www.stata-press.com/data/r18/laborsup", clear

. ivcloglog fem_work fem_educ kids, auxiliary(other_inc = male_educ) vhatname(vhat) vce(robust) nogenerate

(click to run example)

A Discrete Endogenous Covariate with Instrumenting via a Linear Control Function

If some of your endogenous covariates are discrete but functions of the auxiliary dependent variables,
simply include all endogenous variables (continuous and discrete) inside the option endogenous(varlist).
In this example, suppose that this setup is the same as the previous example except that high_other_inc and other_inc are our two endogenous covariates,
where high_other_inc is an indicator for whether other_inc is greater than 50.

. use "https://www.stata-press.com/data/r18/laborsup", clear

. gen high_other_inc = (other_inc > 50) // Generate the other endogenous variable

. ivcloglog fem_work fem_educ kids, auxiliary(other_inc = male_educ) endogenous(high_other_inc other_inc) vhatname(vhat) vce(robust) nogenerate

(click to run example)

A Prentice and Gloeckler (1978) Model with Instrumenting via a Quadratic Control Function

In this last example, the treatment variable, drug, is a binary variable and is not continuous.
The fact that the auxiliary model (i.e., "first stage") is a linear probability model means that the auxiliary model is, strictly speaking, misspecified.
Consequently, the results from this estimation will only be an approximation to the ground truth.
An explanation in this help file of why this is the case is found in Remarks - Allowable Endogenous Covariates.

. sysuse cancer, clear

. gen id = _n

. recode drug 1=0 2=1 3=. // Recoding endogenous variable

. label values drug . // Remove value labels to prevent confusion

. expand studytime // Structure dataset so that each time period corresponds to one observation

. bysort id: gen time = _n // Time period

. bysort id: gen event = (died & _n == _N) // Event indicator

. gen external_instrument = drug + rnormal(0, 1) // Generate a fictional instrument just so we have one for demonstration purposes

. ivcloglog event ibn.time age, auxiliary(drug = external_instrument, noconstant) vhatname(vhat) noconstant order(2) vce(cluster id) nogenerate

(click to run example)

Note that noconstant being supplied in both stages is not strictly necessary since the results are essentially the same otherwise -
without noconstant, one of the time fixed effects would simply be dropped to prevent collinearity.
Also note that clustering by id is not necessary, but will increase robustness in case of misspecification.
Similarly, adding time fixed effects to the first stage is also not required, but doing so enhances robustness.

Stored Results

cloglog stores the following in e():

Scalars

e(N) number of observations

e(k) number of first- and second-stage parameters

e(endog_ct) number of endogenous regressors

e(auxdep_ct) number of first-stage (auxiliary-model) dependent variables

e(N_clust) number of clusters

e(chi2) Wald chi-squared test statistic for significance of original (i.e., excluding control function terms) second-stage variables, not including any intercept

e(df_m) degrees of freedom of the above chi-squared test statistic

e(p) p-value of the above chi-squared test statistic

e(ll) log-likelihood of the cloglog second stage (full model)

e(ll_0) log-likelihood of the cloglog second stage (constant-only model)

e(rank) rank of e(V), which equals e(k) if e(V) is full-rank

e(ic) number of iterations for cloglog

e(rc) return code for cloglog

e(converged) 1 if cloglog converged, 0 otherwise

Macros

e(cmdline) command as typed

e(cmd) cloglog

e(depvar) name of the dependent variable, i.e., the outcome variable

e(exog) names of the exogenous variables specified in the second stage, which are also included in the first stage

e(endog) names of the endogenous variables

e(auxdep) names of the first-stage (auxiliary-model) dependent variables

e(inst) names of the instruments, including the exogenous variables added from the second-stage

e(vce) vcetype specified in vce()

e(clustvar) name of cluster variable

e(properties) b V

Matrices

e(b) coefficient vector containing the first- and second-stage parameter estimates

e(V) variance-covariance matrix of the first- and second-stage parameter estimates

Functions

e(sample) marks estimation sample

Author

William Liu (刘威廉), pre-doctoral research assistant at MIT, MIT Sloan, and Harvard

Acknowledgements

My ivcloglog command is inspired by Dr. Enrique Pinzon's (2020; Stata Conference) presentation on implementing control functions in Stata.
His presentation has helped teach me how to write a gmm moment evaluator program.
In addition, Enrique shared the code for his cfunction command with me.
It has been extremely useful for learning how to code a Stata command.
Many thanks to Enrique, whose assistance has been invaluable for the development of ivcloglog!

References

Allison, P. D. (1982). Discrete-time methods for the analysis of event histories. Sociological methodology, 13, 61-98.

Angrist, J. D., & Krueger, A. B. (1995). Split-sample instrumental variables estimates of the return to schooling. Journal of Business & Economic Statistics, 13(2), 225-235.

Angrist, J. D., & Pischke, J. S. (2009). Mostly harmless econometrics: An empiricist's companion. Princeton university press.

Cox, D. R. (1972). Regression models and life‐tables. Journal of the Royal Statistical Society: Series B (Methodological), 34(2), 187-202.

Hausman, J. A. (1975). An instrumental variable approach to full information estimators for linear and certain nonlinear econometric models. Econometrica, 727-738.

Jenkins, S. P. (1995). Easy estimation methods for discrete-time duration models. Oxford bulletin of economics and statistics, 57(1), 129-138.

Jenkins, S. P. (2004) PGMHAZ8: Stata module to estimate discrete time (grouped data) proportional hazards models. Statistical Software Components S438501, Boston College Department of Economics, revised 17 Sep 2004.

Kelejian, H. H. (1971). Two-stage least squares and econometric systems linear in parameters but nonlinear in the endogenous variables. Journal of the American Statistical Association, 66(334), 373-374.

Liu, W. (2023) A theory guide: Instrumenting a discrete-data proportional hazards model with control functions. Working Paper.

Palmer, C. (2023) An IV hazard model of loan default with an application to subprime mortgage cohorts. MIT Working Paper.

Pinzon, E. (2020) GMM with first-step residuals: A recipe for control-function S.E.s. London Stata Conference 2020, Stata Users Group. https://EconPapers.repec.org/RePEc:boc:usug20:12.

Prentice, R. L., & Gloeckler, L. A. (1978). Regression analysis of grouped survival data with application to breast cancer data. Biometrics, 57-67.

Wooldridge, J. M. (2010). Econometric analysis of cross section and panel data. MIT press.