"""Results containers for panel models, and tools to compare them."""
from __future__ import annotations
from linearmodels.compat.statsmodels import Summary
from collections.abc import Mapping
import datetime as dt
from functools import cached_property
from typing import Any, NamedTuple, Union
import warnings
from formulaic.utils.context import capture_context
import numpy as np
from pandas import DataFrame, Series, concat
from scipy import stats
from statsmodels.iolib.summary import SimpleTable, fmt_2cols, fmt_params
from linearmodels.iv.results import default_txt_fmt, stub_concat, table_concat
from linearmodels.panel.covariance import HomoskedasticCovariance
from linearmodels.panel.data import PanelDataLike
from linearmodels.shared.alignment import same_labels
from linearmodels.shared.base import _ModelComparison, _SummaryStr
from linearmodels.shared.hypotheses import (
InapplicableTestStatistic,
InvalidTestStatistic,
NormalTestStatistic,
WaldTestStatistic,
quadratic_form_test,
)
from linearmodels.shared.io import _str, add_star, pval_format
from linearmodels.shared.utility import AttrDict
import linearmodels.typing.data
__all__ = [
"FamaMacBethResults",
"HausmanTestResults",
"PanelEffectsResults",
"PanelResults",
"RandomEffectsResults",
"compare",
]
[docs]
class PanelResults(_SummaryStr):
"""
Results container for panel data models that do not include effects.
Parameters
----------
res : AttrDict
The results of the estimation, which the ``fit`` method of the model
constructs.
"""
def __init__(self, res: AttrDict):
self._params = res.params.squeeze()
self._deferred_cov = res.deferred_cov
self._debiased = res.debiased
self._df_resid = res.df_resid
self._df_model = res.df_model
self._nobs = res.nobs
self._name = res.name
self._var_names = res.var_names
self._residual_ss = res.residual_ss
self._total_ss = res.total_ss
self._r2 = res.r2
self._r2w = res.r2w
self._r2b = res.r2b
self._r2o = res.r2o
self._c2w = res.c2w
self._c2b = res.c2b
self._c2o = res.c2o
self._s2 = res.s2
self._entity_info = res.entity_info
self._time_info = res.time_info
self.model = res.model
self._cov_type = res.cov_type
self._datetime = dt.datetime.now()
self._resids = res.resids
self._wresids = res.wresids
self._index = res.index
self._f_info = res.f_info
self._f_stat = res.f_stat
self._loglik = res.loglik
self._fitted = res.fitted
self._effects = res.effects
self._idiosyncratic = res.idiosyncratic
self._original_index = res.original_index
self._not_null = res.not_null
@property
def params(self) -> Series:
"""Estimated parameters."""
return Series(self._params, index=self._var_names, name="parameter")
[docs]
@cached_property
def cov(self) -> DataFrame:
"""Estimated covariance of parameters."""
return DataFrame(
self._deferred_cov(), columns=self._var_names, index=self._var_names
)
@property
def std_errors(self) -> Series:
"""Estimated parameter standard errors."""
return Series(np.sqrt(np.diag(self.cov)), self._var_names, name="std_error")
@property
def tstats(self) -> Series:
"""Parameter t-statistics."""
return Series(self._params / self.std_errors, name="tstat")
[docs]
@cached_property
def pvalues(self) -> Series:
"""
Parameter p-vals. Uses t(df_resid) if ``debiased`` is True, else normal.
"""
abs_tstats = np.abs(self.tstats)
if self._debiased:
pv = 2 * stats.t.sf(abs_tstats, self.df_resid)
else:
pv = 2 * stats.norm.sf(abs_tstats)
return Series(pv, index=self._var_names, name="pvalue")
@property
def df_resid(self) -> int:
"""
Residual degree of freedom.
Notes
-----
Defined as nobs minus nvar minus the number of included effects, if any.
"""
return self._df_resid
@property
def df_model(self) -> int:
"""
Model degree of freedom.
Notes
-----
Defined as nvar plus the number of included effects, if any.
"""
return self._df_model
@property
def nobs(self) -> int:
"""Number of observations used to estimate the model."""
return self._nobs
@property
def name(self) -> str:
"""Model name."""
return self._name
@property
def total_ss(self) -> float:
"""Total sum of squares."""
return self._total_ss
@property
def model_ss(self) -> float:
"""Model sum of squares."""
return self._total_ss - self._residual_ss
@property
def resid_ss(self) -> float:
"""Residual sum of squares."""
return self._residual_ss
@property
def rsquared(self) -> float:
"""
Model coefficient of determination.
Returns
-------
float
The coefficient of determination of the model.
Notes
-----
The coefficient of determination is NaN if its total sum of squares is zero,
up to rounding error, since it is not defined then. This happens if the
dependent variable does not vary, or if nothing varies once the means or the
effects of the model are removed. No error or warning is raised.
The limit is the rounding error of the computation. If the effects are removed
by an iterative algorithm (``use_lsmr=True`` in ``fit``), its error is larger,
by default about 1e-8 relative to the size of the dependent variable, so that a
dependent variable that the effects explain exactly can have a total sum of
squares that is not recognized as zero.
"""
return self._r2
@property
def rsquared_between(self) -> float:
"""
Between coefficient of determination.
Returns
-------
float
Between coefficient of determination.
Notes
-----
The between rsquared measures the fit of the time-averaged dependent
variable on the time averaged dependent variables. It accounts for the
weights used in the estimation of the model.
See the mathematical reference in the documentation for the formal
definition of this measure.
It is NaN if its total sum of squares is zero, up to rounding error, i.e., if
the time-averaged dependent variable is the same for every entity in a model
with a constant, or is 0 for every entity in a model without one. No error or
warning is raised.
"""
return self._r2b
@property
def rsquared_within(self) -> float:
"""
Within coefficient of determination.
Returns
-------
float
Within coefficient of determination.
Notes
-----
The within rsquared measures the fit of the dependent purged of entity
effects on the exogenous purged of entity effects. It accounts for the
weights used in the estimation of the model.
See the mathematical reference in the documentation for the formal
definition of this measure.
It is NaN if its total sum of squares is zero, up to rounding error, i.e., if
the dependent variable does not vary within entities, which includes a panel
with a single time period. No error or warning is raised.
"""
return self._r2w
@property
def rsquared_overall(self) -> float:
"""
Overall coefficient of determination.
Returns
-------
float
Overall coefficient of determination.
Notes
-----
The overall rsquared measures the fit of the dependent
variable on the dependent variables ignoring any included effects.
It accounts for the weights used in the estimation of the model.
See the mathematical reference in the documentation for the formal
definition of this measure.
It is NaN if its total sum of squares is zero, up to rounding error, i.e., if
the dependent variable does not vary in a model with a constant, or is 0 in a
model without one. No error or warning is raised.
"""
return self._r2o
@property
def corr_squared_between(self) -> float:
r"""
Between coefficient of determination using squared correlation.
Returns
-------
float
Between coefficient of determination.
Notes
-----
The between rsquared measures the fit of the time-averaged dependent
variable on the time averaged dependent variables.
This measure is based on the squared correlation between the
entity-wise averaged dependent variables and their average
predictions.
.. math::
Corr[\bar{y}_i, \bar{x}_i\hat{\beta}]
This measure **does not** account for weights.
It is NaN if the entity-wise averaged dependent variable is the same for every
entity, up to rounding error, since the correlation is not defined, and it is 0
if the predictions are the same for every entity. No error or warning is
raised.
"""
return self._c2b
@property
def corr_squared_within(self) -> float:
r"""
Within coefficient of determination using squared correlation.
Returns
-------
float
Within coefficient of determination.
Notes
-----
The within rsquared measures the fit of the dependent purged of entity
effects on the exogenous purged of entity effects.
This measure is based on the squared correlation between the
entity-wise demeaned dependent variables and their demeaned
predictions.
.. math::
Corr[y_{it}-\bar{y}_i, (x_{it}-\bar{x}_i)\hat{\beta}]
This measure **does not** account for weights.
It is NaN if the dependent variable does not vary within entities, up to
rounding error, since the correlation is not defined, and it is 0 if the
demeaned predictions do not vary. No error or warning is raised.
"""
return self._c2w
@property
def corr_squared_overall(self) -> float:
r"""
Overall coefficient of determination using squared correlation.
Returns
-------
float
Overall coefficient of determination.
Notes
-----
The overall rsquared measures the fit of the dependent
variable on the dependent variables ignoring any included effects.
This measure is based on the squared correlation between the
dependent variables and their predictions.
.. math::
Corr[y_{it}, x_{it}\hat{\beta}]
This measure **does not** account for weights.
It is NaN if the dependent variable does not vary, up to rounding error, since
the correlation is not defined, and it is 0 if the predictions do not vary. No
error or warning is raised.
"""
return self._c2o
@property
def s2(self) -> float:
"""Residual variance estimator."""
return self._s2
@property
def entity_info(self) -> Series:
"""Statistics on observations per entity."""
return self._entity_info
@property
def time_info(self) -> Series:
"""Statistics on observations per time interval."""
return self._time_info
[docs]
def conf_int(self, level: float = 0.95) -> DataFrame:
"""
Confidence interval construction.
Parameters
----------
level : float, optional
Confidence level for interval. The default is 0.95.
Returns
-------
DataFrame
Confidence interval of the form [lower, upper] for each parameter.
Notes
-----
Uses a t(df_resid) if ``debiased`` is True, else normal.
"""
ci_quantiles = np.array([(1 - level) / 2, 1 - (1 - level) / 2])
if self._debiased:
q: np.ndarray = stats.t.ppf(ci_quantiles, self.df_resid)
else:
q = stats.norm.ppf(ci_quantiles)
q = q[None, :]
params = np.asarray(self.params)[:, None]
ci = params + np.asarray(self.std_errors)[:, None] * q
return DataFrame(ci, index=self._var_names, columns=["lower", "upper"])
@property
def summary(self) -> Summary:
"""
Model estimation summary.
Returns
-------
Summary
Summary table of model estimation results.
Notes
-----
Supports export to csv, html and latex using the methods ``summary.as_csv()``,
``summary.as_html()`` and ``summary.as_latex()``.
"""
title = self.name + " Estimation Summary"
mod = self.model
top_left = [
("Dep. Variable:", mod.dependent.vars[0]),
("Estimator:", self.name),
("No. Observations:", self.nobs),
("Date:", self._datetime.strftime("%a, %b %d %Y")),
("Time:", self._datetime.strftime("%H:%M:%S")),
("Cov. Estimator:", self._cov_type),
("", ""),
("Entities:", str(int(self.entity_info["total"]))),
("Avg Obs:", _str(self.entity_info["mean"])),
("Min Obs:", _str(self.entity_info["min"])),
("Max Obs:", _str(self.entity_info["max"])),
("", ""),
("Time periods:", str(int(self.time_info["total"]))),
("Avg Obs:", _str(self.time_info["mean"])),
("Min Obs:", _str(self.time_info["min"])),
("Max Obs:", _str(self.time_info["max"])),
("", ""),
]
is_invalid = np.isfinite(self.f_statistic.stat)
f_stat = _str(self.f_statistic.stat) if is_invalid else "--"
f_pval = pval_format(self.f_statistic.pval) if is_invalid else "--"
f_dist = self.f_statistic.dist_name if is_invalid else "--"
f_robust = _str(self.f_statistic_robust.stat) if is_invalid else "--"
f_robust_pval = (
pval_format(self.f_statistic_robust.pval) if is_invalid else "--"
)
f_robust_name = self.f_statistic_robust.dist_name if is_invalid else "--"
top_right = [
("R-squared:", _str(self.rsquared)),
("R-squared (Between):", _str(self.rsquared_between)),
("R-squared (Within):", _str(self.rsquared_within)),
("R-squared (Overall):", _str(self.rsquared_overall)),
("Log-likelihood", _str(self._loglik)),
("", ""),
("F-statistic:", f_stat),
("P-value", f_pval),
("Distribution:", f_dist),
("", ""),
("F-statistic (robust):", f_robust),
("P-value", f_robust_pval),
("Distribution:", f_robust_name),
("", ""),
("", ""),
("", ""),
("", ""),
]
stubs = []
vals = []
for stub, val in top_left:
stubs.append(stub)
vals.append([val])
table = SimpleTable(vals, txt_fmt=fmt_2cols, title=title, stubs=stubs)
# create summary table instance
smry = Summary()
# Top Table
# Parameter table
fmt = fmt_2cols
fmt["data_fmts"][1] = "%18s"
top_right = [("%-21s" % (" " + k), v) for k, v in top_right]
stubs = []
vals = []
for stub, val in top_right:
stubs.append(stub)
vals.append([val])
table.extend_right(SimpleTable(vals, stubs=stubs))
smry.tables.append(table)
if self.params.shape[0] == 0:
# A model that only has effects has no table of parameters
return smry
param_data = np.c_[
self.params.to_numpy()[:, None],
self.std_errors.to_numpy()[:, None],
self.tstats.to_numpy()[:, None],
self.pvalues.to_numpy()[:, None],
self.conf_int().to_numpy(),
]
data = []
for row in param_data:
txt_row = []
for i, v in enumerate(row):
f = _str
if i == 3:
f = pval_format
txt_row.append(f(v))
data.append(txt_row)
title = "Parameter Estimates"
table_stubs = list(self.params.index)
header = ["Parameter", "Std. Err.", "T-stat", "P-value", "Lower CI", "Upper CI"]
table = SimpleTable(
data, stubs=table_stubs, txt_fmt=fmt_params, headers=header, title=title
)
smry.tables.append(table)
return smry
@property
def resids(self) -> Series:
"""
Model residuals.
Notes
-----
These residuals are from the estimated model. They will not have the
same shape as the original data whenever the model is estimated on
transformed data which has a different shape.
"""
return Series(self._resids.squeeze(), index=self._index, name="residual")
def _out_of_sample(
self,
exog: PanelDataLike | None,
data: DataFrame | None,
missing: bool,
context: Mapping[str, Any] | None = None,
) -> DataFrame:
"""Interface between model predict and predict for OOS fits"""
if exog is not None and data is not None:
raise ValueError(
"Predictions can only be constructed using one "
"of exog or data, but not both."
)
pred = self.model.predict(self.params, exog=exog, data=data, context=context)
if not missing:
pred = pred.loc[pred.notnull().all(axis=1)]
return pred
[docs]
def predict(
self,
exog: PanelDataLike | None = None,
*,
data: DataFrame | None = None,
fitted: bool = True,
effects: bool = False,
idiosyncratic: bool = False,
missing: bool = False,
) -> DataFrame:
"""
In- and out-of-sample predictions.
Parameters
----------
exog : PanelData, DataFrame, Series, ndarray or DataArray, optional
Exogenous values to use in out-of-sample prediction (nobs by nexog).
The containers are those of ``exog`` in the model. A list or a tuple
raises a ``TypeError`` that names ``exog``. If neither `exog` nor
`data` is provided, the in-sample values are returned.
data : DataFrame, optional
DataFrame to use for out-of-sample predictions when model was
constructed using a formula.
fitted : bool, optional
Flag indicating whether to include the fitted values. The default
is True. Only used for in-sample values.
effects : bool, optional
Flag indicating whether to include estimated effects. The default
is False. Only used for in-sample values.
idiosyncratic : bool, optional
Flag indicating whether to include the estimated idiosyncratic
shock. The default is False. Only used for in-sample values.
missing : bool, optional
Flag indicating to adjust for dropped observations. If True, the
values returned will have the same size as the original input data
before filtering missing values. The default is False.
Returns
-------
DataFrame
DataFrame containing columns for all selected output.
Raises
------
ValueError
If both `exog` and `data` are provided, if no in-sample output
is selected, or if `effects` or `idiosyncratic` is requested for
out-of-sample predictions.
Notes
-----
`data` can only be used when the model was created using the formula
interface. `exog` can be used for both a model created using a formula
or a model specified with dependent and exog arrays.
When using `exog` to generate out-of-sample predictions, the variable
order must match the variables in the original model.
Idiosyncratic errors and effects are not available for out-of-sample
predictions.
"""
if not (exog is None and data is None):
if effects or idiosyncratic:
raise ValueError(
"effects and idiosyncratic are not available for "
"out-of-sample predictions"
)
if not fitted:
raise ValueError("At least one output must be selected")
context = capture_context(1)
return self._out_of_sample(exog, data, missing, context=context)
out = []
if fitted:
out.append(self.fitted_values)
if effects:
out.append(self.estimated_effects)
if idiosyncratic:
out.append(self.idiosyncratic)
if len(out) == 0:
raise ValueError("At least one output must be selected")
out_df: DataFrame = concat(out, axis=1)
if missing:
index = self._original_index
out_df = out_df.reindex(index)
return out_df
@property
def fitted_values(self) -> DataFrame:
"""Fitted values."""
return self._fitted
@property
def estimated_effects(self) -> DataFrame:
"""
Estimated effects.
Notes
-----
The combined effect of all of the effects in the model, in one column.
It is the sum of the entity, time and other effects of each
observation. The effects are not available separately.
See :ref:`panel-estimated-effects` for how to recover the entity and
time effects of a model that has both.
The estimated effects have no standard errors or any other inference.
They are not estimated consistently when the number of time periods is
fixed. The effect of an entity is estimated from its observations, so
the error does not shrink when the number of entities grows. To make
inference about the effects of a small number of entities, include
them as dummy variables in the regression.
The values are NaN for models that do not have effects, which are
PooledOLS, FirstDifferenceOLS and FamaMacBeth. They are 0 for a
PanelOLS model without effects.
The effects of RandomEffects are theta times the entity mean of the
difference between the dependent variable and the fitted values, where
theta is in the results. They are all 0 if the estimated variance of
the random effect is negative and so it is set to 0, since theta is
then 0 and the model is pooled OLS. ``variance_decomposition`` shows
whether this is the case.
"""
return self._effects
@property
def idiosyncratic(self) -> DataFrame:
r"""
Idiosyncratic error.
Notes
-----
Differs from resids since this is the estimated idiosyncratic shock
from the data. It has the same dimension as the dependent data.
The shape and nature of resids depends on the model estimated. These
estimates only depend on the model estimated through the estimation
of parameters and inclusion of effects, if any.
For ``FirstDifferenceOLS`` the values are the dependent variable less
the fitted values, :math:`y_{it} - x_{it}\hat{\beta}`, in levels. They
are not the shocks of the differenced equation, which are in ``resids``.
"""
return self._idiosyncratic
@property
def wresids(self) -> Series:
"""Weighted model residuals."""
return Series(
self._wresids.squeeze(), index=self._index, name="weighted residual"
)
def _pesaran_cd_inapplicable(self) -> str | None:
"""Reason why the Pesaran CD test is not valid for the model, if any"""
from linearmodels.panel.model import BetweenOLS # noqa: PLC0415
if isinstance(self.model, BetweenOLS):
return (
"The Pesaran CD test is not applicable to BetweenOLS. The model "
"is fitted to the entity means, so it has no time-varying "
"residuals, and the series implied by its coefficients is not "
"the model's error."
)
return None
[docs]
@cached_property
def pesaran_cd(self) -> InapplicableTestStatistic | NormalTestStatistic:
r"""
Pesaran CD test of residual cross-sectional dependence.
Returns
-------
NormalTestStatistic or InapplicableTestStatistic
Statistic value, distribution and p-value. If the test is not
valid for the model, an InapplicableTestStatistic that explains
why in its reason.
Notes
-----
Tests the null hypothesis that the model's idiosyncratic shocks are
cross-sectionally independent [1]_. Let :math:`\hat{\rho}_{ij}` denote
the sample correlation of the estimated idiosyncratic shocks for
entities :math:`i` and :math:`j`, computed using their common time
observations, and let :math:`T_{ij}` denote the number of overlapping
observations. The statistic is
.. math::
CD = \frac{1}{\sqrt{M}}\sum_{i<j}\sqrt{T_{ij}}\hat{\rho}_{ij},
where :math:`M` is the number of entity pairs with at least two
overlapping observations and finite pairwise correlation estimates.
Under the null, the statistic is asymptotically standard normal.
The shocks are the model's ``idiosyncratic`` values, so the weights of
a weighted model are not applied to them. The exception is
``FirstDifferenceOLS``, which uses ``resids``, the residuals of the
differenced equation, as ``plm::pcdtest`` does for a pooled regression
of the differenced data. Its ``idiosyncratic`` values are in levels,
and are persistent when the errors are, for example a random walk,
which is when first differences are used. Since the correlations are
computed over time, the test assumes that the shocks are not serially
correlated, and it over-rejects if they are persistent. Conversely, if
the errors in levels are serially uncorrelated, the residuals of
``FirstDifferenceOLS`` are negatively autocorrelated (an MA(1) with
autocorrelation -0.5) and the test over-rejects, with a size of about
11% at the nominal 5% level in large panels. The test is then better
applied to a ``PanelOLS`` model with entity effects.
The test is not valid for every model and an InapplicableTestStatistic
is returned for the following.
* ``BetweenOLS``. The model is fitted to the entity means, so it has
no time-varying residuals, and the series implied by its
coefficients is not the model's error.
* ``FamaMacBeth``. The model's errors are the residuals of the
period-by-period cross-sectional regressions. The series implied by
the averaged coefficients contains the common, time-varying term
:math:`(\beta_t - \bar{\beta})^{\prime}x_{it}`, so it is
cross-sectionally dependent by construction. Fama-MacBeth inference
is also already robust to cross-sectional dependence.
* Models with time effects, and models with other effects that
change over time for some entity and have a group of several
entities that is missing from some periods, such as period,
industry-by-period or decade effects. These effects demean the
residuals across entities that are observed in the same periods,
which makes the residuals negatively correlated across entities
and biases the statistic downwards. For example, when the model
has time effects and the errors are independent, the statistic is
centered at about :math:`-\sqrt{T/2}` and its standard deviation
is far below 1, so it is not standard normal [2]_. Other effects
that do not change over time for an entity, or that are present
in every period, are not affected.
Time dummy variables (for example ``C(year)``) among the regressors have
the same effect on the residuals as time effects, and make the test
invalid in the same way. The code cannot reliably detect
such regressors, so that the test is returned without a warning and
should not be used for a model that has them.
The statistic is computed from dense N by N matrices of pairwise
correlations and numbers of overlapping observations, where N is the
number of entities. Computing them takes about 450 MB of memory when
N is 4,000, and the memory use is proportional to the square of N.
References
----------
.. [1] Pesaran, M. H. (2021). General diagnostic tests for
cross-sectional dependence in panels. Empirical Economics, 60(1),
13-50.
.. [2] Juodis, A. and Reese, S. (2022). The incidental parameters
problem in testing for remaining cross-section correlation.
Journal of Business & Economic Statistics, 40(3), 1191-1203.
"""
from linearmodels.panel.model import FirstDifferenceOLS # noqa: PLC0415
reason = self._pesaran_cd_inapplicable()
if reason is not None:
return InapplicableTestStatistic(reason=reason, name="Pesaran CD test")
if isinstance(self.model, FirstDifferenceOLS):
eps = self.resids
else:
eps = self.idiosyncratic.iloc[:, 0]
wide = eps.unstack(level=0)
wide = wide.loc[:, wide.notnull().any(axis=0)]
nentity = wide.shape[1]
if nentity < 2:
return InapplicableTestStatistic(
reason="Pesaran CD test requires at least two entities.",
name="Pesaran CD test",
)
corr = wide.corr(min_periods=2).to_numpy(dtype=float)
counts = wide.notnull().to_numpy(dtype=np.int64).T @ wide.notnull().to_numpy(
dtype=np.int64
)
selector = np.tril(np.ones_like(counts, dtype=bool), k=-1)
selector &= counts >= 2
selector &= np.isfinite(corr)
npairs = int(selector.sum())
if npairs == 0:
return InapplicableTestStatistic(
reason=(
"Pesaran CD test requires at least one pair of entities "
"with two or more overlapping observations."
),
name="Pesaran CD test",
)
stat = float(
np.sum(np.sqrt(counts[selector].astype(float)) * corr[selector])
/ np.sqrt(npairs)
)
null = "Idiosyncratic shocks are cross-sectionally independent"
return NormalTestStatistic(stat, null, name="Pesaran CD test")
@property
def f_statistic_robust(self) -> WaldTestStatistic:
r"""
Joint test of significance for non-constant regressors.
Returns
-------
WaldTestStatistic or InvalidTestStatistic
Statistic value, distribution and p-value. An ``InvalidTestStatistic``
is returned if the test cannot be computed, as described in Notes.
Notes
-----
Implemented as a Wald test using the estimated parameter covariance,
and so inherits any robustness that the choice of covariance estimator
provides.
.. math::
W = \hat{\beta}_{-}' \hat{\Sigma}_{-}^{-1} \hat{\beta}_{-}
where :math:`\hat{\beta}_{-}` does not include the model constant and
:math:`\hat{\Sigma}_{-}` is the estimated covariance of the
parameters, also excluding the constant. The test statistic is
distributed as :math:`\chi^2_{k}` where k is the number of non-
constant parameters.
If ``debiased`` is True, then the Wald statistic is divided by the
number of restrictions and inference is made using an :math:`F_{k,df}`
distribution where df is the residual degree of freedom from the model.
An ``InvalidTestStatistic`` is returned if the model only has a constant,
or if the covariance of the parameters is singular, e.g., the dependent
variable is all zero, so that the model fits exactly.
"""
from linearmodels.panel.model import _deferred_f # noqa: PLC0415
return _deferred_f(
self.params, self.cov, self._debiased, self.df_resid, self._f_info
)
@property
def f_statistic(self) -> WaldTestStatistic:
r"""
Joint test of significance for non-constant regressors.
Returns
-------
WaldTestStatistic or InvalidTestStatistic
Statistic value, distribution and p-value. An ``InvalidTestStatistic``
is returned if the model has no regressors, only a constant, or no
residual degrees of freedom.
Notes
-----
Classical F-stat that is only correct under an assumption of
homoskedasticity. The test statistic is defined as
.. math::
F = \frac{(RSS_R - RSS_U)/ k}{RSS_U / df_U}
where :math:`RSS_R` is the restricted sum of squares from the model
where the coefficients on all exog variables is zero, excluding a
constant if one was included. :math:`RSS_U` is the unrestricted
residual sum of squares. k is the number of non-constant regressors
in the model and :math:`df_U` is the residual degree of freedom in the
unrestricted model. The test has an :math:`F_{k,df_U}` distribution.
"""
return self._f_stat
@property
def loglik(self) -> float:
r"""
Log-likelihood of model.
Notes
-----
The Gaussian log-likelihood of the regression that the model estimates, at
the estimates and the maximum likelihood estimate of the error variance,
.. math::
-\frac{n}{2}\left(\ln 2\pi + \ln\hat{\sigma}^2 + 1\right)
+ \frac{1}{2}\sum_{i=1}^{n}\ln w_i
where :math:`\hat{\sigma}^2 = \hat{\epsilon}'\hat{\epsilon}/n` is the
residual sum of squares of the regression divided by its number of
observations :math:`n`, and :math:`\hat{\epsilon}_i` are the weighted
residuals, :math:`\sqrt{w_i}` times the residuals. The last term is the
Jacobian of the weights, which is 0 if the model is not weighted. The
variance of the error of observation :math:`i` is
:math:`\sigma^2/w_i`, and so the log-likelihood is that of the weighted least
squares regression of the original data, for example of ``WLS(...).llf`` in
statsmodels for ``PooledOLS``. It does not depend on the scale of the weights,
and the log-likelihoods of the models with different weights are comparable
if they have the same observations, for example in an information
criterion.
The regression and its observations depend on the model.
* ``PooledOLS`` - The regression of the observations. The weights are the
weights of the model.
* ``PanelOLS`` - The regression on the dummy variables of the effects, with
the effects as parameters that are estimated. It is computed from the
regression of the observations with the effects removed. The weights are
the weights of the model.
* ``BetweenOLS`` - The regression of the means of the entities. The
observations are the entities, and the weights are the sums of the
weights of the entities, scaled to a mean of one, if the model is weighted
or ``reweight`` is True. Otherwise all of the weights are 1.
* ``FirstDifferenceOLS`` - The regression of the first differences. The
weights are those of the differences, :math:`1/(1/w_{it}+1/w_{it-1})`.
* ``RandomEffects`` - The regression of the data that are weighted and
quasi-demeaned. It is not the likelihood of the random effects model, which
also depends on the variances of the effects.
* ``FamaMacBeth`` - The pooled regression at the average of the estimates
of the periods.
.. versionchanged:: 7.1
The log-likelihood of a weighted model includes the Jacobian of the
weights. Earlier versions omitted it, so that the log-likelihood was that
of the regression of the weighted data, which is not the likelihood of the
original data, and the log-likelihoods of models with different weights
were not comparable. For the pooled regression of the log wages in the wage
panel on a constant, ``educ``, ``married`` and ``union`` with the hours as
weights it was -3065.75, where ``WLS`` of statsmodels has -3153.16. The
log-likelihoods of models without weights do not change.
"""
return self._loglik
[docs]
def wald_test(
self,
restriction: linearmodels.typing.data.Float64Array | DataFrame | None = None,
value: linearmodels.typing.data.Float64Array | Series | None = None,
*,
formula: str | list[str] | None = None,
) -> WaldTestStatistic:
r"""
Test linear equality constraints using a Wald test.
Parameters
----------
restriction : array_like, optional
Array with q rows and nvar columns containing linear weights to
apply to parameters when forming the restrictions. It is not
possible to use both restriction and formula.
value : array_like, optional
Array with q elements containing the restricted values. If not
provided, the restricted values are all 0.
formula : str, list of str or dict of str to float, optional
Formulaic linear constraints. The simplest formats are one of:
* A single comma-separated string such as "x1=0, x2+x3=1"
* A list of strings where each element is a single constraint
such as ["x1=0", "x2+x3=1"]
* A single string without commas to test simple constraints such
as "x1=x2=x3=0"
* A dictionary where each key is a parameter restriction and
the corresponding value is the restriction value, e.g.,
{"x1": 0, "x2+x3": 1}.
It is not possible to use both ``restriction`` and ``formula``.
The names in the restrictions are the entries of the index of
``params``. A name that is not valid Python, for example one that
contains ``:`` or ``[`` such as ``C(year)[T.1987]:educ``, must be
enclosed in back-ticks, e.g.,
``"`C(year)[T.1987]:educ` = 0"``.
Returns
-------
WaldTestStatistic
Test statistic for null that restrictions are valid.
Raises
------
ValueError
If the model has no parameters, e.g., a PanelOLS model that only has
effects, or if both `restriction` and `formula` are provided.
Notes
-----
Hypothesis test examines whether :math:`H_0:C\theta=v` where the
matrix C is ``restriction`` and v is ``value``. The test statistic
has a :math:`\chi^2_q` distribution where q is the number of rows in C.
Examples
--------
>>> from linearmodels.datasets import wage_panel
>>> import statsmodels.api as sm
>>> import numpy as np
>>> import pandas as pd
>>> data = wage_panel.load()
>>> year = pd.Categorical(data.year)
>>> data = data.set_index(["nr", "year"])
>>> data["year"] = year
>>> from linearmodels.panel import PanelOLS
>>> exog_vars = ["expersq", "union", "married", "year"]
>>> exog = sm.add_constant(data[exog_vars])
>>> mod = PanelOLS(data.lwage, exog, entity_effects=True)
>>> fe_res = mod.fit()
Test the restriction that union and married have 0 coefficients
>>> restriction = np.zeros((2, 11))
>>> restriction[0, 2] = 1
>>> restriction[1, 3] = 1
>>> value = np.array([0, 0])
>>> wald_res = fe_res.wald_test(restriction, value)
The same test using formulas
>>> formula = "union = married = 0"
>>> wald_res = fe_res.wald_test(formula=formula)
A name that is not valid Python, such as the interaction of a
categorical variable with a regressor, is enclosed in back-ticks
>>> from linearmodels import PooledOLS
>>> mod = PooledOLS.from_formula("lwage ~ 1 + union + C(year) * educ", data)
>>> res = mod.fit(cov_type="clustered", cluster_entity=True)
>>> null = "`C(year)[T.1987]:educ` = 0, `C(year)[T.1986]:educ` = 0"
>>> wald_res = res.wald_test(formula=null)
"""
if self.params.shape[0] == 0:
raise ValueError(
"The model has no parameters, so that there is nothing to test. It "
"only has effects, which have no inference."
)
return quadratic_form_test(
self.params, self.cov, restriction=restriction, value=value, formula=formula
)
def _is_concentrated_in_time(groups: Any, entity_ids: Any, time_ids: Any) -> bool:
"""
Test whether groups of entities change over time and are missing in periods
Removing the mean of a group that is the same in every period for an
entity does not change the correlations over time. Removing the mean of a
group that changes over time and is not observed in every period removes a
component that varies over time and is shared by the entities in the group.
A group with a single entity is not shared.
"""
frame = DataFrame(
{
"group": np.asarray(groups).ravel(),
"entity": np.asarray(entity_ids).ravel(),
"time": np.asarray(time_ids).ravel(),
}
)
if frame.groupby("entity")["group"].nunique().max() <= 1:
return False
by_group = frame.groupby("group")
shared = by_group["entity"].nunique() > 1
nperiod = frame["time"].nunique()
return bool((by_group["time"].nunique()[shared] < nperiod).any())
[docs]
class PanelEffectsResults(PanelResults):
"""
Results container for panel data models that include effects.
Parameters
----------
res : AttrDict
The results of the estimation, which the ``fit`` method of the model
constructs.
"""
def __init__(self, res: AttrDict) -> None:
super().__init__(res)
self._other_info = res.other_info
self._f_pooled = res.f_pooled
self._entity_effect = res.entity_effects
self._time_effect = res.time_effects
self._other_effect = res.other_effects
self._rho = res.rho
self._sigma2_eps = res.sigma2_eps
self._sigma2_effects = res.sigma2_effects
self._r2_ex_effects = res.r2_ex_effects
self._effects = res.effects
def _pesaran_cd_inapplicable(self) -> str | None:
reason = (
"The Pesaran CD test is not applicable to models with {effect}. "
"These effects demean the residuals across entities that are "
"observed in the same periods, which makes the residuals "
"negatively correlated across entities and biases the statistic "
"downwards, away from its null distribution (Juodis and Reese, "
"2022)."
)
if self._time_effect:
return reason.format(effect="time effects")
if self._other_effect:
other = self.model._other_effect_cats.dataframe
entity_ids = self.model.dependent.entity_ids
time_ids = self.model.dependent.time_ids
for col in other:
if _is_concentrated_in_time(other[col], entity_ids, time_ids):
return reason.format(
effect="other effects that are concentrated in some periods"
)
return super()._pesaran_cd_inapplicable()
@property
def f_pooled(self) -> WaldTestStatistic:
r"""
Test that included effects are jointly zero.
Returns
-------
WaldTestStatistic, InapplicableTestStatistic or InvalidTestStatistic
Statistic value, distribution and p-value. It is an
``InapplicableTestStatistic`` if the effects do not use any degrees
of freedom, e.g., a single entity with a constant, and an
``InvalidTestStatistic`` if the model has no residual degrees of
freedom or its residual sum of squares is 0.
Notes
-----
Joint test that all included effects are zero. Only correct under an
assumption of homoskedasticity.
The test statistic is defined as
.. math::
F = \frac{(RSS_{pool}-RSS_{effect})/(df_{pool}-df_{effect})}
{RSS_{effect}/df_{effect}}
where :math:`RSS_{pool}` is the residual sum of squares from a no-
effect (pooled) model. :math:`RSS_{effect}` is the residual sum of
squares from a model with effects. :math:`df_{pool}` is the residual
degree of freedom in the pooled regression and :math:`df_{effect}` is
the residual degree of freedom from the model with effects. The test
has an :math:`F_{k,df_{effect}}` distribution where
:math:`k=df_{pool}-df_{effect}`.
"""
return self._f_pooled
@property
def included_effects(self) -> list[str]:
"""List of effects included in the model."""
entity_effect = self._entity_effect
time_effect = self._time_effect
other_effect = self._other_effect
effects = []
if entity_effect or time_effect or other_effect:
if entity_effect:
effects.append("Entity")
if time_effect:
effects.append("Time")
if other_effect:
oe = self.model._other_effect_cats.dataframe
effects.extend(["Other Effect (" + str(c) + ")" for c in oe])
return effects
@property
def other_info(self) -> DataFrame | None:
"""Statistics on observations per group for other effects."""
return self._other_info
@property
def rsquared_inclusive(self) -> float:
"""
Model Coefficient of determination including fit of included effects.
Returns
-------
float
The coefficient of determination of the model and the effects.
Notes
-----
It is NaN if its total sum of squares is zero, up to rounding error, i.e., if
the dependent variable does not vary. No error or warning is raised.
"""
return self._r2_ex_effects
@property
def summary(self) -> Summary:
"""
Model estimation summary.
Returns
-------
Summary
Summary table of model estimation results.
Notes
-----
Supports export to csv, html and latex using the methods ``summary.as_csv()``,
``summary.as_html()`` and ``summary.as_latex()``.
"""
smry = super().summary
is_invalid = np.isfinite(self.f_pooled.stat)
f_pool = _str(self.f_pooled.stat) if is_invalid else "--"
f_pool_pval = pval_format(self.f_pooled.pval) if is_invalid else "--"
f_pool_name = self.f_pooled.dist_name if is_invalid else "--"
extra_text = []
if is_invalid:
extra_text.append(f"F-test for Poolability: {f_pool}")
extra_text.append(f"P-value: {f_pool_pval}")
extra_text.append(f"Distribution: {f_pool_name}")
extra_text.append("")
if self.included_effects:
effects = ", ".join(self.included_effects)
extra_text.append("Included effects: " + effects)
if self.other_info is not None:
nrow = self.other_info.shape[0]
plural = "s" if nrow > 1 else ""
extra_text.append(f"Model includes {nrow} other effect{plural}")
for c in self.other_info.T:
col = self.other_info.T[c]
extra_text.append(f"Other Effect {c}:")
stats = "Avg Obs: {0}, Min Obs: {1}, Max Obs: {2}, Groups: {3}"
stats = stats.format(
_str(col["mean"]),
_str(col["min"]),
_str(col["max"]),
int(col["total"]),
)
extra_text.append(stats)
smry.add_extra_txt(extra_text)
return smry
@property
def variance_decomposition(self) -> Series:
"""Decomposition of total variance into effects and residuals."""
vals = [self._sigma2_effects, self._sigma2_eps, self._rho]
index = ["Effects", "Residual", "Percent due to Effects"]
return Series(vals, index=index, name="Variance Decomposition")
def _has_unadjusted_cov(res: PanelResults) -> bool:
"""Test whether results use the unadjusted covariance estimator
The robust, clustered, kernel and autocorrelation-robust estimators all
derive from the unadjusted estimator, so the exact type must be checked.
"""
estimator = getattr(res._deferred_cov, "__self__", None)
return type(estimator) is HomoskedasticCovariance
def _check_same_sample(res: PanelResults, other: PanelResults) -> None:
"""Check that two sets of results use the same data and weights"""
if res.nobs != other.nobs:
raise ValueError(
"The models must be estimated using the same observations. "
f"This model uses {res.nobs} and other uses {other.nobs}."
)
model, other_model = res.model, other.model
if not same_labels(model.dependent.index, other_model.dependent.index):
raise ValueError(
"The models must be estimated using the same observations. The "
"entities and time periods of the observations differ."
)
if not np.allclose(
model.dependent.values2d, other_model.dependent.values2d, rtol=1e-10, atol=0.0
):
raise ValueError(
"The models must have the same dependent variable, but the "
"dependent variables of the models differ."
)
# Weights are rescaled to have mean 1, so only the relative weights matter
if not np.allclose(
model.weights.values2d, other_model.weights.values2d, rtol=1e-10, atol=0.0
):
raise ValueError(
"The models must be estimated using the same weights, but the "
"weights of the models differ."
)
[docs]
class HausmanTestResults(NamedTuple): # numpydoc ignore=PR02
"""
Results of a Hausman specification test.
Parameters
----------
statistic : WaldTestStatistic or InvalidTestStatistic
The test statistic with its p-value, distribution and null hypothesis.
An InvalidTestStatistic is used if the statistic is negative or not
finite, which means that the models do not meet the assumptions of the
test.
estimates : DataFrame
The coefficients included in the test. The columns are ``b0`` (from
the model that is consistent under both hypotheses, ``other``), ``b1``
(from the model that is efficient under the null), their difference
``b0-b1`` and ``Std. Err.``, the standard error of the difference.
The standard error is NaN if the variance of the difference is
negative.
See Also
--------
RandomEffectsResults.hausman
Compute the Hausman specification test.
Notes
-----
The results are a named tuple, so the statistic and the estimates can be
unpacked as in ``statistic, estimates = results`` or read using the
``statistic`` and ``estimates`` fields. Printing the results shows the
statistic followed by the table of estimates.
"""
statistic: WaldTestStatistic | InvalidTestStatistic
estimates: DataFrame
def __str__(self) -> str:
legend = "b0: consistent under H0 and H1, b1: efficient under H0"
return f"{self.statistic}\n\nCoefficients ({legend})\n{self.estimates}"
def __repr__(self) -> str:
return self.__str__()
[docs]
class RandomEffectsResults(PanelResults):
"""
Results container for random effect panel data models.
Parameters
----------
res : AttrDict
The results of the estimation, which the ``fit`` method of the model
constructs.
"""
def __init__(self, res: AttrDict) -> None:
super().__init__(res)
self._theta = res.theta
self._sigma2_effects = res.sigma2_effects
self._sigma2_eps = res.sigma2_eps
self._rho = res.rho
@property
def variance_decomposition(self) -> Series:
"""Decomposition of total variance into effects and residuals."""
vals = [self._sigma2_effects, self._sigma2_eps, self._rho]
index = ["Effects", "Residual", "Percent due to Effects"]
return Series(vals, index=index, name="Variance Decomposition")
@property
def theta(self) -> DataFrame:
"""Values used in generalized demeaning."""
return self._theta
[docs]
def hausman(
self,
other: PanelResults,
include_constant: bool = False,
sigmamore: bool = False,
sigmaless: bool = False,
) -> HausmanTestResults:
r"""
Hausman specification test against results from a consistent model.
Parameters
----------
other : PanelResults
Results from a model that is consistent whether or not the null
hypothesis is true, typically a fixed effects (entity effects)
model estimated using the same observations, dependent variable,
regressors and weights as this model.
include_constant : bool, optional
Flag indicating whether to include the constant in the comparison.
The default is False.
sigmamore : bool, optional
Flag indicating whether to base both covariance estimates on the
error variance estimated by this model, which is efficient under
the null. Cannot be used with ``sigmaless``. The default is False.
sigmaless : bool, optional
Flag indicating whether to base both covariance estimates on the
error variance estimated by ``other``. Cannot be used with
``sigmamore``. The default is False.
Returns
-------
HausmanTestResults
A named tuple with the fields ``statistic``, which contains the
test statistic, p-value, distribution and null as a
WaldTestStatistic, and ``estimates``, a DataFrame with the
coefficients included in the test. An InvalidTestStatistic is
returned as the statistic when the statistic is negative or not
finite. The columns of ``estimates`` are ``b0`` (from ``other``),
``b1`` (from this model), their difference ``b0-b1`` and
``Std. Err.``, the standard error of the difference. The standard
error is NaN if the variance of the difference is negative.
Raises
------
TypeError
If ``other`` is not a panel results object, or if either model
was not estimated using the unadjusted covariance estimator.
ValueError
If ``sigmamore`` and ``sigmaless`` are both True, if the models
were not estimated using the same observations, dependent variable
and weights, or if the models do not have any coefficients in
common.
Notes
-----
The test statistic is
.. math::
H = (b_0 - b_1)^{\prime} (V_0 - V_1)^{-1} (b_0 - b_1)
where :math:`b_0` and :math:`V_0` are the coefficients and covariance
from ``other``, which is consistent under both the null and the
alternative, and :math:`b_1` and :math:`V_1` are from this model,
which is efficient under the null. The null hypothesis is that there
is no systematic difference in the coefficients, which for a fixed
effects model compared with a random effects model means that the
effects are uncorrelated with the regressors. The statistic is
asymptotically :math:`\chi^2_k`, where :math:`k` is the number of
coefficients compared.
Only coefficients found in both models are compared. The constant is
excluded unless ``include_constant`` is True.
The result is only meaningful when :math:`V_0 - V_1` is positive
definite, which is guaranteed in large samples if the null is true. If
it is not, a warning is issued and a generalized inverse is used. If
the resulting statistic is negative or not finite, the data do not
satisfy the assumptions of the test and an InvalidTestStatistic is
returned. This can happen, for example, if ``other`` is a pooled
model, since the unadjusted covariance of a pooled model ignores the
entity effects.
Both models must use the default unadjusted covariance estimator. The
statistic also requires that the models are estimated using the same
observations, the same dependent variable and the same weights, which
are checked. The regressors are not checked: only coefficients with
the same name in both models are compared.
Effects that are included in ``other`` but not in this model are not
tested separately. For example, if ``other`` includes time effects
and this model does not, the null hypothesis is that the regressors
are uncorrelated with the entity effects and with the time effects,
and the test can reject because of the time effects. To test only the
entity effects, include the time dummies as regressors in this model.
Only the coefficients found in both models are compared, so the
coefficients on the time dummies are not part of the test.
References
----------
Hausman, J. A. (1978). Specification tests in econometrics.
Econometrica, 46(6), 1251-1271.
Examples
--------
>>> from linearmodels import PanelOLS, RandomEffects
>>> from linearmodels.datasets import wage_panel
>>> data = wage_panel.load().set_index(["nr", "year"])
>>> y = data["lwage"]
>>> x = data[["hours"]]
>>> fe_res = PanelOLS(y, x, entity_effects=True).fit()
>>> re_res = RandomEffects(y, x).fit()
>>> results = re_res.hausman(fe_res)
>>> print(results) # doctest: +ELLIPSIS
Hausman specification test
H0: No systematic difference in coefficients between models
Statistic: ...
P-value: ...
Distributed: chi2(1)
...
The statistic and the estimates can be unpacked.
>>> test, estimates = results
"""
if not isinstance(other, PanelResults):
raise TypeError("other must be the results of a panel model.")
if sigmamore and sigmaless:
raise ValueError("sigmamore and sigmaless cannot both be True.")
if not (_has_unadjusted_cov(self) and _has_unadjusted_cov(other)):
raise TypeError(
"The Hausman test can only be used with models estimated using "
"the unadjusted covariance estimator."
)
_check_same_sample(self, other)
in_other = set(other.params.index)
common = [name for name in self.params.index if name in in_other]
if not include_constant:
constants: set[Any] = set()
for res in (self, other):
if res.model.has_constant:
loc = res.model._constant_index
assert isinstance(loc, int)
constants.add(res.model.exog.vars[loc])
common = [name for name in common if name not in constants]
if not common:
raise ValueError("The models do not have any coefficients in common.")
# The unadjusted covariance is s2 * inv(x'x), so using the error
# variance of the other model only requires rescaling.
cov0 = other.cov
cov1 = self.cov
if sigmamore:
cov0 = cov0 * (self.s2 / other.s2)
elif sigmaless:
cov1 = cov1 * (other.s2 / self.s2)
b0 = other.params[common]
b1 = self.params[common]
b_diff = b0 - b1
var_diff = cov0.loc[common, common] - cov1.loc[common, common]
diag = np.diag(var_diff)
std_errors = Series(np.sqrt(np.where(diag >= 0, diag, np.nan)), index=common)
estimates = DataFrame(
{"b0": b0, "b1": b1, "b0-b1": b_diff, "Std. Err.": std_errors}
)
diff = var_diff.to_numpy()
delta = b_diff.to_numpy()
name = "Hausman specification test"
if not (np.all(np.isfinite(diff)) and np.all(np.isfinite(delta))):
invalid = InvalidTestStatistic(
"The coefficients or covariances of the models are not finite, "
"so the statistic cannot be computed.",
name=name,
)
return HausmanTestResults(invalid, estimates)
try:
np.linalg.cholesky(diff)
positive_definite = True
except np.linalg.LinAlgError:
positive_definite = False
if positive_definite:
stat = float(delta @ np.linalg.solve(diff, delta))
else:
warnings.warn(
"Var(b0) - Var(b1) is not positive definite. A generalized "
"inverse is used to compute the statistic.",
UserWarning,
stacklevel=2,
)
stat = float(delta @ np.linalg.pinv(diff, hermitian=True) @ delta)
if not np.isfinite(stat) or stat < 0:
problem = "not finite" if not np.isfinite(stat) else "negative"
invalid = InvalidTestStatistic(
f"The statistic is {problem}, so the models do not meet the "
"assumptions of the Hausman test.",
name=name,
)
return HausmanTestResults(invalid, estimates)
null = "No systematic difference in coefficients between models"
wald = WaldTestStatistic(stat, null, len(common), name=name)
return HausmanTestResults(wald, estimates)
PanelModelResults = Union[PanelEffectsResults, PanelResults, RandomEffectsResults]
[docs]
class FamaMacBethResults(PanelResults):
"""
Results container for Fama MacBeth panel data models.
Parameters
----------
res : AttrDict
The results of the estimation, which the ``fit`` method of the model
constructs.
"""
def __init__(self, res: AttrDict):
super().__init__(res)
self._all_params = res.all_params
self._avg_r2 = res.avg_r2
self._avg_adj_r2 = res.avg_adj_r2
@property
def df_resid(self) -> int:
"""
Degrees of freedom of the t distribution used for inference.
Returns
-------
int
T - 1, where T is the number of cross-sectional regressions that
are averaged.
Notes
-----
The parameters are the average of T cross-sectional estimates, and
their covariance is estimated from the same T estimates. If
``debiased`` is True, p-values and confidence intervals use a t
distribution with T - 1 degrees of freedom, as in Fama and MacBeth
(1973). The periods whose cross-section cannot be estimated are not
counted. This is not nobs minus nvar, which is the residual degree of
freedom of the pooled regression and the one that ``f_statistic``, the
classical F-statistic of the pooled regression, uses. The joint test
``f_statistic_robust`` uses T - k denominator degrees of freedom, where
k is the number of parameters that it tests.
"""
return self._df_resid
@property
def f_statistic_robust(self) -> WaldTestStatistic:
r"""
Joint test of significance for non-constant regressors.
Returns
-------
WaldTestStatistic or InvalidTestStatistic
Statistic value, distribution and p-value. It is an
``InvalidTestStatistic`` if the model contains only a constant, or
if the covariance of the parameters is singular, which it is if the
number of periods that are averaged is not larger than the number
of tested parameters, or if the dependent variable is all zero.
Notes
-----
Implemented as a Wald test using the estimated parameter covariance,
which is the covariance of the average of the T cross-sectional
estimates that is selected by ``cov_type``.
.. math::
W = \hat{\beta}_{-}' \hat{\Sigma}_{-}^{-1} \hat{\beta}_{-}
where :math:`\hat{\beta}_{-}` does not include the model constant and
:math:`\hat{\Sigma}_{-}` is the estimated covariance of the
parameters, also excluding the constant. Let :math:`k` be the number of
non-constant parameters and :math:`T` the number of periods whose
cross-sectional regression is estimated, which is ``df_resid`` plus 1.
If ``debiased`` is True, which is the default, the statistic is
.. math::
F = \frac{T-k}{k(T-1)} W
and it is compared with an :math:`F_{k,T-k}` distribution. This is
the Hotelling T-squared test [1]_ of the hypothesis that the mean of
the :math:`T` estimates is zero. It is exact when the :math:`T`
estimates are independent draws from the same normal distribution and
the covariance is the standard covariance of their average
(``cov_type`` equal to "unadjusted", "homoskedastic", "robust" or
"heteroskedastic"), and the test then has the size that it claims.
With one tested parameter, :math:`F` is the square of the t-statistic
and the distribution is the square of the :math:`t_{T-1}`
distribution, so that the p-value is that of the parameter.
With the kernel covariance ("kernel") the test is only an
approximation. A kernel estimate of the long-run covariance from only
:math:`T` estimates is much less precise than the sample covariance, so
that the test can reject a true null hypothesis far too often even if
the estimates are independent, as can the t-test of a single
parameter, which is the case :math:`k=1`. In simulations of
independent normal estimates with the default bandwidth, the 5% test
rejected the null hypothesis in 21% of the samples with :math:`k=1` and
:math:`T=10`, in 37% with :math:`k=3` and :math:`T=10`, and in 23% with
:math:`k=3` and :math:`T=40`, where the test with the standard
covariance rejected in 5%.
The covariance is estimated from only :math:`T` estimates, which makes
:math:`W/k` stochastically larger than an :math:`F_{k,df}` variable
with :math:`df=T-1`, or with :math:`df=nobs-nvar` as in 7.0 and
earlier, when there are several tested parameters. A test that uses
those distributions rejects a true null hypothesis too often, and more
with more tested parameters and fewer periods. The factor and the
:math:`F_{k,T-k}` distribution correct this. In simulations of 20,000
samples of 40 entities in which the null hypothesis is true, the
tests of nominal size 5% with :math:`k=3` and :math:`T=10`, with
:math:`k=5` and :math:`T=10`, and with :math:`k=5` and :math:`T=20`
rejected the null hypothesis in 10%, 24% and 11% of the samples with the
:math:`F_{k,T-1}` distribution, in 20%, 41% and 18% with the
:math:`F_{k,nobs-nvar}` distribution of 7.0, and in 5% with the test
described here.
If ``debiased`` is False, the statistic is :math:`W` and the
distribution is :math:`\chi^2_k`. The general
:meth:`~linearmodels.panel.results.PanelResults.wald_test` of the
results also compares its statistic with a chi-squared distribution,
and does not apply this correction.
References
----------
.. [1] Hotelling, H. (1931). The generalization of Student's ratio.
The Annals of Mathematical Statistics, 2(3), 360-378.
"""
from linearmodels.panel.model import _hotelling_f # noqa: PLC0415
# The periods whose cross-section is estimated are df_resid + 1
return _hotelling_f(
self.params, self.cov, self._debiased, self._df_resid + 1, self._f_info
)
def _pesaran_cd_inapplicable(self) -> str | None:
return (
"The Pesaran CD test is not applicable to FamaMacBeth. The errors "
"of the model are the residuals of the period-by-period "
"cross-sectional regressions. The series implied by the averaged "
"coefficients contains the common, time-varying term "
"(beta_t - beta_bar)'x_it, so it is cross-sectionally dependent by "
"construction. Fama-MacBeth inference is already robust to "
"cross-sectional dependence."
)
@property
def all_params(self) -> DataFrame:
"""
The set of parameters estimated for each of the time periods.
Returns
-------
DataFrame
The parameters of each of the time periods, with shape (nobs,
nparam).
"""
return self._all_params
@property
def avg_rsquared(self) -> float:
"""
The average coefficient of determination.
This value contains the average of the individual rsquared values
across the cross-sectional regressions, one for each time period. An
R-squared value is only included in the average if a cross-section has
full rank and if the dependent variable of the cross-section varies,
since the coefficient of determination is NaN, up to rounding error, if
its total sum of squares is zero.
"""
return self._avg_r2
@property
def avg_adj_rsquared(self) -> float:
"""
The average coefficient of determination, adjusted for sample size.
This value contains the average of the individual adjusted rsquared
values across the cross-sectional regressions, one for each time
period. An R-squared value is only included in the average if a
cross-section has full rank, if the number of observations in a
cross-section is larger than the number of regressors, and if the
dependent variable of the cross-section varies, since the coefficient
of determination is NaN, up to rounding error, if its total sum of
squares is zero.
"""
return self._avg_adj_r2
[docs]
class PanelModelComparison(_ModelComparison):
"""
Comparison of multiple models.
Parameters
----------
results : list of results or dict of str to results
Set of results to compare. The results are those of the panel models
in the package. If a dict, the keys will be used as model names.
precision : {"tstats", "std_errors", "std-errors", "pvalues"}, optional
Estimator precision estimator to include in the comparison output. The
default is "tstats". The names are not case sensitive.
stars : bool, optional
Add stars based on the p-value of the coefficient where 1, 2 and
3-stars correspond to p-values of 10%, 5% and 1%, respectively. The
default is False.
Raises
------
TypeError
If a result is not the result of a panel model.
ValueError
If `precision` is not one of the supported values.
"""
_supported = (
PanelEffectsResults,
PanelResults,
RandomEffectsResults,
FamaMacBethResults,
)
def __init__(
self,
results: list[PanelModelResults] | dict[str, PanelModelResults],
*,
precision: str = "tstats",
stars: bool = False,
) -> None:
super().__init__(results, precision=precision, stars=stars)
@property
def rsquared_between(self) -> Series:
"""
Between coefficients of determination (R**2).
Returns
-------
Series
The between coefficient of determination of each model.
Notes
-----
The value of a model is NaN if its between coefficient of determination is not
defined, i.e., if the total sum of squares is zero, up to rounding error. See
``rsquared_between`` of the results of the models.
"""
return self._get_property("rsquared_between")
@property
def rsquared_within(self) -> Series:
"""
Within coefficients of determination (R**2).
Returns
-------
Series
The within coefficient of determination of each model.
Notes
-----
The value of a model is NaN if its within coefficient of determination is not
defined, i.e., if the total sum of squares is zero, up to rounding error. See
``rsquared_within`` of the results of the models.
"""
return self._get_property("rsquared_within")
@property
def rsquared_overall(self) -> Series:
"""
Overall coefficients of determination (R**2).
Returns
-------
Series
The overall coefficient of determination of each model.
Notes
-----
The value of a model is NaN if its overall coefficient of determination is not
defined, i.e., if the total sum of squares is zero, up to rounding error. See
``rsquared_overall`` of the results of the models.
"""
return self._get_property("rsquared_overall")
@property
def estimator_method(self) -> Series:
"""Estimation methods."""
return self._get_property("name")
@property
def cov_estimator(self) -> Series:
"""Covariance estimator descriptions."""
return self._get_property("_cov_type")
@property
def summary(self) -> Summary:
"""
Model estimation summary.
Returns
-------
Summary
Summary table of model estimation results.
Notes
-----
Supports export to csv, html and latex using the methods ``summary.as_csv()``,
``summary.as_html()`` and ``summary.as_latex()``.
"""
smry = Summary()
models = list(self._results.keys())
title = "Model Comparison"
stubs = [
"Dep. Variable",
"Estimator",
"No. Observations",
"Cov. Est.",
"R-squared",
"R-Squared (Within)",
"R-Squared (Between)",
"R-Squared (Overall)",
"F-statistic",
"P-value (F-stat)",
]
dep_name = {}
for key in self._results:
dep_name[key] = self._results[key].model.dependent.vars[0]
vals = concat(
[
Series(dep_name),
self.estimator_method,
self.nobs,
self.cov_estimator,
self.rsquared,
self.rsquared_within,
self.rsquared_between,
self.rsquared_overall,
self.f_statistic,
],
axis=1,
)
vals_lst = [list(v) for v in vals.T.values]
vals_lst[2] = [str(v) for v in vals_lst[2]]
for i in range(4, len(vals_lst)):
f = _str
if i == 9:
f = pval_format
vals_lst[i] = [f(v) for v in vals_lst[i]]
params = self.params
precision = getattr(self, self._precision)
pvalues = np.asarray(self.pvalues)
params_fmt = []
params_stub: list[str] = []
for i in range(len(params)):
formatted_and_starred = []
for v, pv in zip(params.values[i], pvalues[i], strict=False):
formatted_and_starred.append(add_star(_str(v), pv, self._stars))
params_fmt.append(formatted_and_starred)
precision_fmt = []
for v in precision.values[i]:
v_str = _str(v)
v_str = f"({v_str})" if v_str.strip() else v_str
precision_fmt.append(v_str)
params_fmt.append(precision_fmt)
params_stub.append(str(params.index[i]))
params_stub.append(" ")
if params_fmt:
# None of the models has parameters if they only have effects
vals_lst = table_concat((vals_lst, params_fmt))
stubs = stub_concat((stubs, params_stub))
all_effects = []
for key in self._results:
res = self._results[key]
effects = getattr(res, "included_effects", [])
all_effects.append(effects)
neffect = max(map(len, all_effects))
effects = []
effects_stub = ["Effects"]
for i in range(neffect):
if i > 0:
effects_stub.append("")
row = []
for j in range(len(self._results)):
effect = all_effects[j]
if len(effect) > i:
row.append(effect[i])
else:
row.append("")
effects.append(row)
if effects:
vals_lst = table_concat((vals_lst, effects))
stubs = stub_concat((stubs, effects_stub))
txt_fmt = default_txt_fmt.copy()
txt_fmt["data_aligns"] = "r"
txt_fmt["header_align"] = "r"
table = SimpleTable(
vals_lst, headers=models, title=title, stubs=stubs, txt_fmt=txt_fmt
)
smry.tables.append(table)
prec_type = self._PRECISION_TYPES[self._precision]
smry.add_extra_txt([f"{prec_type} reported in parentheses"])
return smry
[docs]
def compare(
results: list[PanelModelResults] | dict[str, PanelModelResults],
*,
precision: str = "tstats",
stars: bool = False,
) -> PanelModelComparison:
"""
Compare the results of multiple models.
Parameters
----------
results : list of results or dict of str to results
Set of results to compare. The results are those of the panel models
in the package. If a dict, the keys will be used as model names.
precision : {"tstats", "std_errors", "std-errors", "pvalues"}, optional
Estimator precision estimator to include in the comparison output. The
default is "tstats". The names are not case sensitive.
stars : bool, optional
Add stars based on the p-value of the coefficient where 1, 2 and
3-stars correspond to p-values of 10%, 5% and 1%, respectively. The
default is False.
Returns
-------
PanelModelComparison
The model comparison object.
Raises
------
TypeError
If a result is not the result of a panel model.
ValueError
If `precision` is not one of the supported values.
"""
return PanelModelComparison(results, precision=precision, stars=stars)