IV
IV estimates a linear model with endogenous regressors by two-stage least squares (2SLS) or generalized method of moments (GMM). Unlike OLS, independent variables are split into two lists — x_exog (exogenous) and x_endog (endogenous) — plus instruments (the excluded instruments, one per endogenous variable at minimum for identification). IVOptions.estimator ("2sls", the default, or "gmm") selects the estimator; a single IV/IVResults pair serves both.
Standard error types
IVOptions.cov_type supports "classical", "hc0" through "hc3", "hac" (with hac_lag/hac_time), and "cluster" (with cluster) — the same range as OLS. The number of HAC lags actually used (the explicit hac_lags, or the automatic value when omitted) is reported as IVResults.hac_lags_used; it is set when cov_type="hac" or, for estimator="gmm" with gmm_type "two_step"/"iterated", gmm_weight_type="hac", and None otherwise. stats (test statistics) and p_values use a t-test for estimator="2sls" and a z-test for estimator="gmm".
GMM weight type and iteration
For estimator="gmm", IVOptions.gmm_weight_type selects the weight matrix used for point estimation — "classical", "robust", "cluster", or "hac" (the same vocabulary as cov_type) — independently of cov_type (which only affects the final reported standard errors). gmm_weight_type="cluster"/"hac" read cluster/hac_lags/hac_time from the same fields cov_type uses (each is valid if either cov_type or gmm_weight_type uses it). IVOptions.gmm_type selects the GMM estimation type: "two_step" (default, efficient two-step GMM), "one_step" (weight matrix (Z'Z)⁻¹ only; gmm_weight_type is not used), or "iterated" (repeat until convergence). gmm_max_iter (maximum number of estimations counting the initial one, at least 3; effective default 100) and gmm_tol (convergence tolerance; effective default 1e-6) apply only to "iterated" (as does raise_on_non_convergence) and raise ValidationError when given with the other types; IVResults.converged/n_iter report the outcome (converged is always True for "one_step"/"two_step"). Specifying any GMM-only field (gmm_type, gmm_weight_type, gmm_max_iter, gmm_tol, raise_on_non_convergence) with estimator="2sls" also raises ValidationError, as does gmm_weight_type with gmm_type="one_step"; their defaults are None, meaning the effective defaults above. The estimator, GMM type and weight matrix actually used are echoed back on the result as IVResults.estimator, IVResults.gmm_type and IVResults.gmm_weight_type (normalized to lowercase); gmm_type is None for estimator="2sls", and gmm_weight_type is None for estimator="2sls" and for gmm_type="one_step", which have no such concept.
Diagnostics
IVResults exposes three diagnostics in addition to the coefficient table:
weak_instrument_f_statistics: partial F-statistic per endogenous variable, testing the excluded instruments' joint significance after partialling outx_exog(always under the classical formula, regardless ofcov_type).overid_statistic/overid_p_value: the overidentification test — Sargan (estimator="2sls") or Hansen J (estimator="gmm").Nonewhen just-identified (len(instruments) == len(x_endog)).wu_hausman_statistic/wu_hausman_p_value: regression-based endogeneity test (adds first-stage residuals to the structural equation). Only available forestimator="2sls"; alwaysNoneforestimator="gmm".
First-stage results
IVResults.first_stage() returns a dict[str, OLSResults] keyed by endogenous variable name, one plain-OLS regression of x_endog[i] on x_exog + instruments per endogenous variable. Its f_statistic includes x_exog's contribution and is not the same as weak_instrument_f_statistics.
econometricsmodels.IV(data, y, x_exog, x_endog, instruments, options=None)
Instrumental variables estimator (2SLS/GMM).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
data
|
DataFrame
|
A polars DataFrame containing the dependent variable, exogenous/endogenous independent variables, and instrument columns. |
required |
y
|
str
|
Column name of the dependent variable. |
required |
x_exog
|
list[str]
|
List of column names of the exogenous independent variables. |
required |
x_endog
|
list[str]
|
List of column names of the endogenous independent variables. |
required |
instruments
|
list[str]
|
List of column names of the excluded instruments
(must not overlap |
required |
options
|
IVOptions | None
|
Estimation options. Defaults to |
None
|
Examples:
>>> import polars as pl
>>> from econometricsmodels import IV
>>> df = pl.DataFrame(
... {
... "y": [1.0, 2.0, 3.0, 4.0],
... "endog1": [2.0, 1.0, 4.0, 3.0],
... "z1": [1.0, 3.0, 2.0, 4.0],
... }
... )
>>> result = IV(
... df, y="y", x_exog=[], x_endog=["endog1"], instruments=["z1"]
... ).fit()
>>> result.params["endog1"]
fit()
Estimate the IV model.
Returns:
| Type | Description |
|---|---|
IVResults
|
The estimation results. |
Raises:
| Type | Description |
|---|---|
TypeError
|
An argument has the wrong type (for example
|
ValidationError
|
The input or options are invalid (a
column is missing, contains missing values or
NaN/infinity, |
ComputationError
|
A problem was detected during
computation (e.g. a singular first- or second-stage
design matrix). A subclass of |
econometricsmodels.IVOptions
Estimation options for IV (2SLS/GMM).
See docs/spec/iv-spec.md for the rationale behind each field's
meaning and default value. A single IVOptions/fit_iv pair serves both
estimation methods; fields that apply to only one estimator are documented as such.
cluster
property
Column name to use as the cluster group key. Used by cov_type="cluster" and,
with estimator="gmm", by gmm_weight_type="cluster" (also when
cov_type is not "cluster"). Specifying it when neither uses it raises
ValidationError.
confidence_level
property
Confidence level for confidence intervals, in the range (0, 1). Defaults to 0.95 (a 95% confidence interval).
cov_type
property
Standard error type: one of "classical", "hc0" through "hc3", "hac", "cluster".
Case-insensitive. For estimator="gmm", this is independent of gmm_weight_type
(the weight matrix used for point estimation, see gmm_weight_type below).
estimator
property
Estimation estimator: "2sls" (default) or "gmm". Case-insensitive.
gmm_max_iter
property
Maximum number of GMM estimations for gmm_type="iterated", counting the initial
estimate; an integer from 3 to 10,000 (use gmm_type="two_step" for two steps).
None (default) means 100. Specifying it with any other gmm_type or with
estimator="2sls" raises ValidationError.
gmm_tol
property
Convergence tolerance for gmm_type="iterated": iteration stops once every
coefficient changes by less than this (relative/absolute mix). None (default)
means 1e-6. Specifying it with any other gmm_type or with estimator="2sls"
raises ValidationError.
gmm_type
property
GMM estimation type: "one_step" (weight matrix (Z'Z)^-1 only), "two_step"
(efficient two-step GMM), or "iterated" (repeat until convergence).
Case-insensitive. None (default) means "two_step" for estimator="gmm".
Specifying it with estimator="2sls" raises ValidationError.
gmm_weight_type
property
Weight matrix used for GMM point estimation: one of "classical" (homoskedastic),
"robust" (heteroskedasticity-robust), "cluster", "hac" (Newey-West). Same vocabulary
as cov_type. Case-insensitive. None (default) means "classical" for
gmm_type="two_step"/"iterated". Specifying it with estimator="2sls" or
gmm_type="one_step" (which does not use a weight matrix) raises ValidationError.
"cluster"/"hac" draw from the same cluster/hac_lags/hac_time fields as
cov_type (no separate fields; see module docstring "GMMのgmm_weight_type").
hac_lags
property
Number of lags (bandwidth) for HAC (Newey-West), used by cov_type="hac" and, with
estimator="gmm", by gmm_weight_type="hac". When None, computed automatically.
Specifying it when neither uses it raises ValidationError.
hac_time
property
Column name giving the time order for HAC, used by cov_type="hac" and, with
estimator="gmm", by gmm_weight_type="hac". Required when either is "hac"
(omitting it raises ValidationError): the row order of the data is never assumed
to be the time order. Specifying it when neither uses it raises ValidationError.
include_intercept
property
Whether the engine should automatically add an intercept column to x_exog.
x_endog/instruments never get an automatic intercept column.
raise_on_non_convergence
property
Whether to raise an error if gmm_type="iterated" does not converge within
gmm_max_iter. If False, returns the result with converged=False instead of
raising. None (default) means True. Specifying it with any other gmm_type
(which never checks convergence) or with estimator="2sls" raises
ValidationError.
econometricsmodels.IVResults(raw)
IV estimation results.
Array-valued properties (params, std_errors, etc.) are exposed
as dictionaries keyed by coefficient name (for O(1) lookup of a
single parameter). Use coef_table() for a row-oriented listing.
first_stage() (per-endogenous-variable first-stage regression
results) is provided as a separate method rather than a field on
this class (docs/spec/iv-spec.md section 2).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
raw
|
IVResult
|
The estimation result object returned by |
required |
Note
Users normally do not construct this directly; it is returned
by IV.fit().
adj_r_squared
property
Degrees-of-freedom-adjusted R².
conf_int
property
Coefficient name to confidence interval (lower, upper).
converged
property
Whether GMM iteration converged (estimator="gmm" only).
Only meaningful for gmm_type="iterated"; always True for
"one_step"/"two_step" (which never check convergence) and
for estimator="2sls" (2SLS is a closed-form, non-iterative
estimator).
cov_type
property
Standard error type actually used (normalized to lowercase).
dep_var_name
property
Column name of the dependent variable.
df_model
property
Model degrees of freedom (k minus 1 if
include_intercept=True).
df_resid
property
Residual degrees of freedom (n - k).
estimator
property
Estimator actually used (normalized to lowercase):
"2sls" or "gmm".
gmm_type
property
GMM estimation type actually used (normalized to
lowercase): "one_step", "two_step" or "iterated". Always
None for estimator="2sls".
gmm_weight_type
property
Weight matrix actually used for GMM point estimation
(normalized to lowercase). Only meaningful for estimator="gmm";
always None for estimator="2sls", which has no such concept,
and for gmm_type="one_step", which does not use a weight
type.
hac_lags_used
property
Number of HAC (Newey-West) lags actually used: the explicit
hac_lags if given, otherwise the value chosen automatically,
floor(4 * (n / 100) ** (2 / 9)). Set when cov_type="hac" or,
for estimator="gmm" with gmm_type "two_step" or
"iterated", gmm_weight_type="hac" (both share hac_lags, so
the value is the same); None otherwise.
n_iter
property
Number of GMM estimations actually run, counting the initial
estimate (estimator="gmm" only): 1 for "one_step", 2 for
"two_step", at most gmm_max_iter for "iterated". Always
1 for estimator="2sls".
n_obs
property
Number of observations.
overid_df
property
Degrees of freedom of the chi-squared overidentification test
(len(instruments) - len(x_endog)). None under the same
conditions as overid_statistic.
overid_p_value
property
P-value of the overidentification test.
Same conditions as overid_statistic for when this is None.
overid_statistic
property
Overidentification test statistic: Sargan (estimator="2sls")
or Hansen J (estimator="gmm").
None when just-identified (len(instruments) ==
len(x_endog), degrees of freedom 0); see
docs/spec/iv-spec.md section 3.5.
p_values
property
Coefficient name to two-sided p-value.
param_names
property
List of coefficient names ("const" first when
include_intercept=True).
params
property
Coefficient name to coefficient value.
r_squared
property
Coefficient of determination (R²).
residuals
property
Structural residuals (in observation order, y - Xβ̂, using
the actual endogenous variables rather than their first-stage
fitted values).
stat_df
property
Degrees of freedom of the t distribution behind test_stats,
or None when stat_dist is "normal". May differ from
df_resid (e.g. cluster-robust inference uses G - 1), so use
this to recompute p-values from test_stats.
stat_dist
property
Distribution of test_stats: "t" for estimator="2sls",
"normal" for estimator="gmm".
std_errors
property
Coefficient name to standard error.
test_stats
property
Coefficient name to test statistic.
t-statistic for estimator="2sls", z-statistic for
estimator="gmm"; stat_dist tells which.
wald_df_denom
property
Denominator degrees of freedom of wald_statistic for "f"
(df_resid, or G - 1 with cluster-robust inference). None for
"chi2" and when the statistic is NaN.
wald_df_num
property
Numerator degrees of freedom of wald_statistic (the number of
slope coefficients; the only degrees of freedom for "chi2").
None when there are no slope coefficients.
wald_dist
property
Distribution of wald_statistic: "f" (F distribution) for
estimator="2sls", "chi2" (chi-squared) for estimator="gmm".
wald_p_value
property
P-value of wald_statistic (F or chi-squared, see
wald_dist).
wald_statistic
property
Wald test statistic for all slope coefficients being zero.
For estimator="2sls" this is the F-type statistic (the Wald
statistic divided by the number of slope coefficients; the
counterpart of OLSResults.f_statistic, a classical F-test when
cov_type="classical", a robust Wald test otherwise). For
estimator="gmm" it is the undivided Wald statistic, which
follows a chi-squared distribution. wald_dist tells which.
weak_instrument_f_df_denom
property
Denominator degrees of freedom of the weak-instrument F statistics (residual degrees of freedom of the first-stage regressions; the same for every endogenous variable).
weak_instrument_f_df_num
property
Numerator degrees of freedom of the weak-instrument F statistics (the number of excluded instruments; the same for every endogenous variable).
weak_instrument_f_statistics
property
Weak-instrument diagnostic: partial F-statistic for each endogenous variable, keyed by variable name.
Tests the excluded instruments' joint significance after
partialling out x_exog, always under the classical
(homoskedastic) formula regardless of cov_type. Not the
same as the plain F-statistic of the corresponding regression
in first_stage(), which includes x_exog's contribution
too. Computed the same way for both estimator="2sls" and
estimator="gmm"; see docs/spec/iv-spec.md section 3.4.
wu_hausman_df_denom
property
Denominator degrees of freedom of the Wu-Hausman F test.
None under the same conditions as wu_hausman_statistic.
wu_hausman_df_num
property
Numerator degrees of freedom of the Wu-Hausman F test (the
number of endogenous variables). None under the same conditions
as wu_hausman_statistic.
wu_hausman_p_value
property
P-value of the Wu-Hausman test.
None under the same conditions as wu_hausman_statistic.
wu_hausman_statistic
property
Wu-Hausman endogeneity test statistic (regression-based).
Adds the first-stage residuals to the structural equation and
tests their joint significance (linearmodels'
wooldridge_regression formulation), jointly over all
endogenous variables. Unlike
weak_instrument_f_statistics, this is always computed under
the same cov_type passed to fit().
None when the augmented regression cannot be estimated
(e.g. the first-stage residual has zero variance, such as
when an instrument perfectly predicts its endogenous
variable, or there are too few observations for the extra
residual columns) — this does not affect the validity of
the other results. Always None for estimator="gmm"
(not implemented for GMM). See
docs/spec/iv-spec.md section 3.6.
coef_table()
Row-oriented summary table of the coefficients.
Shaped to be usable almost as-is in a REST API response (same
policy as OLSResults.coef_table()). Returned as list[dict]
rather than a polars DataFrame, per the project's policy of
not using DataFrames for the coefficient table itself.
Returns:
| Type | Description |
|---|---|
list[dict[str, float | str]]
|
A list of dictionaries, one per coefficient. Keys are |
list[dict[str, float | str]]
|
|
list[dict[str, float | str]]
|
|
first_stage()
Per-endogenous-variable first-stage regression results.
Each first-stage regression is x_endog[i] ~ x_exog +
instruments, estimated by plain OLS (docs/spec/iv-spec.md
section 2). Returns the existing
OLSResults type rather than a new IV-specific type — the
first stage is a genuine, valid OLS regression in its own
right. Its f_statistic/f_p_value include x_exog's
contribution and are not the weak-instrument partial
F-statistic (weak_instrument_f_statistics).
Returns:
| Type | Description |
|---|---|
dict[str, OLSResults]
|
A dictionary keyed by endogenous variable name (matching |
dict[str, OLSResults]
|
|