groupedpaneldatamodels.GroupedFixedEffects

class groupedpaneldatamodels.GroupedFixedEffects(dependent: Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes], exog: Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes], G: int, use_bootstrap: bool = False, model: Literal['bonhomme_manresa', 'su_shi_phillips'] = 'bonhomme_manresa', heterogeneous_beta: bool = True, entity_effects: bool = False, kappa: float = 0.1, **kwargs)[source]

Class for estimating grouped fixed effects in panel data models.

Supports both Bonhomme and Manresa (2015) and Su, Shi, and Phillips (2016) estimators.

This class clusters units into a specified number of latent groups and estimates either: - Group-specific slope coefficients (heterogeneous), or - A shared slope coefficient (homogeneous)

depending on the specified configuration. It also optionally includes individual (entity-specific) fixed effects and supports bootstrap inference.

Typical usage:
>>> model = GroupedFixedEffects(y, x, G=3)
>>> model.fit(max_iter=100)
>>> model.summary()

Attributes such as coefficients, group assignments, and residuals are made available after fitting.

Initialize the GroupedFixedEffects model for panel data analysis.

This class estimates grouped fixed effects using either the Bonhomme and Manresa (2015) or Su, Shi, and Phillips (2016) estimators. The model is designed for settings where units can be grouped based on similarities in their fixed effects or slope coefficients.

Parameters:

  • dependent (np.ndarray) – A 3D array of Y, structured as (N, T, 1), where N is the number of individuals, T is the number of time periods.

  • exog (np.ndarray) – A 3D array of X, structured as (N, T, K), containing the exogenous regressors.

  • G (int) – The (maximum) number of latent groups to estimate.

  • use_bootstrap (bool, optional) – Whether or not to estimate the standard errors using the Bootstrap method. Defaults to False.

  • model (Literal["bonhomme_manresa", "su_shi_phillips"], optional) – Which estimator to use: “bonhomme_manresa” (default) or “su_shi_phillips”.

  • heterogeneous_beta (bool, optional) – Whether the coefficients β should be allowed to differ across groups. If False, they are homogeneous. Defaults to True.

  • entity_effects (bool, optional) – Whether to include individual (entity-specific) fixed effects in the estimation. Recommended for “su_shi_phillips”. Defaults to False.

  • kappa (float, optional) – Regularization strength for SCAD penalty. Default is 0.1.

Raises:

ValueError – If the specified model is not supported.

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 GroupedFixedEffects model to the data.

This method estimates grouped fixed effects based on the selected model type: - “bonhomme_manresa” implements the algorithm by Bonhomme and Manresa (2015). - “su_shi_phillips” implements the algorithm by Su, Shi, and Phillips (2016).

Parameters:

  • n_boot (int, optional) – Number of bootstrap replications to compute standard errors. Default is 50.

  • model='bonhomme_manresa' (For) –

    max_iterint, optional

    Maximum number of optimization iterations. Default is 10000.

    tolfloat, optional

    Convergence tolerance for optimization. Default is 1e-6.

    gfe_iterationsint, optional

    Number of different starting values for the grouped fixed effects algorithm. Default is 100.

    enable_vnsbool, optional

    Whether to use the Variable Neighborhood Search (VNS) algorithm. Default is False. (Not recommended when heterogeneous_beta=True due to computational cost.)

  • model='su_shi_phillips' (For) –

    max_iterint, optional

    Maximum number of optimization iterations. Default is 1000.

    tolfloat, optional

    Convergence tolerance for optimization. Default is 1e-6.

    only_bfgsbool, optional

    Whether to use only the L-BFGS optimizer. If False, alternates between L-BFGS and Nelder-Mead. Default is True.

Returns:

self – The fitted model instance.

Return type:

GroupedFixedEffects

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

predict(params: Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes], *, exog: Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes] | None = None, data: Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes] | None = None) → Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes]

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