groupedpaneldatamodels.GroupedInteractiveFixedEffects

Class for estimating grouped interactive fixed effects in panel data.

Implements the estimators by Ando and Bai (2016) and Su and Ju (2018).

This class extends the grouped fixed effects framework by allowing for interactive effects (latent factors and loadings) that vary across groups. It is suitable for capturing unobserved heterogeneity that follows a low-rank factor structure within each group.

It supports both heterogeneous and homogeneous slope coefficients (only for Ando & Bai, 2016).

Example usage:

>>> model = GroupedInteractiveFixedEffects(y, x, G=3)
>>> model.fit()
>>> model.summary()

After fitting, the model provides access to estimated coefficients, group assignments, latent factors, and residual diagnostics.

Initialize the GroupedInteractiveFixedEffects model for panel data analysis.

This model estimates grouped interactive fixed effects using either the Ando and Bai (2016) or the Su and Ju (2018) estimators. It allows for heterogeneity in slope coefficients across groups and supports group-specific factor structures to model unobserved interactive effects.

Parameters:

dependent (ArrayLike) – A 3D array representing the dependent variable with shape (N, T, 1), where N is the number of individuals and T is the number of time periods.
exog (ArrayLike) – A 3D array representing the exogenous variables with shape (N, T, K), where K is the number of regressors.
G (int) – The number of latent groups to estimate.
use_bootstrap (bool, optional) – Whether to compute bootstrap-based standard errors. Default is False.
model (Literal["ando_bai", "su_ju"], optional) – The estimator to use. Choose between “ando_bai” (default) or “su_ju”.
GF (ArrayLike, optional) – An array specifying the number of latent factors for each group. If not provided, a single factor is assumed for each group.
R (int, optional) – The total number of latent factors in the Su and Ju model. If not specified, defaults to G.
heterogeneous_beta (bool, optional) – Whether to allow slope coefficients to vary across groups. Default is True.
**kwargs (dict) –
Additional configuration arguments, such as:
- hide_progressbar (bool): Whether to suppress progress bars.
- disable_analytical_se (bool): Whether to skip analytical SE calculation.

property IC: dict

Returns the information criteria of the model

Returns:: The information criteria of the model, or None if not available
Return type:: dict | None

property K: int

Returns the number of exogenous variables

Returns:: The number of exogenous variables
Return type:: int

property N: int

Returns the number of observations

Returns:: The number of observations
Return type:: int

property T: int

Returns the number of time periods

Returns:: The number of time periods
Return type:: int

fit(**kwargs)[source]

Fit the GroupedInteractiveFixedEffects model to the data.

This method estimates grouped interactive fixed effects using the selected estimator: - “ando_bai” (Ando & Bai, 2016): Supports both homogeneous and heterogeneous slope coefficients across groups. - “su_ju” (Su & Ju, 2018): Supports only heterogeneous slopes and models a shared factor structure across units.

It estimates group assignments, coefficients, and latent interactive components, and computes information criteria and standard errors.

Parameters:

n_boot (int, optional) – Number of bootstrap replications to compute standard errors. Default is 50.
boot_n_jobs (int, optional) – Number of parallel jobs for the bootstrap procedure. Default is -1 (use all processors).
kwargs (dict, optional) – Additional arguments passed to the underlying estimator routines.

Returns:

self – The fitted model instance.

Return type:

GroupedInteractiveFixedEffects

Raises:

ValueError – If the selected model is not one of “ando_bai” or “su_ju”, or if homogeneous beta is requested for “su_ju”, which is not supported.

get_confidence_intervals(confidence_level: float = 0.95, conf_type: Literal['auto', 'bootstrap', 'analytical'] = 'auto') → dict

Returns the confidence intervals for the parameters, prefers bootstrap if available, otherwise analytical

Parameters:

confidence_level (float, optional, the confidence level for the intervals, default is 0.95)
conf_type (str, optional, the type of confidence intervals to compute, can be 'auto', 'bootstrap', or 'analytical', default is 'auto')

Returns:

The confidence intervals for the parameters

Return type:

dict

p_values() → dict

Returns the p-values of the parameters

Returns:: The p-values of the parameters, or None if not available
Return type:: dict | None

property params: dict

Returns the parameters of the model

Returns:: The parameters of the model
Return type:: dict

property params_analytical_standard_errors: dict

Returns the analytical standard errors of the parameters

Returns:: The analytical standard errors of the parameters, or None if not available
Return type:: dict | None

property params_bootstrap_standard_errors: dict

Returns the bootstrap standard errors of the parameters

Returns:: The bootstrap standard errors of the parameters, or None if not available
Return type:: dict | None

property params_standard_errors: dict

Returns the standard errors of the parameters

Returns:: The standard errors of the parameters, or None if not available
Return type:: dict | None

Predicts the dependent variable based on the parameters and exogenous variables This function is a placeholder and should be implemented in subclasses.

Parameters:

params (array_like) – The parameters
exog (array_like) – The exogenous variables

Returns:

The predicted dependent variable

Return type:

array_like

property resid: ndarray

Returns the residuals of the model

Returns:: The residuals of the model
Return type:: ArrayLike
Raises:: ValueError – If the model has not been fitted yet or residuals are not available for this model.

summary(confidence_level: float = 0.95, standard_errors: Literal['auto', 'bootstrap', 'analytical'] = 'auto')

Generates a summary of the model, including information about the model type, observations, exogenous variables, groups, fit time, fit duration, and standard errors.

Parameters:

confidence_level (float, optional) – The preferred confidence lebel . Defaults to 0.95.
standard_errors (Literal["auto", "bootstrap", "analytical"], optional) – Which type of errors to prefer. Defaults to “auto”.
"auto" (If)
available (it will use bootstrap if)
NotImplementedError. (otherwise analytical standard errors. All other values will raise a)
yet. (As this is not implemented)

Raises:

ValueError – Model has not been fitted yet
NotImplementedError – Standard errors type other than ‘auto’ is not implemented yet, you can manually view them using model.params_bootstrap_standard_errors or `model.params_analytical_standard_errors`_

Returns:

A summary object containing the model information, parameters, and standard errors.

Return type:

Summary

property t_values: dict

Returns the t-values of the parameters

Returns:: The t-values of the parameters, or None if not available
Return type:: dict | None

to_dict(store_bootstrap_iterations=False) → dict[str, Any]

Converts the model to a dictionary, which can be useful for serialization or inspection.

Parameters:

store_bootstrap_iterations (bool, optional, whether to store the bootstrap iterations in the dictionary, default is False, requires a lot of memory)
True (If set to)
dictionary. (the bootstrap estimations will be included in the)

Returns:

The model as a dictionary

Return type:

dict