rbicopula
Stata module to estimate recursive bivariate copula regressions
Table of Contents
- Model Estimation
- Conventional Postestimation Commands
- Treatment Effects
- Marginal Effects
- Examples
- References
- About
- How to install
- Changelog
1. Model Estimation
rbicopula is a user-written command that fits a recursive bivariate copula regression using maximum likelihood estimation. It is implemented as an lf1 ml evaluator. The model involves an outcome equation with the dependent variable depvar and a treatment equation with the dependent variable depvar_en. Both dependent variables depvar and depvar_en have to be binary and coded as 0/1 variables.
rbicopula allows to choose from a set of different parametric bivariate distributions, so called copula functions. The bivariate residual distribution is specified to have gaussian marginals and a choice of copula functions to represent the dependence pattern between the equations' residuals. Using copula(gaussian) as copula type is equivalent to estimate the model by rbiprobit. For more information about copula functions and their properties, see Trivedi/Zimmer (2007) in the references.
For copula(frank) the user-written command integrate has to be installed additionally by typing
ssc install integrate, replace
Syntax
rbicopula depvar [=] [indepvars] [if] [in] [weight], endogenous(depvar_en [=] [indepvars_en] [, enopts]) [options]
where depvar is the outcome variable, indepvars are the independent variables of the outcome equation, depvar_en is the treatment variable, and indepvars_en are the independent variables of the treatment equation. rbicopula automatically adds the treatment variable depvar_en as an independent variable on the right-hand side of the outcome equation. Independent variables may contain factor variables and may be different or the same. All variables may contain time-series operators. rbicopula is limited to a recursive model with two equations and provides two tailored postestimation commands and some common Stata postestimation commands.
Options
options Description
-----------------------------------------------------------------------------------------------------------
Model
copula(copulatype) specify copula function to control dependence pattern between equations.
copulatype may be product, gaussian, fgm, plackett, clayton, frank, gumbel,
joe, amh; default is copula(gaussian)
noconstant suppress constant term
offset(varname) offset variable for outcome equation
constraints(constraints) apply specified linear constraints
collinear keep collinear variables
SE/Robust
vce(vcetype) vcetype may be oim, robust, cluster clustvar, opg, bootstrap, or jackknife
Reporting
level(#) set confidence level; default is level(95)
lrmodel perform likelihood-ratio model test instead of the default Wald test
nocnsreport do not display constraints
display_options control columns and column formats, row spacing, line width, display of
omitted variables and base and empty cells, and factor-variable labeling
Maximization
maximize_options control the maximization process; seldom used
coeflegend display legend instead of statistics
-----------------------------------------------------------------------------------------------------------
enopts Description
-----------------------------------------------------------------------------------------------------------
Model
noconstant suppress constant term
offset(varname) offset variable for treatment equation
-----------------------------------------------------------------------------------------------------------
2. Conventional Postestimation Commands
As for the biprobit, rbiprobit, or probit commands, there are a set of common postestimation commands available for testing hypotheses, obtaining model statistics, predicting responses and saving estimation results.
Command Description
-----------------------------------------------------------------------------------------------------------
contrast contrasts and ANOVA-style joint tests of estimates
estat ic Akaike's and Schwarz's Bayesian information criteria (AIC and BIC)
estat summarize summary statistics for the estimation sample
estat vce variance-covariance matrix of the estimators (VCE)
estat (svy) postestimation statistics for survey data
estimates cataloging estimation results
* hausman Hausman's specification test
lincom point estimates, standard errors, testing, and inference for linear combinations of
coefficients
* lrtest likelihood-ratio test
nlcom point estimates, standard errors, testing, and inference for nonlinear combinations of
coefficients
predict predictions, residuals, influence statistics, and other diagnostic measures
predictnl point estimates, standard errors, testing, and inference for generalized predictions
pwcompare pairwise comparisons of estimates
test Wald tests of simple and composite linear hypotheses
testnl Wald tests of nonlinear hypotheses
-----------------------------------------------------------------------------------------------------------
* hausman and lrtest are not appropriate with svy estimation results.
Syntax for predict
predict [type] newvar [if] [in] [, statistic nooffset]
predict [type] {stub*|newvar_eq1 newvar_eq2 newvar_atanrho} [if] [in] , scores
predict creates a new variable containing predictions such as probabilities, linear indexes, and standard errors. The following statistics are available both in and out of sample; type predict ... if e(sample) ... if wanted only for the estimation sample.
statistic Description
--------------------------------------------------------------------------------------------------
Main
p11 Pr(depvar=1, depvar_en=1); the default
p10 Pr(depvar=1, depvar_en=0)
p01 Pr(depvar=0, depvar_en=1)
p00 Pr(depvar=0, depvar_en=0)
pmarg1 Pr(depvar=1); marginal success probability for outcome equation
pmarg2 Pr(depvar_en=1); marginal success probability for treatment equation
pcond1 Pr(depvar=1 | depvar_en=1)
pcond2 Pr(depvar_en=1 | depvar=1)
xb1 linear prediction for outcome equation
xb2 linear prediction for treatment equation
stdp1 standard error of the linear prediction for outcome equation
stdp2 standard error of the linear prediction for treatment equation
--------------------------------------------------------------------------------------------------
3. Treatment Effects
rbicopula tmeffects [if] [in] [weight] [, options]
rbicopula tmeffects estimates the average treatment effect, average treatment effect on the treated, and the average treatment effect on the conditional probability.
Options
options Description
-----------------------------------------------------------------------------------------------------------
Main
tmeffect(effecttype) specify type of treatment effect; effecttype may be ate, atet, or atec; default is
ate
SE
vce(delta) estimate SEs using delta method; the default
vce(unconditional) estimate SEs allowing for sampling of covariates
Advanced
noweights ignore weights specified in estimation
noesample do not restrict rbicopula tmeffects to the estimation sample
force estimate treatment effects despite potential problems
Reporting
level(#) set confidence level; default is level(95)
post post margins and their VCE as estimation results
display_options control columns and column formats, row spacing, line width, and factor-variable
labeling
-----------------------------------------------------------------------------------------------------------
pweights, fweights, and iweights are allowed; see weight.
Description of tmeffect()
tmeffect(effecttype) specifies the type of the treatment effect of the treatment variable depvar_en on a specific response.
| Effecttype | Description |
|---|---|
ate |
rbicopula tmeffects reports the average treatment effect, i.e. the finite difference between Pr(depvar=1) given depvar_en=1 and Pr(depvar=1) given depvar_en=0. Thus, ate is the difference between the marginal probability of outcome success given treatment success and the marginal probability of outcome success given treatment failure. |
atet |
rbicopula tmeffects reports the average treatment effect on the treated, i.e. the finite difference between Pr(depvar=1,depvar_en=1) given depvar_en=1 and Pr(depvar=1,depvar_en=1) given depvar_en=0, computed and averaged only for the treated observations. Thus, atet is the difference between the joint probability of outcome and treatment success conditioned on treatment success and the joint probability of outcome and treatment success conditioned on treatment failure. |
atec |
rbicopula tmeffects reports the average treatment effect on the conditional probability, i.e. the finite difference between Pr(depvar=1|depvar_en=1) and Pr(depvar=1|depvar_en=0). Thus, atec is the difference between the conditional (on treatment success) probability of outcome success and the conditional (on treatment failure) probability of outcome success. |
NOTE:
Currently, treatment effects cannot be estimated for the Gaussian copula. Please use rbiprobit command instead. You can download rbiprobit from SSC archive using the following command in Stata
ssc install rbiprobit
4. Marginal Effects
rbicopula margdec [if] [in] [weight] [, response_options options]
Margins are statistics calculated from predictions of a previously fit model by rbicopula at fixed values of some covariates and averaging or otherwise integrating over the remaining covariates. The rbicopula margdec command estimates margins of responses for specified values of independent variables in indepvars and indepvars_en and presents the results as a table.
Capabilities include estimated marginal means, least-squares means, average and conditional marginal and partial effects (which may be reported as derivatives or as elasticities), average and conditional adjusted predictions, and predictive margins. For estimation of margins of responses for specified values of the treatment variable depvar_en, please use rbicopula tmeffects. rbicopula margdec won't deliver results in this case.
CAUTION: Limitations of margins after rbicopula
Do not use margins after you have fit your model by using rbicopula if your are interested in marginal means, predictive margins, marginal effects or average marginal effects. margins doesn't account for the recursive nature of the model and will deliver incorrect point estimates and / or incorrect standard errors of the point estimates.
Instead, use the postestimation commands rbicopula margdec and rbicopula tmeffects written explicitly for rbicopula. They cover some but not all options of margins and will deliver correct point estimates and standard errors.
Options
response_options Description
-----------------------------------------------------------------------------------------------------------
Main
effect(effecttype) specify type of effect for margins; effecttype may be total, direct, or indirect;
default is total
predict(pred_opt) estimate margins for predict, pred_opt
dydx(varlist) estimate marginal effect of variables in varlist
eyex(varlist) estimate elasticities of variables in varlist
dyex(varlist) estimate semielasticity -- d(y)/d(lnx)
eydx(varlist) estimate semielasticity -- d(lny)/d(x)
-----------------------------------------------------------------------------------------------------------
options Description
-----------------------------------------------------------------------------------------------------------
SE
vce(delta) estimate SEs using delta method; the default
vce(unconditional) estimate SEs allowing for sampling of covariates
Advanced
noweights ignore weights specified in estimation
noesample do not restrict rbicopula margdec to the estimation sample
force estimate margins despite potential problems
Reporting
level(#) set confidence level; default is level(95)
post post margins and their VCE as estimation results
display_options control columns and column formats, row spacing, line width, and factor-variable
labeling
-----------------------------------------------------------------------------------------------------------
Time-series operators are allowed if they were used in the estimation.
pweights, fweights, and iweights are allowed; see weight.
Description of effect()
effect(effecttype) specifies the effecttype for the margins. Once independent variables are parts of indepvars and indepvars_en, marginal effects can be splitted into a direct and an indirect marginal effect.
| Effecttype | Description |
|---|---|
effect(total) |
rbicopula margdec reports derivatives of the response with respect to varlist in dydx(varlist), eyex(varlist), dyex(varlist), or eydx(varlist), considering the incorporation of varlist in indepvars and/or indepvars_en. |
effect(direct) |
rbicopula margdec reports derivatives of the response with respect to varlist from dydx(varlist), eyex(varlist), dyex(varlist), or eydx(varlist), considering only the incorporation of varlist in indepvars and not taking into account the appearance of varlist in indepvars_en. |
effect(indirect) |
rbicopula margdec reports derivatives of the response with respect to varlist from dydx(varlist), eyex(varlist), dyex(varlist), or eydx(varlist), considering only the incorporation of varlist in indepvars_en and not taking into account the appearance of varlist in indepvars. |
NOTE:
Currently, marginal effects cannot be estimated for the Gaussian copula. Please use rbiprobit command instead. You can download rbiprobit from SSC archive using the following command in Stata
ssc install rbiprobit
5. Examples
Examples for rbicopula
Setup
. webuse class10, clear
(Class of 2010 profile)
Estimation of a recursive bivariate copula regression with a Frank copula
. rbicopula graduate = income i.roommate i.hsgpagrp, ///
> endog(program = i.campus i.scholar income i.hsgpagrp) cop(frank)
Univariate Probits for starting values
Fitting comparison outcome equation:
Iteration 0: log likelihood = -1670.5207
Iteration 1: log likelihood = -1174.1089
Iteration 2: log likelihood = -1163.4298
Iteration 3: log likelihood = -1161.967
Iteration 4: log likelihood = -1161.8185
Iteration 5: log likelihood = -1161.791
Iteration 6: log likelihood = -1161.7856
Iteration 7: log likelihood = -1161.7844
Iteration 8: log likelihood = -1161.7843
Iteration 9: log likelihood = -1161.7842
Fitting comparison treatment equation:
Iteration 0: log likelihood = -1724.5355
Iteration 1: log likelihood = -1512.2212
Iteration 2: log likelihood = -1512.0846
Iteration 3: log likelihood = -1512.0846
Comparison: log likelihood = -2673.8688
Fitting full model:
Iteration 0: log likelihood = -2673.8211
Iteration 1: log likelihood = -2669.3178
Iteration 2: log likelihood = -2668.6718
Iteration 3: log likelihood = -2668.6714
Iteration 4: log likelihood = -2668.6714
Recursive Bivariate Copula Regression (Copula: FRANK)
Number of obs = 2,500
Wald chi2(12) = 957.97
Log likelihood = -2668.6714 Prob > chi2 = 0.0000
------------------------------------------------------------------------------
| Coef. Std. Err. z P>|z| [95% Conf. Interval]
-------------+----------------------------------------------------------------
graduate |
1.program | .3839363 .1915659 2.00 0.045 .008474 .7593987
income | .1451966 .0147468 9.85 0.000 .1162935 .1740997
|
roommate |
yes | .274152 .0593486 4.62 0.000 .1578309 .3904731
|
hsgpagrp |
2.5-2.9 | .9466574 .1354618 6.99 0.000 .6811571 1.212158
3.0-3.4 | 1.950385 .148173 13.16 0.000 1.659971 2.240799
3.5-4.0 | 7.497412 1643.325 0.00 0.996 -3213.36 3228.354
|
_cons | -2.110085 .2279379 -9.26 0.000 -2.556835 -1.663335
-------------+----------------------------------------------------------------
program |
campus |
yes | .74922 .0748645 10.01 0.000 .6024884 .8959517
|
scholar |
yes | .903145 .0580028 15.57 0.000 .7894616 1.016828
income | -.0787123 .009652 -8.16 0.000 -.0976299 -.0597947
|
hsgpagrp |
2.5-2.9 | .0569215 .109988 0.52 0.605 -.1586511 .2724941
3.0-3.4 | .0647886 .1152315 0.56 0.574 -.161061 .2906382
3.5-4.0 | -.0980512 .1780694 -0.55 0.582 -.4470607 .2509584
|
_cons | -.4456948 .1279326 -3.48 0.000 -.696438 -.1949516
-------------+----------------------------------------------------------------
/delta | 2.222322 .7442333 2.99 0.003 .7636514 3.680993
-------------+----------------------------------------------------------------
theta | 2.222322 .7442333 .7636514 3.680993
-------------+----------------------------------------------------------------
tau | .2356647
------------------------------------------------------------------------------
Wald test of theta=0: chi2(1) = 8.91653 Prob > chi2 = 0.0028
Report likelihood-ratio test instead of Wald test
. rbicopula graduate = income i.roommate i.hsgpagrp, ///
> endog(program = i.campus i.scholar income i.hsgpagrp) cop(frank) nolog lrmodel
Recursive Bivariate Copula Regression (Copula: FRANK)
Number of obs = 2,500
LR chi2(11) = 1368.07
Log likelihood = -2668.6714 Prob > chi2 = 0.0000
------------------------------------------------------------------------------
| Coef. Std. Err. z P>|z| [95% Conf. Interval]
-------------+----------------------------------------------------------------
graduate |
1.program | .3839325 .1915628 2.00 0.045 .0084764 .7593886
income | .1451968 .0147467 9.85 0.000 .1162938 .1740998
|
roommate |
yes | .2741528 .0593486 4.62 0.000 .1578317 .3904739
|
hsgpagrp |
2.5-2.9 | .946659 .1354618 6.99 0.000 .6811587 1.212159
3.0-3.4 | 1.950389 .1481729 13.16 0.000 1.659975 2.240803
3.5-4.0 | 7.500715 1659.003 0.00 0.996 -3244.086 3259.087
|
_cons | -2.110086 .2279358 -9.26 0.000 -2.556832 -1.66334
-------------+----------------------------------------------------------------
program |
campus |
yes | .7492212 .0748645 10.01 0.000 .6024895 .8959529
|
scholar |
yes | .9031463 .0580028 15.57 0.000 .7894629 1.01683
income | -.0787123 .009652 -8.16 0.000 -.0976299 -.0597947
|
hsgpagrp |
2.5-2.9 | .0569211 .109988 0.52 0.605 -.1586515 .2724938
3.0-3.4 | .0647879 .1152315 0.56 0.574 -.1610617 .2906375
3.5-4.0 | -.0980515 .1780694 -0.55 0.582 -.4470611 .2509582
|
_cons | -.4456957 .1279326 -3.48 0.000 -.6964389 -.1949524
-------------+----------------------------------------------------------------
/delta | 2.222323 .7442206 2.99 0.003 .7636772 3.680968
-------------+----------------------------------------------------------------
theta | 2.222323 .7442206 .7636772 3.680968
-------------+----------------------------------------------------------------
tau | .2356648
------------------------------------------------------------------------------
Wald test of theta=0: chi2(1) = 8.91684 Prob > chi2 = 0.0028
Prediction after rbicopula
. predict p11, p11
. predict p1, pmarg1
. predict pcond1, pcond1
. sum p11 p1 pcond1
Variable | Obs Mean Std. Dev. Min Max
-------------+---------------------------------------------------------
p11 | 2,500 .3758099 .168123 .0328388 .821138
p1 | 2,500 .6133447 .2697109 .026443 1
pcond1 | 2,500 .7307627 .240151 .0832402 1
Examples for rbicopula margdec
Setup
. webuse class10, clear
(Class of 2010 profile)
. rbicopula graduate = income i.roommate i.hsgpagrp, ///
> endog(program = i.campus i.scholar income i.hsgpagrp) cop(frank)
Compute total average marginal effects of income on the joint probability Pr(depvar=1, depvar_en=1)
. rbicopula margdec, dydx(income) predict(p11) effect(total)
Average marginal effects Number of obs = 2,500
Model VCE : OIM
Expression : Pr(graduate=1,program=1), predict(p11)
dy/dx w.r.t. : income
------------------------------------------------------------------------------
| Delta-method
| dy/dx Std. Err. z P>|z| [95% Conf. Interval]
-------------+----------------------------------------------------------------
income | .0032202 .002847 1.13 0.258 -.0023598 .0088002
------------------------------------------------------------------------------
Compute direct average marginal effects of income on the joint probability Pr(depvar=1, depvar_en=1)
. rbicopula margdec, dydx(income) predict(p11) effect(direct)
Average marginal effects Number of obs = 2,500
Model VCE : OIM
Expression : Pr(graduate=1,program=1), predict(p11)
dy/dx w.r.t. : income
------------------------------------------------------------------------------
| Delta-method
| dy/dx Std. Err. z P>|z| [95% Conf. Interval]
-------------+----------------------------------------------------------------
income | .020748 .0018168 11.42 0.000 .0171871 .0243089
------------------------------------------------------------------------------
Compute indirect average marginal effects of income on the joint probability Pr(depvar=1, depvar_en=1)
. rbicopula margdec, dydx(income) predict(p11) effect(indirect)
Average marginal effects Number of obs = 2,500
Model VCE : OIM
Expression : Pr(graduate=1,program=1), predict(p11)
dy/dx w.r.t. : income
------------------------------------------------------------------------------
| Delta-method
| dy/dx Std. Err. z P>|z| [95% Conf. Interval]
-------------+----------------------------------------------------------------
income | -.0175278 .0021575 -8.12 0.000 -.0217564 -.0132992
------------------------------------------------------------------------------
Compute indirect average marginal effects of all independent variables on the joint probability Pr(depvar=1, depvar_en=0) and plot the results
. rbicopula margdec, dydx(*) predict(p10) effect(direct)
Average marginal effects Number of obs = 2,500
Model VCE : OIM
Expression : Pr(graduate=1,program=0), predict(p10)
dy/dx w.r.t. : income 1.roommate 25.hsgpagrp 30.hsgpagrp 35.hsgpagrp
------------------------------------------------------------------------------
| Delta-method
| dy/dx Std. Err. z P>|z| [95% Conf. Interval]
-------------+----------------------------------------------------------------
income | .0183783 .0015127 12.15 0.000 .0154134 .0213431
|
roommate |
yes | .0347057 .0074373 4.67 0.000 .0201287 .0492826
|
hsgpagrp |
2.5-2.9 | .1088569 .0115855 9.40 0.000 .0861497 .1315642
3.0-3.4 | .2715053 .0142936 18.99 0.000 .2434903 .2995203
3.5-4.0 | .4065801 .01354 30.03 0.000 .3800422 .433118
------------------------------------------------------------------------------
Note: dy/dx for factor levels is the discrete change from the base level.
. marginsplot
Examples for rbicopula tmeffects
Setup
. webuse class10, clear
(Class of 2010 profile)
. rbicopula graduate = income i.roommate i.hsgpagrp, ///
> endog(program = i.campus i.scholar income i.hsgpagrp) cop(frank)
Compute the average treatment effect of program
. rbicopula tmeffects, tmeffect(ate)
Treatment effect Number of obs = 2,500
Model VCE : OIM
Expression : Pr(graduate=1), predict(pmarg1)
Effect : Average treatment effect
dydx w.r.t. : 1.program
------------------------------------------------------------------------------
| Delta-method
| dy/dx Std. Err. z P>|z| [95% Conf. Interval]
-------------+----------------------------------------------------------------
ate | .1064717 .0511033 2.08 0.037 .006311 .2066324
------------------------------------------------------------------------------
Compute the average treatment effect on the treated of program
. rbicopula tmeffects, tmeffect(atet)
Treatment effect Number of obs = 1,352
Model VCE : OIM
Expression : Pr(graduate=1,program=1|program=1) - Pr(graduate=1,program=1|program=0)
Effect : Average treatment effect on the treated
dydx w.r.t. : 1.program
------------------------------------------------------------------------------
| Delta-method
| dy/dx Std. Err. z P>|z| [95% Conf. Interval]
-------------+----------------------------------------------------------------
atet | .0679115 .0330877 2.05 0.040 .0030608 .1327623
------------------------------------------------------------------------------
Compute average treatment effects on the conditional probability of program
. rbicopula tmeffects, tmeffect(atec)
Treatment effect Number of obs = 2,500
Model VCE : OIM
Expression : Pr(graduate=1|program=1)-Pr(graduate=1|program=0), predict(pcond1)-predict(pcond10)
Effect : Average treatment effect on conditional probability
dydx w.r.t. : 1.program
------------------------------------------------------------------------------
| Delta-method
| dy/dx Std. Err. z P>|z| [95% Conf. Interval]
-------------+----------------------------------------------------------------
atec | .2736936 .0164694 16.62 0.000 .2414141 .3059731
------------------------------------------------------------------------------
6. References
Coban, M. (2020). Redistribution Preferences, Attitudes towards Immigrants, and Ethnic Diversity, IAB Discussion Paper 2020/23.
Greene, W.H. (2018). Econometric Analysis, 8th Edition, Pearson.
Hasebe, T. (2013). Marginal effects of a bivariate binary choice model, Economic Letters 121(2), pp. 298-301.
Trivedi, P. and Zimmer, D. (2007). Copula Modelling: An Introduction for Practitioners, Foundations and Trends in Econmetrics} 1(1), pp. 1-111.
7. About
Mustafa Coban
Institute for Employment Research (Germany)
email: mustafa.coban@iab.de
github: github.com/cobanomics
webpage: mustafacoban.de
8. How to Install
The latest version can be obtained via
net install rbicopula, from("https://cobanomics.github.io/rbicopula/")
9. Changelog
10oct2022 (version 1.1.0)
-
rbicopula margdec- Applicable to all copula functions except the Gaussian copula
-
rbicopula tmeffects- Applicable to all copula functions except the Gaussian copula