Estimation Methods

class IV2SLS(dependent, exog, endog, instruments, *, weights=None)[source]

Estimation of IV models using two-stage least squares

Parameters
  • dependent (array-like) – Endogenous variables (nobs by 1)

  • exog (array-like) – Exogenous regressors (nobs by nexog)

  • endog (array-like) – Endogenous regressors (nobs by nendog)

  • instruments (array-like) – Instrumental variables (nobs by ninstr)

  • weights (array-like, optional) – Observation weights used in estimation

Notes

The 2SLS estimator is defined

\[\begin{split}\hat{\beta}_{2SLS} & =(X'Z(Z'Z)^{-1}Z'X)^{-1}X'Z(Z'Z)^{-1}Z'Y\\ & =(\hat{X}'\hat{X})^{-1}\hat{X}'Y\\ \hat{X} & =Z(Z'Z)^{-1}Z'X\end{split}\]

The 2SLS estimator is a special case of a k-class estimator with \(\kappa=1\),

Todo

  • VCV: bootstrap

See also

IVLIML, IVGMM, IVGMMCUE

static estimate_parameters(x, y, z, kappa)

Parameter estimation without error checking

Parameters
  • x (ndarray) – Regressor matrix (nobs by nvar)

  • y (ndarray) – Regressand matrix (nobs by 1)

  • z (ndarray) – Instrument matrix (nobs by ninstr)

  • kappa (scalar) – Parameter value for k-class estimator

Returns

params – Estimated parameters (nvar by 1)

Return type

ndarray

Notes

Exposed as a static method to facilitate estimation with other data, e.g., bootstrapped samples. Performs no error checking.

fit(*, cov_type='robust', debiased=False, **cov_config)

Estimate model parameters

Parameters
  • cov_type (str, optional) –

    Name of covariance estimator to use. Supported covariance estimators are:

    • ’unadjusted’, ‘homoskedastic’ - Classic homoskedastic inference

    • ’robust’, ‘heteroskedastic’ - Heteroskedasticity robust inference

    • ’kernel’ - Heteroskedasticity and autocorrelation robust inference

    • ’cluster’ - One-way cluster dependent inference. Heteroskedasticity robust

  • debiased (bool, optional) – Flag indicating whether to debiased the covariance estimator using a degree of freedom adjustment.

  • **cov_config – Additional parameters to pass to covariance estimator. The list of optional parameters differ according to cov_type. See the documentation of the alternative covariance estimators for the complete list of available commands.

Returns

results – Results container

Return type

IVResults

Notes

Additional covariance parameters depend on specific covariance used. The see the docstring of specific covariance estimator for a list of supported options. Defaults are used if no covariance configuration is provided.

property formula

Formula used to create the model

Return type

str

static from_formula(formula, data, *, weights=None)[source]
Parameters
  • formula (str) – Patsy formula modified for the IV syntax described in the notes section

  • data (DataFrame) – DataFrame containing the variables used in the formula

  • weights (array-like, optional) – Observation weights used in estimation

Returns

model – Model instance

Return type

IV2SLS

Notes

The IV formula modifies the standard Patsy formula to include a block of the form [endog ~ instruments] which is used to indicate the list of endogenous variables and instruments. The general structure is dependent ~ exog [endog ~ instruments] and it must be the case that the formula expressions constructed from blocks dependent ~ exog endog and dependent ~ exog instruments are both valid Patsy formulas.

A constant must be explicitly included using ‘1 +’ if required.

Examples

>>> import numpy as np
>>> from linearmodels.datasets import wage
>>> from linearmodels.iv import IV2SLS
>>> data = wage.load()
>>> formula = 'np.log(wage) ~ 1 + exper + exper ** 2 + brthord + [educ ~ sibs]'
>>> mod = IV2SLS.from_formula(formula, data)
property has_constant

Flag indicating the model includes a constant or equivalent

property isnull

Locations of observations with missing values

property notnull

Locations of observations included in estimation

predict(params, *, exog=None, endog=None, data=None, eval_env=4)

Predict values for additional data

Parameters
  • params (array-like) – Model parameters (nvar by 1)

  • exog (array-like) – Exogenous regressors (nobs by nexog)

  • endog (array-like) – Endogenous regressors (nobs by nendog)

  • data (DataFrame) – Values to use when making predictions from a model constructed from a formula

  • eval_env (int) – Depth of use when evaluating formulas using Patsy.

Returns

predictions – Fitted values from supplied data and parameters

Return type

DataFrame

Notes

The number of parameters must satisfy nvar = nexog + nendog.

When using exog and endog, regressor matrix is constructed as [exog, endog] and so parameters must be aligned to this structure. The the the same structure used in model estimation.

If data is not none, then exog and endog must be none. Predictions from models constructed using formulas can be computed using either exog and endog, which will treat these are arrays of values corresponding to the formula-processed data, or using data which will be processed using the formula used to construct the values corresponding to the original model specification.

resids(params)

Compute model residuals

Parameters

params (ndarray) – Model parameters (nvar by 1)

Returns

resids – Model residuals

Return type

ndarray

wresids(params)

Compute weighted model residuals

Parameters

params (ndarray) – Model parameters (nvar by 1)

Returns

wresids – Weighted model residuals

Return type

ndarray

Notes

Uses weighted versions of data instead of raw data. Identical to resids if all weights are unity.

class IVLIML(dependent, exog, endog, instruments, *, weights=None, fuller=0, kappa=None)[source]

Limited information ML and k-class estimation of IV models

Parameters
  • dependent (array-like) – Endogenous variables (nobs by 1)

  • exog (array-like) – Exogenous regressors (nobs by nexog)

  • endog (array-like) – Endogenous regressors (nobs by nendog)

  • instruments (array-like) – Instrumental variables (nobs by ninstr)

  • weights (array-like, optional) – Observation weights used in estimation

  • fuller (float, optional) – Fuller’s alpha to modify LIML estimator. Default returns unmodified LIML estimator.

  • kappa (float, optional) – Parameter value for k-class estimation. If not provided, computed to produce LIML parameter estimate.

Notes

kappa and fuller should not be used simultaneously since Fuller’s alpha applies an adjustment to kappa, and so the same result can be computed using only kappa. Fuller’s alpha is used to adjust the LIML estimate of \(\kappa\), which is computed whenever kappa is not provided.

The LIML estimator is defined as

\[\begin{split}\hat{\beta}_{\kappa} & =(X(I-\kappa M_{z})X)^{-1}X(I-\kappa M_{z})Y\\ M_{z} & =I-P_{z}\\ P_{z} & =Z(Z'Z)^{-1}Z'\end{split}\]

where \(Z\) contains both the exogenous regressors and the instruments. \(\kappa\) is estimated as part of the LIML estimator.

When using Fuller’s \(\alpha\), the value used is modified to

\[\kappa-\alpha/(n-n_{instr})\]

Todo

  • VCV: bootstrap

See also

IV2SLS, IVGMM, IVGMMCUE

static estimate_parameters(x, y, z, kappa)[source]

Parameter estimation without error checking

Parameters
  • x (ndarray) – Regressor matrix (nobs by nvar)

  • y (ndarray) – Regressand matrix (nobs by 1)

  • z (ndarray) – Instrument matrix (nobs by ninstr)

  • kappa (scalar) – Parameter value for k-class estimator

Returns

params – Estimated parameters (nvar by 1)

Return type

ndarray

Notes

Exposed as a static method to facilitate estimation with other data, e.g., bootstrapped samples. Performs no error checking.

fit(*, cov_type='robust', debiased=False, **cov_config)[source]

Estimate model parameters

Parameters
  • cov_type (str, optional) –

    Name of covariance estimator to use. Supported covariance estimators are:

    • ’unadjusted’, ‘homoskedastic’ - Classic homoskedastic inference

    • ’robust’, ‘heteroskedastic’ - Heteroskedasticity robust inference

    • ’kernel’ - Heteroskedasticity and autocorrelation robust inference

    • ’cluster’ - One-way cluster dependent inference. Heteroskedasticity robust

  • debiased (bool, optional) – Flag indicating whether to debiased the covariance estimator using a degree of freedom adjustment.

  • **cov_config – Additional parameters to pass to covariance estimator. The list of optional parameters differ according to cov_type. See the documentation of the alternative covariance estimators for the complete list of available commands.

Returns

results – Results container

Return type

IVResults

Notes

Additional covariance parameters depend on specific covariance used. The see the docstring of specific covariance estimator for a list of supported options. Defaults are used if no covariance configuration is provided.

property formula

Formula used to create the model

Return type

str

static from_formula(formula, data, *, weights=None, fuller=0, kappa=None)[source]
Parameters
  • formula (str) – Patsy formula modified for the IV syntax described in the notes section

  • data (DataFrame) – DataFrame containing the variables used in the formula

  • weights (array-like, optional) – Observation weights used in estimation

  • fuller (float, optional) – Fuller’s alpha to modify LIML estimator. Default returns unmodified LIML estimator.

  • kappa (float, optional) – Parameter value for k-class estimation. If not provided, computed to produce LIML parameter estimate.

Returns

model – Model instance

Return type

IVLIML

Notes

The IV formula modifies the standard Patsy formula to include a block of the form [endog ~ instruments] which is used to indicate the list of endogenous variables and instruments. The general structure is dependent ~ exog [endog ~ instruments] and it must be the case that the formula expressions constructed from blocks dependent ~ exog endog and dependent ~ exog instruments are both valid Patsy formulas.

A constant must be explicitly included using ‘1 +’ if required.

Examples

>>> import numpy as np
>>> from linearmodels.datasets import wage
>>> from linearmodels.iv import IVLIML
>>> data = wage.load()
>>> formula = 'np.log(wage) ~ 1 + exper + exper ** 2 + brthord + [educ ~ sibs]'
>>> mod = IVLIML.from_formula(formula, data)
property has_constant

Flag indicating the model includes a constant or equivalent

property isnull

Locations of observations with missing values

property notnull

Locations of observations included in estimation

predict(params, *, exog=None, endog=None, data=None, eval_env=4)[source]

Predict values for additional data

Parameters
  • params (array-like) – Model parameters (nvar by 1)

  • exog (array-like) – Exogenous regressors (nobs by nexog)

  • endog (array-like) – Endogenous regressors (nobs by nendog)

  • data (DataFrame) – Values to use when making predictions from a model constructed from a formula

  • eval_env (int) – Depth of use when evaluating formulas using Patsy.

Returns

predictions – Fitted values from supplied data and parameters

Return type

DataFrame

Notes

The number of parameters must satisfy nvar = nexog + nendog.

When using exog and endog, regressor matrix is constructed as [exog, endog] and so parameters must be aligned to this structure. The the the same structure used in model estimation.

If data is not none, then exog and endog must be none. Predictions from models constructed using formulas can be computed using either exog and endog, which will treat these are arrays of values corresponding to the formula-processed data, or using data which will be processed using the formula used to construct the values corresponding to the original model specification.

resids(params)[source]

Compute model residuals

Parameters

params (ndarray) – Model parameters (nvar by 1)

Returns

resids – Model residuals

Return type

ndarray

wresids(params)[source]

Compute weighted model residuals

Parameters

params (ndarray) – Model parameters (nvar by 1)

Returns

wresids – Weighted model residuals

Return type

ndarray

Notes

Uses weighted versions of data instead of raw data. Identical to resids if all weights are unity.

class IVGMM(dependent, exog, endog, instruments, *, weights=None, weight_type='robust', **weight_config)[source]

Estimation of IV models using the generalized method of moments (GMM)

Parameters
  • dependent (array-like) – Endogenous variables (nobs by 1)

  • exog (array-like) – Exogenous regressors (nobs by nexog)

  • endog (array-like) – Endogenous regressors (nobs by nendog)

  • instruments (array-like) – Instrumental variables (nobs by ninstr)

  • weights (array-like, optional) – Observation weights used in estimation

  • weight_type (str) – Name of moment condition weight function to use in the GMM estimation

  • **weight_config – Additional keyword arguments to pass to the moment condition weight function

Notes

Available GMM weight functions are:

  • ‘unadjusted’, ‘homoskedastic’ - Assumes moment conditions are homoskedastic

  • ‘robust’, ‘heteroskedastic’ - Allows for heteroskedasticity by not autocorrelation

  • ‘kernel’ - Allows for heteroskedasticity and autocorrelation

  • ‘cluster’ - Allows for one-way cluster dependence

The estimator is defined as

\[\hat{\beta}_{gmm}=(X'ZW^{-1}Z'X)^{-1}X'ZW^{-1}Z'Y\]

where \(W\) is a positive definite weight matrix and \(Z\) contains both the exogenous regressors and the instruments.

Todo

  • VCV: bootstrap

See also

IV2SLS, IVLIML, IVGMMCUE

static estimate_parameters(x, y, z, w)[source]
Parameters
  • x (ndarray) – Regressor matrix (nobs by nvar)

  • y (ndarray) – Regressand matrix (nobs by 1)

  • z (ndarray) – Instrument matrix (nobs by ninstr)

  • w (ndarray) – GMM weight matrix (ninstr by ninstr)

Returns

params – Estimated parameters (nvar by 1)

Return type

ndarray

Notes

Exposed as a static method to facilitate estimation with other data, e.g., bootstrapped samples. Performs no error checking.

fit(*, iter_limit=2, tol=0.0001, initial_weight=None, cov_type='robust', debiased=False, **cov_config)[source]

Estimate model parameters

Parameters
  • iter_limit (int, optional) – Maximum number of iterations. Default is 2, which produces two-step efficient GMM estimates. Larger values can be used to iterate between parameter estimation and optimal weight matrix estimation until convergence.

  • tol (float, optional) – Convergence criteria. Measured as covariance normalized change in parameters across iterations where the covariance estimator is based on the first step parameter estimates.

  • initial_weight (ndarray, optional) – Initial weighting matrix to use in the first step. If not specified, uses the average outer-product of the set containing the exogenous variables and instruments.

  • cov_type (str, optional) –

    Name of covariance estimator to use. Available covariance functions are:

    • ’unadjusted’, ‘homoskedastic’ - Assumes moment conditions are homoskedastic

    • ’robust’, ‘heteroskedastic’ - Allows for heteroskedasticity but not autocorrelation

    • ’kernel’ - Allows for heteroskedasticity and autocorrelation

    • ’cluster’ - Allows for one-way cluster dependence

  • debiased (bool, optional) – Flag indicating whether to debiased the covariance estimator using a degree of freedom adjustment.

  • **cov_config – Additional parameters to pass to covariance estimator. Supported parameters depend on specific covariance structure assumed. See linearmodels.iv.gmm.IVGMMCovariance for details on the available options. Defaults are used if no covariance configuration is provided.

Returns

results – Results container

Return type

IVGMMResults

property formula

Formula used to create the model

Return type

str

static from_formula(formula, data, *, weights=None, weight_type='robust', **weight_config)[source]
Parameters
  • formula (str) – Patsy formula modified for the IV syntax described in the notes section

  • data (DataFrame) – DataFrame containing the variables used in the formula

  • weights (array-like, optional) – Observation weights used in estimation

  • weight_type (str) – Name of moment condition weight function to use in the GMM estimation

  • **weight_config – Additional keyword arguments to pass to the moment condition weight function

Notes

The IV formula modifies the standard Patsy formula to include a block of the form [endog ~ instruments] which is used to indicate the list of endogenous variables and instruments. The general structure is dependent ~ exog [endog ~ instruments] and it must be the case that the formula expressions constructed from blocks dependent ~ exog endog and dependent ~ exog instruments are both valid Patsy formulas.

A constant must be explicitly included using ‘1 +’ if required.

Returns

model – Model instance

Return type

IVGMM

Examples

>>> import numpy as np
>>> from linearmodels.datasets import wage
>>> from linearmodels.iv import IVGMM
>>> data = wage.load()
>>> formula = 'np.log(wage) ~ 1 + exper + exper ** 2 + brthord + [educ ~ sibs]'
>>> mod = IVGMM.from_formula(formula, data)
property has_constant

Flag indicating the model includes a constant or equivalent

property isnull

Locations of observations with missing values

property notnull

Locations of observations included in estimation

predict(params, *, exog=None, endog=None, data=None, eval_env=4)

Predict values for additional data

Parameters
  • params (array-like) – Model parameters (nvar by 1)

  • exog (array-like) – Exogenous regressors (nobs by nexog)

  • endog (array-like) – Endogenous regressors (nobs by nendog)

  • data (DataFrame) – Values to use when making predictions from a model constructed from a formula

  • eval_env (int) – Depth of use when evaluating formulas using Patsy.

Returns

predictions – Fitted values from supplied data and parameters

Return type

DataFrame

Notes

The number of parameters must satisfy nvar = nexog + nendog.

When using exog and endog, regressor matrix is constructed as [exog, endog] and so parameters must be aligned to this structure. The the the same structure used in model estimation.

If data is not none, then exog and endog must be none. Predictions from models constructed using formulas can be computed using either exog and endog, which will treat these are arrays of values corresponding to the formula-processed data, or using data which will be processed using the formula used to construct the values corresponding to the original model specification.

resids(params)

Compute model residuals

Parameters

params (ndarray) – Model parameters (nvar by 1)

Returns

resids – Model residuals

Return type

ndarray

wresids(params)

Compute weighted model residuals

Parameters

params (ndarray) – Model parameters (nvar by 1)

Returns

wresids – Weighted model residuals

Return type

ndarray

Notes

Uses weighted versions of data instead of raw data. Identical to resids if all weights are unity.

class IVGMMCUE(dependent, exog, endog, instruments, *, weights=None, weight_type='robust', **weight_config)[source]

Estimation of IV models using continuously updating GMM

Parameters
  • dependent (array-like) – Endogenous variables (nobs by 1)

  • exog (array-like) – Exogenous regressors (nobs by nexog)

  • endog (array-like) – Endogenous regressors (nobs by nendog)

  • instruments (array-like) – Instrumental variables (nobs by ninstr)

  • weights (array-like, optional) – Observation weights used in estimation

  • weight_type (str) – Name of moment condition weight function to use in the GMM estimation

  • **weight_config – Additional keyword arguments to pass to the moment condition weight function

Notes

Available weight functions are:

  • ‘unadjusted’, ‘homoskedastic’ - Assumes moment conditions are homoskedastic

  • ‘robust’, ‘heteroskedastic’ - Allows for heteroskedasticity by not autocorrelation

  • ‘kernel’ - Allows for heteroskedasticity and autocorrelation

  • ‘cluster’ - Allows for one-way cluster dependence

In most circumstances, the center weight option should be True to avoid starting value dependence.

\[\begin{split}\hat{\beta}_{cue} & =\min_{\beta}\bar{g}(\beta)'W(\beta)^{-1}g(\beta)\\ g(\beta) & =n^{-1}\sum_{i=1}^{n}z_{i}(y_{i}-x_{i}\beta)\end{split}\]

where \(W(\beta)\) is a weight matrix that depends on \(\beta\) through \(\epsilon_i = y_i - x_i\beta\).

See also

IV2SLS, IVLIML, IVGMM

estimate_parameters(starting, x, y, z, display=False, opt_options=None)[source]
Parameters
  • starting (ndarray) – Starting values for the optimization

  • x (ndarray) – Regressor matrix (nobs by nvar)

  • y (ndarray) – Regressand matrix (nobs by 1)

  • z (ndarray) – Instrument matrix (nobs by ninstr)

  • display (bool) – Flag indicating whether to display iterative optimizer output

  • opt_options (dict, optional) – Dictionary containing additional keyword arguments to pass to scipy.optimize.minimize.

Returns

params – Estimated parameters (nvar by 1)

Return type

ndarray

Notes

Exposed to facilitate estimation with other data, e.g., bootstrapped samples. Performs no error checking.

See also

scipy.optimize.minimize()

fit(*, starting=None, display=False, cov_type='robust', debiased=False, opt_options=None, **cov_config)[source]

Estimate model parameters

Parameters
  • starting (ndarray, optional) – Starting values to use in optimization. If not provided, 2SLS estimates are used.

  • display (bool, optional) – Flag indicating whether to display optimization output

  • cov_type (str, optional) – Name of covariance estimator to use

  • debiased (bool, optional) – Flag indicating whether to debiased the covariance estimator using a degree of freedom adjustment.

  • opt_options (dict, optional) – Additional options to pass to scipy.optimize.minimize when optimizing the objective function. If not provided, defers to scipy to choose an appropriate optimizer.

  • **cov_config – Additional parameters to pass to covariance estimator. Supported parameters depend on specific covariance structure assumed. See linearmodels.iv.gmm.IVGMMCovariance for details on the available options. Defaults are used if no covariance configuration is provided.

Returns

results – Results container

Return type

IVGMMResults

Notes

Starting values are computed by IVGMM.

property formula

Formula used to create the model

Return type

str

static from_formula(formula, data, *, weights=None, weight_type='robust', **weight_config)[source]
Parameters
  • formula (str) – Patsy formula modified for the IV syntax described in the notes section

  • data (DataFrame) – DataFrame containing the variables used in the formula

  • weights (array-like, optional) – Observation weights used in estimation

  • weight_type (str) – Name of moment condition weight function to use in the GMM estimation

  • **weight_config – Additional keyword arguments to pass to the moment condition weight function

Returns

model – Model instance

Return type

IVGMMCUE

Notes

The IV formula modifies the standard Patsy formula to include a block of the form [endog ~ instruments] which is used to indicate the list of endogenous variables and instruments. The general structure is dependent ~ exog [endog ~ instruments] and it must be the case that the formula expressions constructed from blocks dependent ~ exog endog and dependent ~ exog instruments are both valid Patsy formulas.

A constant must be explicitly included using ‘1 +’ if required.

Examples

>>> from linearmodels.datasets import wage
>>> from linearmodels.iv import IVGMMCUE
>>> data = wage.load()
>>> formula = 'np.log(wage) ~ 1 + exper + exper ** 2 + brthord + [educ ~ sibs]'
>>> mod = IVGMMCUE.from_formula(formula, data)
property has_constant

Flag indicating the model includes a constant or equivalent

property isnull

Locations of observations with missing values

j(params, x, y, z)[source]

Optimization target

Parameters
  • params (ndarray) – Parameter vector (nvar)

  • x (ndarray) – Regressor matrix (nobs by nvar)

  • y (ndarray) – Regressand matrix (nobs by 1)

  • z (ndarray) – Instrument matrix (nobs by ninstr)

Returns

j – GMM objective function, also known as the J statistic

Return type

float

Notes

The GMM objective function is defined as

\[J(\beta) = \bar{g}(\beta)'W(\beta)^{-1}\bar{g}(\beta)\]

where \(\bar{g}(\beta)\) is the average of the moment conditions, \(z_i \hat{\epsilon}_i\), where \(\hat{\epsilon}_i = y_i - x_i\beta\). The weighting matrix is some estimator of the long-run variance of the moment conditions.

Unlike tradition GMM, the weighting matrix is simultaneously computed with the moment conditions, and so has explicit dependence on \(\beta\).

property notnull

Locations of observations included in estimation

predict(params, *, exog=None, endog=None, data=None, eval_env=4)

Predict values for additional data

Parameters
  • params (array-like) – Model parameters (nvar by 1)

  • exog (array-like) – Exogenous regressors (nobs by nexog)

  • endog (array-like) – Endogenous regressors (nobs by nendog)

  • data (DataFrame) – Values to use when making predictions from a model constructed from a formula

  • eval_env (int) – Depth of use when evaluating formulas using Patsy.

Returns

predictions – Fitted values from supplied data and parameters

Return type

DataFrame

Notes

The number of parameters must satisfy nvar = nexog + nendog.

When using exog and endog, regressor matrix is constructed as [exog, endog] and so parameters must be aligned to this structure. The the the same structure used in model estimation.

If data is not none, then exog and endog must be none. Predictions from models constructed using formulas can be computed using either exog and endog, which will treat these are arrays of values corresponding to the formula-processed data, or using data which will be processed using the formula used to construct the values corresponding to the original model specification.

resids(params)

Compute model residuals

Parameters

params (ndarray) – Model parameters (nvar by 1)

Returns

resids – Model residuals

Return type

ndarray

wresids(params)

Compute weighted model residuals

Parameters

params (ndarray) – Model parameters (nvar by 1)

Returns

wresids – Weighted model residuals

Return type

ndarray

Notes

Uses weighted versions of data instead of raw data. Identical to resids if all weights are unity.