Add 'list_fairness_functions' util.

declearn/fairness/__init__.py

@@ -88,7 +88,7 @@ References
     Improving Fairness via Federated Learning.
     https://arxiv.org/abs/2110.15545
 - [4]
-    Eszzeldin et al. (2021).
+    Ezzeldin et al. (2021).
     FairFed: Enabling Group Fairness in Federated Learning
     https://arxiv.org/abs/2110.00857
 """

declearn/fairness/core/__init__.py

@@ -40,6 +40,11 @@ Concrete implementations of various fairness functions:
     Equalized Odds group-fairness function.
 
 Abstraction and generic constructor may be found in [declearn.fairness.api][].
+An additional util may be used to list available functions, either declared
+here or by third-party and end-user code:
+
+* [list_fairness_functions][declearn.fairness.core.list_fairness_functions]:
+    Return a mapping of registered FairnessFunction subclasses.
 """
 
 from ._functions import (
@@ -47,5 +52,6 @@ from ._functions import (
     DemographicParityFunction,
     EqualityOfOpportunityFunction,
     EqualizedOddsFunction,
+    list_fairness_functions,
 )
 from ._inmemory import FairnessInMemoryDataset

declearn/fairness/core/_functions.py

@@ -17,20 +17,47 @@
 
 """Concrete implementations of various group-fairness functions."""
 
-from typing import Any, Dict, List, Tuple, Union
+from typing import Any, Dict, List, Tuple, Type, Union
 
 import numpy as np
 
 from declearn.fairness.api import FairnessFunction
+from declearn.utils import access_types_mapping
 
 __all__ = (
     "AccuracyParityFunction",
     "DemographicParityFunction",
     "EqualityOfOpportunityFunction",
     "EqualizedOddsFunction",
+    "list_fairness_functions",
 )
 
 
+def list_fairness_functions() -> Dict[str, Type[FairnessFunction]]:
+    """Return a mapping of registered FairnessFunction subclasses.
+
+    This function aims at making it easy for end-users to list and access
+    all available FairnessFunction classes at any given time. The returned
+    dict uses unique identifier keys, which may be used to use the associated
+    function within a [declearn.fairness.api.FairnessControllerServer][].
+
+    Note that the mapping will include all declearn-provided functions,
+    but also registered functions provided by user or third-party code.
+
+    See also
+    --------
+    * [declearn.fairness.api.FairnessFunction][]:
+        API-defining abstract base class for the FairnessFunction classes.
+
+    Returns
+    -------
+    mapping:
+        Dictionary mapping unique str identifiers to `FairnessFunction`
+        class constructors.
+    """
+    return access_types_mapping("FairnessFunction")
+
+
 class AccuracyParityFunction(FairnessFunction):
     """Accuracy Parity group-fairness function.
 
@@ -120,7 +147,7 @@ class DemographicParityFunction(FairnessFunction):
     evaluated classifier.
 
     In other words, Demographic Parity is achieved when the probability to
-    predict any given label is indenpendent from the sensitive attribute(s)
+    predict any given label is independent from the sensitive attribute(s)
     (regardless of whether that label is accurate or not).
 
     Formula

test/fairness/test_fairness_functions.py

@@ -32,6 +32,7 @@ from declearn.fairness.core import (
     DemographicParityFunction,
     EqualityOfOpportunityFunction,
     EqualizedOddsFunction,
+    list_fairness_functions,
 )
 from declearn.test_utils import assert_dict_equal
 
@@ -297,3 +298,20 @@ class TestEqualityOfOpportunity(TestEqualizedOddsFunction):
                 counts=self.counts,
                 target="wrong-type",  # type: ignore
             )
+
+
+def test_list_fairness_functions() -> None:
+    """Test 'declearn.fairness.core.list_fairness_functions'."""
+    mapping = list_fairness_functions()
+    assert isinstance(mapping, dict)
+    assert all(
+        isinstance(key, str) and issubclass(val, FairnessFunction)
+        for key, val in mapping.items()
+    )
+    for cls in (
+        AccuracyParityFunction,
+        DemographicParityFunction,
+        EqualityOfOpportunityFunction,
+        EqualizedOddsFunction,
+    ):
+        assert mapping.get(cls.f_type) is cls  # type: ignore