*! version 2.2.0 10jun2026

help for civregManh Hoang-Ba (hbmanh9492@gmail, Youtube, Facebook, Website)

Title

civreg -- Coplanar (synthetic) instrumental variables (CIV/SIV) regression

Syntax

civreg depvar [exogvars]
(endogvars = [excluded_exogvars])
[if] [in]
,
[civ_options]
[ivreg2_options]

Most options supported by ivreg2 may also be specified.

civ_options

CIV/SIV construction

hete(#) criterion used to identify the optimal coplanar/synthetic instrument (# = 0, 1, or 2); default is hete(0)

d(#) initial value of the nuisance parameter d0; default is d(0.01)

delt(#) grid-search increment for d0; default is delt(0.01)

dmax(#) upper bound (angle measured in degrees) for the search over d0; default is dmax(70)

reps(#) bootstrap replications used to select optimal d0; default is reps(50)

plusrand specifies that an independent random disturbance with zero mean
and variance equal to the variance of the endogenous variable is added to the CIV variable.

cgraph display covariance and correlation graphs of squared first-stage residuals and CIV used in determining the direction of endogeneity

savegraph save the covariance and correlation graphs produced by cgraph

gprefix(name) specify the prefix used for naming graphs saved with savegraph

rcode uses R programming language (via rcall) for random number generation to exactly reproduce R results

FE options

fe specifies one-way (individual) fixed-effects estimator

twfe specifies two-way (individual and time) fixed-effects estimator

maxiter(#) maximum iterations for Halperin APM; default is maxiter(50)

tolerance(#) convergence tolerance for maximum absolute difference; default is tolerance(1e-8)

nolog suppresses the Halperin APM iteration log

civreg passes most standard IV estimation options directly to
ivreg2. See ivreg2 for estimation, variance-covariance,
and reporting options.

civreg requires STATA version 11 or later, ivreg2
version 2.1.15 or later, and relevant STATA packages.

Install and update

To install civreg, type:

. `"ssc install civreg"'

. //raw.githubusercontent.com/ManhHB94/civreg/main/")"'

The latest version of civreg can be found at the following link: https://github.com/ManhHB94/

To update the civreg package to the latest version, run either of the following commands

. `"ado update civreg, update"'

. `"ssc install civreg, replace"'

. //raw.githubusercontent.com/ManhHB94/civreg/main/") replace"'

Citation of civreg

civreg is not an official Stata command. It is a free contribution
to the research community, like a paper. Please cite it as such:

Manh Hoang-Ba, 2026. CIVREG: Stata module to perform coplanar/synthetic instrumental variables regression.
https://ideas.repec.org/c/boc/bocode/s459728.html

Description

civreg estimates linear models with endogenous regressors using the
Coplanar (Synthetic) Instrumental Variables (CIV) method proposed by
Dzhumashev and Tursunalieva (2025), currently available as an arXiv preprint.

Unlike conventional instrumental variables estimators, the CIV method
does not require external instruments. Instead, instruments are constructed
from the observed data using the geometric relationship among the dependent
variable, endogenous regressors, and structural disturbances.

The method is based on the result that the outcome variable, endogenous
regressor, and structural error lie on the same coplanar subspace in the
reduced-form representation of the model. A valid coplanar
instrument projected onto that subspace can be represented as

s = x - k*d0*r

where x is the endogenous regressor, r is orthogonal to x
within the regression plane, d0 is a nuisance parameter, and
k = 1 if cov(x,u) > 0, or -1 if cov(x,u) < 0, with u is the structural error.

The CIV estimator searches for the value of d0 that satisfies the
Dual Tendency (DT) condition. Under the DT condition, a valid
coplanar instrument simultaneously satisfies:

1. orthogonality with the structural error; and

2. a restriction on the first-stage error process.

The identified coplanar instrument is then supplied to
ivreg2 for standard IV/2SLS estimation.

Method

Suppose the structural model is

y = beta*x + u

and the first-stage equation is

x = gamma*z + e

where x is endogenous because cov(x,u) != 0.

The CIV method constructs a coplanar instrument of the form

s = x - k*d0*r

where r is constructed as the component of the dependent variable
orthogonal to x. In practice, r is obtained from the projection
of y onto the orthogonal complement of x.

The nuisance parameter d0 is selected using one of two DT criteria:

Homoskedastic DT criterion (hete(0)):
The algorithm searches for the value of d0 that minimizes the
dependence between the coplanar instrument and the squared
first-stage residuals.

Robust DT criterion (hete(1) and hete(2)):
The algorithm compares the distribution of OLS and feasible GLS
first-stage residuals to identify the value of d0 that minimizes
the difference in heteroskedasticity implied by misspecified
coplanar instruments.

hete(1) uses the parametric implementation proposed in the paper.

hete(2) uses the nonparametric implementation based on empirical
distribution functions and the Anderson-Darling statistic.

The implementation follows the bootstrap-based estimation strategy
proposed in Dzhumashev and Tursunalieva (2025).

The resulting coplanar instrument is treated as a generated
instrument and passed to ivreg2 for final estimation.

When option fe or twfe is specified, the fixed-effects
transformation is applied before the CIV construction stage.

For fe, variables are transformed using the standard within
(time-demeaning) transformation at the individual level.

For twfe, variables are transformed using the Halperin alternating
projection method (APM), which iteratively removes individual and time
effects until convergence.

After the transformed variables are obtained, the coplanar
instrument construction procedure and final IV/2SLS estimation are
applied to the transformed data.

Options

SIV construction

hete(#) specifies the criterion used to identify the optimal
coplanar instrument.

hete(0) baseline DT criterion for approximately
homoskedastic errors.

hete(1) robust DT criterion based on comparison between
OLS and feasible GLS residual distributions using parametric
approximations.

hete(2) nonparametric robust DT criterion using empirical
distribution functions and the Anderson-Darling statistic.

d(#) specifies the initial value of the nuisance parameter
d0.

delt(#) specifies the increment used in the grid search over
d0.

dmax(#) specifies the upper bound of the search region for
d0.

reps(#) specifies the number of bootstrap replications used to
obtain the optimal d0.

cgraph displays covariance and correlation graphs of squared first-stage residuals and the CIV under both assumed directions of endogeneity,
cov(u,x)>0 and cov(u,x)<0, for each endogenous variable being evaluated.

savegraph saves the covariance and correlation graphs generated under each assumed direction of endogeneity. By default, graphs are saved as [direction]_e2_[varname].gph,
where direction is pos or neg and varname is the name of the endogenous variable.

gprefix(name) specifies a prefix to be added to the default graph filename when savegraph is specified. For example, gprefix(myproj_) produces graph filenames such as myproj_pos_e2_x.gph and myproj_neg_e2_x.gph.

rcode requests random number generation through R programming
language using rcall.

FE options

fe requests the one-way fixed-effects estimator for panel data.
Before constructing the coplanar instrument, all variables are
transformed using the within transformation (time-demeaning at the
individual level).

twfe requests the two-way fixed-effects estimator for panel data.
Before constructing the coplanar instrument, all variables are
transformed using the Halperin alternating projection method (APM) to
remove both individual and time fixed effects iteratively.

maxiter(#) specifies the maximum number of iterations used in the
Halperin APM algorithm when option twfe is specified.

tolerance(#) specifies the convergence tolerance for the maximum
absolute difference between successive APM iterations when option
twfe is specified.

nolog suppresses the iteration log displayed by the Halperin APM
algorithm when option twfe is specified.

Important notes

As of the current release of civreg, the underlying CIV methodology has not yet undergone formal peer review in a scholarly journal.
Users are encouraged to carefully evaluate its suitability and robustness for their specific research applications.
The methodology remains an active area of research and may be subject to further revision and development.

civreg does not currently support factor-variable notation or
time-series operators directly inside the command syntax.
Users should generate transformed variables manually before estimation.

. generate Lx = L.x

. tabulate group, generate(g_)

Options fe and twfe require panel data declared by
xtset. Both panel and time identifiers must be specified before
estimation.

. xtset panelvar timevar

predict , residuals after civreg. Under fe or twfe,
the predicted residuals are composite residuals (a_i [+ v_t] + u_it),
not structural residuals (u_it). Structural residuals can be obtained by assuming E(a_i)=0 and E(v_t)=0
and performing calculations on group means. See Examples below for details.

The R programming language and rcall package must be installed
when option rcode is specified. To install rcall, type:

. //haghish.github.io/github/")"'

. `"github install haghish/rcall, stable"'

Saved results

civreg stores all standard estimation results returned by
ivreg2 in e().

In addition, the following are stored:

e(fe_opt) fixed-effects specification: 0 = none, 1 = one-way FE, 2 = two-way FE

e(rc) return code

e(hete) heteroskedasticity criterion selected by hete(#)

e(reps) number of bootstrap replications used

e(rcode) whether results are reproduced exactly in R

e(chk_sign) store information about the signs of cov(x,u)

e(cor_x_iv) correlation matrix corr(x,civ)

e(d0) matrix of parameter d0 (mean across bootstrap replications)

Examples

Load mroz dataset:

. webuse mroz, clear

Model with one endogenous variable:

. civreg hours (lwage = ) educ age kidslt6 kidsge6 nwifeinc, hete(0) reps(5)

Model with two endogenous variables:

. civreg hours (lwage educ = ) age kidslt6 kidsge6 nwifeinc, hete(1) reps(5)

Reproducing the SIV column results of Table 2 in Dzhumashev and Tursunalieva (2025):

. civreg hours (lwage = ) educ age kidslt6 kidsge6 nwifeinc , hete(0) reps(49) small rcode

Load Arellano and Bond (1991) dataset:

. webuse abdata, clear

Fixed-effects CIV estimation:

. civreg n (k = ) w ys, fe

Predict a_i:

. predict double au , resid

. egen double a_i = mean(au) , by(id)

Two-way fixed-effects CIV estimation:

. civreg n (k w = ) ys if year > 1977 & year < 1983 , twfe

Predict a_i and v_t in balanced panel data case:

. predict double avu if e(sample) , resid

. qui sum avu if e(sample), mean

. scalar avu_m = r(mean)

. egen double a_i = mean(avu - `=avu_m') if e(sample), by(id)

. egen double v_t = mean(avu - `=avu_m') if e(sample), by(year)

Acknowledgements

The author is grateful to Ratbek Dzhumashev, corresponding author of the Coplanar (Synthetic) Instrumental Variable (CIV) methodology,
for his generous assistance and valuable clarifications regarding the coplanar-instrument search algorithm.
The author also thanks Stata users for their helpful comments, suggestions, and feedback, which have contributed to the development and improvement of civreg.

References

Baum, C.F., Schaffer, M.E., Stillman, S. 2010.
ivreg2: Stata module for extended instrumental variables/2SLS, GMM and AC/HAC, LIML and k-class regression.
http://ideas.repec.org/c/boc/bocode/s425401.html

Dzhumashev, R., Tursunalieva, A. 2025. A synthetic instrumental variable method: Using the dual tendency condition for coplanar instruments.
arXiv preprint arXiv:2512.17301. https://doi.org/10.48550/arXiv.2512.17301.

Haghish, E.F. 2021. Integrating R machine learning algorithms in Stata using rcall. UK Stata Conference 2021, StataCorp.
https://www.stata.com/meeting/uk21/slides/UK21_Haghish.pdf

Author

Package implementation by Manh Hoang-Ba (hbmanh9492@gmail.com).