BaseUnitAverager

class unit_averaging.averager.BaseUnitAverager(focus_function, ind_estimates)

Bases: ABC

Base class for unit averaging methods.

This abstract base class encapsulates the common behavior for unit averaging methods. It provides the basic structure for fitting weights and computing averages, and is designed to be subclassed for specific unit averaging strategies.

Subclasses must implement the _compute_weights() method to define how the weights are computed for the specific averaging strategy.

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 (array rows or dict 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 not an array, keys defaults to numeric indices (0, 1, 2, …).

• weights (np.ndarray) – The computed weights for each unit. Initialized as None, computed by calling fit()

• estimate (float) – The computed unit averaging estimate. Initialized as None.

• 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 BaseUnitAverager, InlineFocusFunction
>>> import numpy as np
>>> # Custom averager that uses equal weights
>>> class CustomUnitAverager(BaseUnitAverager):
...     def _compute_weights(self):
...         self.weights = (
...             np.ones(len(self.ind_estimates)) / len(self.ind_estimates)
...            )
>>> # Using the averager in practice
>>> focus_fun = lambda x: (x[0])**2
>>> focus_grad = lambda x: np.array([2*x[0], 0])
>>> focus_function = InlineFocusFunction(focus_fun, focus_grad)
>>> ind_estimates = [np.array([4, 2]), np.array([3, 4])]
>>> averager = CustomUnitAverager(focus_function, ind_estimates)
>>> averager.fit(target_id=0)
>>> print(averager.weights)  # [0.5, 0.5]
>>> print(averager.estimate) # 12.5

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.