MeanGroupUnitAverager

class unit_averaging.averager.MeanGroupUnitAverager(focus_function, ind_estimates)

Bases: BaseUnitAverager

Unit averaging scheme that assigns equal weights to all units.

This class implements a unit averaging scheme where equal weights are assigned to all units — the mean group estimator. The MG approach typically is a good estimator of the expected value of a parameter in a heterogeneous setting.

Parameters:

• focus_function (BaseFocusFunction) – Focus function expressing the transformation of interest.

• ind_estimates (np.ndarray | list | dict[str | int, np.ndarray | list]) – Individual unit estimates. Can be a list, numpy array, or dictionary. Each unit-specific estimate should be a NumPy array or a list. The first dimension of ind_estimates indexes units (rows or dictionary entries).

Attributes:

• ind_estimates (np.ndarray) – Array of individual unit estimates.

• keys (np.ndarray) – Array of keys corresponding to the units. The individual estimates are converted to numpy arrays internally. If ind_estimates is a dictionary, the keys are preserved in the keys attribute. If ind_estimates is a list or array, keys defaults to numeric indices (0, 1, 2, …).

• weights (np.ndarray) – The computed weights for each unit. For this scheme, all weights are equal and sum to 1.

• estimate (float) – The computed unit averaging estimate. Here a simple average of all unit estimates.

• focus_function (BaseFocusFunction) – Focus function expressing the transformation of interest.

• target_id (int | str) – The ID of the target unit. Initialized as None, set by calling fit().

Example

>>> from unit_averaging import MeanGroupUnitAverager, InlineFocusFunction
>>> import numpy as np
>>> # Define a focus function
>>> focus_function = InlineFocusFunction(
...     lambda x: x[0],
...     lambda x: np.array([1, 0])
... )
>>> # Define individual unit estimates
>>> ind_estimates = {
...     "unit1": np.array([5, 6]),
...     "unit2": np.array([7, 8]),
...     "unit3": np.array([9, 10])
... }
>>> # Create a MeanGroupUnitAverager instance
>>> averager = MeanGroupUnitAverager(focus_function, ind_estimates)
>>> # Fit the averager to the target unit
>>> averager.fit(target_id="unit1")
>>> print(averager.weights)   # [0.33333333 0.33333333 0.33333333]
>>> print(averager.estimate)  # 7.0

Methods

average(focus_function=None)

Perform unit averaging with the fitted weights.

This method computes the unit averaging estimate using the fitted weights. It can accept a different focus function and reuse the fitted weights.

Parameters:

focus_function (BaseFocusFunction | None) – Focus function to use in computing the averaging estimator. Expresses the parameter of interest. If None, defaults to the focus function used in fitting.

Returns:

The unit averaging estimate.

Return type:

float

Raises:

TypeError – If weights have not been fitted yet by calling fit()

fit(target_id)

Compute the unit averaging weights and the averaging estimator.

Parameters:

target_id (int | str) – ID of the target unit. This is specified in terms of the keys attribute, which are either numeric indices (if ind_estimates was an array or list) or dictionary keys (if ind_estimates was a dictionary)

Raises:

ValueError – If the target unit is not found in the keys.