BaseFocusFunction

class unit_averaging.focus_function.BaseFocusFunction

Bases: ABC

Abstract base class to encapsulate a focus function and its gradient.

This class provides a framework for implementing focus functions and their gradients. A focus function represents a transformation of interest applied to parameter estimates. Subclasses must implement both the focus_function and gradient methods to define the specific transformation and its derivative.

The focus function concept is central to unit averaging methods, particularly the optimal approach which relies on the function and its derivative.

Attributes:

None (abstract class)

Examples

>>> from unit_averaging import BaseFocusFunction
>>> import numpy as np
>>> class LinearFocusFunction(BaseFocusFunction):
...     def focus_function(self, ind_estimate):
...         return ind_estimate[0] + ind_estimate[1]
...
...     def gradient(self, ind_estimate):
...         return np.array([1.0, 1.0])
>>> # Create an instance of the custom focus function
>>> focus_func = LinearFocusFunction()
>>> # Apply the focus function to an estimate
>>> estimate = np.array([2.0, 3.0])
>>> result = focus_func.focus_function(estimate)
>>> print(result)  # Output: 5.0
>>> # Get the gradient at the estimate
>>> grad = focus_func.gradient(estimate)
>>> print(grad)  # Output: [1. 1.]

Methods

abstractmethod focus_function(ind_estimate)

Compute the focus function for a given estimate.

This method applies the focus function transformation to an individual estimate. The focus function defines the parameter of interest that the unit averaging process aims to estimate.

Parameters:

ind_estimate (float | np.floating[Any] | np.ndarray) – Individual specific estimate. Can be a scalar or an array-like object.

Returns:

Scalar result of applying the focus function to the input estimate.

Return type:

float | np.floating[Any]

abstractmethod gradient(ind_estimate)

Compute the gradient of the focus function for a given estimate.

This method calculates the gradient (vector of first derivatives) of the focus function with respect to the input estimate. The gradient is used in the optimization process to determine the optimal weights for unit averaging.

Parameters:

ind_estimate (float | np.floating[Any] | np.ndarray) – Individual specific estimate. Can be a scalar or an array-like object.

Returns:

Vector of first derivatives of the focus function with respect to the input estimate. The shape of the array should match the shape of the input estimate.

Return type:

np.ndarray