RE

RE estimates a random effects (Swamy-Arora GLS) panel regression. It shares the general API shape with OLS (data/y/x/options constructor, .fit()), but — like FE — entity is a required argument, since the model has no meaning without a panel structure. Unlike FE, RE keeps an intercept (REResults.param_names[0] is always "const") and supports entity-direction random effects only; two-way RE is not implemented.

Standard error types

REOptions.cov_type defaults to "cluster" (clustered on entity), the same departure from OLS's "classical" default that FE makes, and for the same reason. Supported values are "classical", "hc1", "hc2", "hc3", "cluster", and "dk" — "hc0" is not supported. "dk" is the same Driscoll-Kraay panel estimator FE uses, and it requires REOptions.dk_time, the column that defines the time periods (the same option as FEOptions.dk_time). The bandwidth actually used is reported as REResults.dk_bandwidth_used (None unless cov_type="dk"). RE has no time option, since it has no two-way structure.

The small-sample corrections and the degrees of freedom of the t tests follow the same Stata/R convention as FE (fixest's ssc() defaults; plm::vcovHC(type = "sss") for "cluster"): "cluster" scales by G/(G-1) · (n-1)/(n-K) and uses G - 1 degrees of freedom, "dk" uses T/(T-1) with T = number of time periods in place of G and T - 1 degrees of freedom, and the other types use df_resid. These differ from linearmodels, which does not apply the G/(G-1) factor. The F statistic is the exception: it does not depend on cov_type, so f_df_denom is always df_resid even when stat_df is G - 1 or T - 1. See Inference conventions for the full table.

The Hausman test

REResults exposes hausman_statistic, hausman_p_value, and hausman_df directly as properties — computed automatically inside fit(), rather than requiring a separate call (unlike FE's fixed_effects()).

The test is the regression-based (auxiliary regression) version (Wooldridge 2010, section 10.7.3; equivalent to R's plm::phtest(method = "aux", effect = "individual")): the quasi-demeaned y is regressed on a constant, the quasi-demeaned regressors and the within-transformed regressors, and the within-transformed coefficients are tested jointly for zero. Its properties:

• The statistic is always non-negative (no indefinite variance-difference problem).
• The comparison is always against one-way (entity) fixed effects, the same structure as RE itself. REOptions.dk_time is used only as the Driscoll-Kraay time periods (cov_type="dk") and does not affect the test; specifying it with any other cov_type raises ValidationError.
• The Wald test uses the covariance matching REOptions.cov_type (classical, hc1–hc3, cluster, or Driscoll-Kraay dk). With the default cov_type="cluster" this is the cluster-robust Hausman test; use cov_type="classical" for the classical version, which assumes RE is fully efficient under the null. The auxiliary regression uses the same Stata/R-style small-sample corrections as RE's own standard errors.
• All three are None only when there are no slope coefficients to compare. If the auxiliary regression cannot be computed (rank-deficient design, or a robust covariance that is structurally singular such as cov_type="cluster" with no more clusters than the 2k auxiliary slopes, or "dk" with too few periods), fit() raises ValidationError / ComputationError instead, like a multicollinear design matrix. Use cov_type="classical" or more clusters in that case. See REResults's docstring.

Panel R² and df_resid

Like FE, REResults reports r_squared_within/r_squared_between/r_squared_overall instead of a single R². df_resid follows the plain OLS formula n - k, not FE's n - n_entities - k — RE is a GLS transform and does not consume entity-dummy degrees of freedom the way FE's within transformation does.

econometricsmodels.RE(data, y, x, entity, options=None)

Random effects (Swamy-Arora GLS) panel regression estimator.

Unlike FE, RE has an intercept and supports entity-direction random effects only (docs/spec/panel-common.md section 7.6, two-way RE is out of scope for v1).

Parameters:

Name	Type	Description	Default
data	DataFrame	A polars DataFrame containing the dependent variable, independent variables, entity identifier, and (if specified) time/cluster columns.	required
y	str	Column name of the dependent variable.	required
x	list[str]	List of column names of the independent variables. Must contain at least one column name.	required
entity	str	Column name of the entity (individual/panel unit) identifier.	required
options	REOptions | None	Estimation options. Defaults to REOptions() (cov_type="cluster" on entity, confidence_level=0.95) when omitted.	None

Examples:

>>> import polars as pl
>>> from econometricsmodels import RE
>>> df = pl.DataFrame(
...     {
...         "y": [1.0, 2.0, 3.0, 4.0, 5.0, 6.0],
...         "x1": [2.0, 4.0, 1.0, 5.0, 3.0, 6.0],
...         "id": ["a", "a", "b", "b", "c", "c"],
...     }
... )
>>> result = RE(df, y="y", x=["x1"], entity="id").fit()
>>> result.params["x1"]

fit()

Estimate the RE model.

Returns:

Type	Description
REResults	The estimation results.

Raises:

Type	Description
TypeError	An argument has the wrong type (for example x is a string instead of a list of column names). A builtin exception, not a ValidationError.
ValidationError	The input or options are invalid (x is empty, a column is missing, contains missing values or NaN/infinity, y/x/entity overlap, dk_time equal to y or entity, insufficient observations, confidence_level out of range, an unknown cov_type (or cov_type="hc0", unsupported for RE), dk_time specified with a cov_type other than "dk", a singleton entity group (raised by the internal one-way FE regression that RE's σ_ε² estimation delegates to), a cov_type="dk" request with dk_time unset, or cov_type="dk" with no more unique time periods than regressors: the Driscoll-Kraay covariance has rank at most T-1, so the Hausman test cannot be computed). A subclass of ValueError.
ComputationError	A problem was detected during computation (e.g. a singular quasi-demeaned design matrix). A subclass of RuntimeError.

econometricsmodels.REOptions

Estimation options for RE (random effects panel regression).

See docs/spec/panel-common.md for the rationale behind each field's meaning and default value.

cluster property

Column name to use as the cluster group key when cov_type="cluster". When None, the entity argument's column is used automatically. Specifying it with any other cov_type raises ValidationError.

confidence_level property

Confidence level for confidence intervals, in the range (0, 1). Defaults to 0.95 (a 95% confidence interval).

cov_type property

Standard error type: one of "classical", "hc1", "hc2", "hc3", "cluster", "dk". Case-insensitive. Unlike OLS/WLS/IV, "hc0" is not supported (no reference implementation offers it for panel/RE regressions; see the module docstring).

dk_bandwidth property

Bandwidth for Driscoll-Kraay HAC when cov_type="dk". When None, computed automatically via floor(4*(t/100)^(2/9)) (t = number of unique time periods). Specifying it with any other cov_type raises ValidationError.

dk_time property

Column name that defines the time periods of the Driscoll-Kraay HAC when cov_type="dk" (required there, as in FEOptions.dk_time). Specifying it with any other cov_type raises ValidationError. It may not be the same column as y or entity (ValidationError), but may be one of the regressors. It does not affect the Hausman test, which always compares against one-way FE. The periods are ordered by the values of the column: numerically for integers and floats, chronologically for Date and Datetime, in the order of the categories for Enum, and alphabetically for strings and Categorical.

econometricsmodels.REResults(raw)

RE estimation results.

Array-valued properties (params, std_errors, etc.) are exposed as dictionaries keyed by coefficient name (for O(1) lookup of a single parameter). Use coef_table() for a row-oriented listing. param_names[0] is always "const" (unlike FE, RE has an intercept; see engine::panel::re's module docstring on the Rust side for why the quasi-demeaned constant column is named this way).

The Hausman test (hausman_statistic/hausman_p_value/ hausman_df) is computed automatically inside fit() and exposed directly as properties here, rather than as a separate method like FE's fixed_effects() (panel-common.md section 2.4). It is the regression-based (auxiliary regression) version (Wooldridge 2010, section 10.7.3; equivalent to plm::phtest(method = "aux", effect = "individual")), always comparing against one-way (entity) fixed effects — the same structure as RE itself — regardless of REOptions.dk_time. The Wald test's covariance follows cov_type (the default "cluster" gives the cluster-robust Hausman test; "classical" gives the classical version). The auxiliary regression uses OLS-style small-sample corrections, which differ from the RE standard errors'. All three are None only when there are no slope coefficients to compare. If the auxiliary regression cannot be computed (rank-deficient design, or a structurally singular robust covariance such as too few clusters or periods for the auxiliary slopes), fit() raises ValidationError/ComputationError. A failure in RE's own internal one-way FE call (used to estimate σ_ε²) makes fit() itself raise instead (e.g. a singleton entity, or a regressor with zero variance after the one-way within-transformation); see RE.fit()'s docstring.

Parameters:

Name	Type	Description	Default
raw	REResult	The estimation result object returned by _lib.fit_re (_lib.REResult).	required

Note

Users normally do not construct this directly; it is returned by RE.fit().

aic property

Akaike Information Criterion (AIC).

bic property

Bayesian Information Criterion (BIC).

conf_int property

Coefficient name to confidence interval (lower, upper).

cov_type property

Standard error type actually used (normalized to lowercase).

dep_var_name property

Column name of the dependent variable.

df_model property

Model degrees of freedom (k, including the intercept).

df_resid property

Residual degrees of freedom (n - k, unlike FE's n - n_entities - k; RE is a GLS transform that does not consume entity-dummy degrees of freedom).

dk_bandwidth_used property

Driscoll-Kraay bandwidth actually used: the explicit dk_bandwidth if given, otherwise the value chosen automatically, floor(4 * (t / 100) ** (2 / 9)) where t is the number of unique time periods in REOptions.dk_time. None unless cov_type="dk".

f_df_denom property

Denominator degrees of freedom of f_statistic (None when it is NaN). Follows cov_type like the t-tests (G - 1 for cov_type="cluster", T - 1 for "dk", df_resid otherwise), so it equals stat_df whenever f_statistic is not NaN. Use this to recompute the p-value from f_statistic.

f_df_num property

Numerator degrees of freedom of f_statistic (None when it is NaN, i.e. there are no slope coefficients).

f_p_value property

P-value of the F-statistic.

f_statistic property

F-statistic for the joint significance of the slope coefficients, excluding the intercept (classical F-test when cov_type="classical", a robust Wald test otherwise; the degrees of freedom follow cov_type, see f_df_denom). NaN when there are no slope coefficients (df_model == 1).

hausman_df property

Degrees of freedom of the Hausman test (number of compared slope coefficients, i.e. df_model - 1). None under the same conditions as hausman_statistic.

hausman_p_value property

P-value of hausman_statistic (upper-tail chi-squared probability). None under the same conditions as hausman_statistic.

hausman_statistic property

Regression-based Hausman test statistic (chi-squared version, k × F of the Wald test that the k within-transformed slope regressors are jointly zero in the auxiliary regression of the quasi-demeaned y on the quasi-demeaned regressors and the within-transformed regressors). Always non-negative. The comparison is always against one-way FE. The Wald test's covariance follows cov_type (default "cluster" gives the cluster-robust Hausman test; "classical" gives the classical version). The auxiliary regression uses OLS-style small-sample corrections, unlike the RE standard errors. For unbalanced panels the auxiliary regression's constant is left untransformed, as in plm::phtest. None if the auxiliary regression is unavailable (see the class docstring).

log_likelihood property

Log-likelihood.

n_entities property

Number of panel entities.

n_obs property

Number of observations.

p_values property

Coefficient name to two-sided p-value.

param_names property

List of coefficient names (param_names[0] is always "const").

params property

Coefficient name to coefficient value.

r_squared_between property

Between R² (based on entity-mean variables).

r_squared_overall property

Overall R² (based on the untransformed variables).

r_squared_within property

Within R² (based on the entity-demeaned variables, θ=1; unrelated to RE's own Swamy-Arora quasi-demeaning).

residuals property

Quasi-demeaned residuals (in observation order).

stat_df property

Degrees of freedom of the t distribution behind test_stats, or None when stat_dist is "normal". May differ from df_resid (cluster-robust inference uses G - 1, Driscoll-Kraay T - 1), so use this to recompute p-values from test_stats.

stat_dist property

Distribution of test_stats: "t" (t-statistics) or "normal" (z-statistics).

std_errors property

Coefficient name to standard error.

test_stats property

Coefficient name to test statistic (t-statistic; see stat_dist).

coef_table()

Row-oriented summary table of the coefficients.

Shaped to be usable almost as-is in a REST API response (same policy as OLSResults.coef_table()). Returned as list[dict] rather than a polars DataFrame, per the project's policy of not using DataFrames for the coefficient table itself.

Returns:

Type	Description
list[dict[str, float | str]]	A list of dictionaries, one per coefficient. Keys are
list[dict[str, float | str]]	param, coef, std_err, test_stat, p_value,
list[dict[str, float | str]]	conf_lower, conf_upper.