linearmodels.iv.absorbing.AbsorbingLS.fit¶

AbsorbingLS.fit(*, cov_type: str = 'robust', debiased: bool = False, method: str = 'auto', absorb_options: dict[str, bool | float | str | ndarray | DataArray | DataFrame | Series | list[Any] | tuple[Any, ...] | dict[str, Any] | None] | None = None, use_cache: bool = True, lsmr_options: dict[str, float | bool] | None = None, **cov_config: Any) → AbsorbingLSResults[source]¶

Estimate model parameters.

Parameters:¶

cov_type: str = 'robust'¶

Name of covariance estimator to use. The default is “robust”. The names are not case sensitive. Supported covariance estimators are:

• ”unadjusted”, “homoskedastic”, “homo”, “homoskedasticcovariance” - Classic homoskedastic inference

• ”robust”, “heteroskedastic”, “hccm”, “heteroskedasticcovariance” - Heteroskedasticity robust inference

• ”kernel”, “kernelcovariance” - Heteroskedasticity and autocorrelation robust inference

• ”clustered”, “one-way”, “onewayclusteredcovariance” - Cluster dependent inference, which is heteroskedasticity robust. It is one-way unless clusters has two columns.

debiased: bool = False¶

Flag indicating whether to debias the covariance estimator using a degree of freedom adjustment. The default is False.

method: str = 'auto'¶

The algorithm that absorbs the variables. The names are not case sensitive, and a ValueError is raised for any other value. One of:

• ”auto” - (Default). Use HDFE when applicable and fallback to LSMR.

• ”lsmr” - Force LSMR.

• ”hdfe” - Force HDFE. Raises RuntimeError if the model contains continuous variables or continuous-binary interactions to absorb or if the model is weighted.

absorb_options: dict[str, bool | float | str | ndarray | DataArray | DataFrame | Series | list[Any] | tuple[Any, ...] | dict[str, Any] | None] | None = None¶

Dictionary of options to pass to the absorber. Passed to either scipy.sparse.linalg.lsmr or pyhdfe.create depending on the method used to absorb the absorbed regressors. The options have to be those of the algorithm that is used, which is HDFE if method is “auto” and the model can be absorbed using it. A ValueError is raised for options of LSMR if the variables are absorbed using HDFE, and for options of pyhdfe.create if they are absorbed using LSMR.

use_cache: bool = True¶

Flag indicating whether the variables, once purged from the absorbed variables and interactions, should be stored in the cache, and retrieved if available. Cache can dramatically speed up re-fitting large models when the set of absorbed variables and interactions are identical. The default is True.

lsmr_options: dict[str, float | bool] | None = None¶

Options to pass to scipy.sparse.linalg.lsmr. If they are not empty, method “auto” absorbs the variables using LSMR, and method “hdfe” raises a ValueError.

Deprecated since version 4.17: Use absorb_options with method=”lsmr” to pass options. lsmr_options will be removed in linearmodels 8.0.

**cov_config: Any¶

Additional parameters to pass to the covariance estimator. The keys that are used depend on cov_type. “unadjusted” and “robust” do not use any. “kernel” uses kernel (str), the name of the kernel, which is “bartlett” if it is not provided, and bandwidth (int), which is selected from the data if it is not provided. The names of the kernels are not case sensitive. “clustered” uses clusters (array_like), the cluster assignment of each observation, with one or two columns. The keys center, kappa and extra_df are accepted and ignored: the absorbed effects set the degrees of freedom. See HomoskedasticCovariance, HeteroskedasticCovariance, KernelCovariance and ClusteredCovariance for the details.

Returns:¶

Results container.

Return type:¶

linearmodels.iv.absorbing.AbsorbingLSResults

Raises:¶

• ValueError – If method is not supported, if absorb_options contains options of the algorithm that is not used, if lsmr_options is used with absorb_options or with method="hdfe", if all columns in exog are absorbed and drop_absorbed is True, if debiased is True and the model has no degrees of freedom left, or if the labels of clusters do not match the labels of the other inputs. A key of cov_config that the covariance estimator that cov_type selects does not accept also raises it. The message names the key and lists the accepted keys. This is checked before the model is estimated. Releases before 7.1 raised the TypeError of the constructor of the covariance estimator.

• RuntimeError – If method is “hdfe” and the model cannot be absorbed using HDFE.

• Exception – An AbsorbingEffectError, which is defined in linearmodels.panel.utility, if a variable in exog is absorbed by the effects and drop_absorbed is False.

• UnknownOptionError – If cov_type or kernel is not supported. It is both a KeyError and a ValueError.

Warns:¶

• AbsorbingEffectWarning – If a variable in exog is absorbed by the effects and drop_absorbed is True. The variable is dropped.

• FutureWarning – If lsmr_options is used.

See also

linearmodels.iv.covariance.HomoskedasticCovariance

Homoskedastic covariance.

linearmodels.iv.covariance.HeteroskedasticCovariance

Heteroskedasticity robust covariance.

linearmodels.iv.covariance.KernelCovariance

Kernel (HAC) covariance.

linearmodels.iv.covariance.ClusteredCovariance

Clustered covariance.

Notes

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

Observations with a missing value in dependent, exog, weights, absorb or interactions are dropped when the model is created. When cov_type is “clustered”, clusters must have one row for each of the remaining observations, so the rows of clusters that belong to dropped observations must be dropped too.

If use_cache is True, then variables are hashed based on their contents using either a 64-bit value (if xxhash is installed) or a 256-bit value. This allows variables to be reused in different models if the set of absorbing variables and interactions is held constant. The options used to absorb the variables are part of what identifies them.

If debiased is True, the covariance estimator is adjusted for the degrees of freedom that the model uses: the k regressors in exog that are estimated and the d degrees of freedom of the absorbed terms. They are the dummy variables of the effects, with one less if exog has a constant and one less for each effect after the first, the absorbed continuous variables and the interactions, which is df_absorbed. The unadjusted, robust and kernel covariances are multiplied by n / (n - k - d), and the clustered covariance by g (n - 1) / ((g - 1) (n - k - d)) where g is the number of clusters. The result is that of the regression of the dependent variable on exog and the dummy variables of the effects. It is also that of PanelOLS(debiased=True) with the same effects, using group_debias=True for the clustered covariance. The exception is a clustered covariance when there is a single categorical effect and each of its categories is in one cluster of every cluster variable: its degrees of freedom are not counted, since the effect is nested in the clusters, as in PanelOLS and Stata. Unlike PanelOLS, nothing is adjusted if debiased is False. The t and F distributions of the results use df_resid whatever the covariance estimator. A ValueError is raised if debiased is True and the model has no degrees of freedom left.

The variables are absorbed when fit is called for the first time. A later call uses the same absorbed variables if method, absorb_options and use_cache have the same values, so that changing only the covariance estimator is fast. If any of them differs, the variables are absorbed again using the new values.