How ibm/infairness works
Main Components
• Core Library (inFairness Package): Divide it into its major submodules:
• Auditor Module: Contains the implementations for “auditing”, e.g., modules like auditor.py, sensei_auditor.py, sensr_auditor.py, senstir_auditor.py. This component is responsible for evaluating whether a given ML model meets individual fairness criteria.
• Distances Module: Implements various distance metrics (files like euclidean_dists.py, mahalanobis_distance.py, sensitive_subspace_dist.py, logistic_sensitive_subspace.py, wasserstein_distance.py). This module measures similarity between inputs and outputs.
• Fair Algorithms Module (fairalgo): Holds the fair learning algorithms (such as SenSeI in SenSeI.py) which are used to train models under fairness constraints.
• Postprocessing Module: Contains the post‑processing methods to adjust the outcomes of models for fairness purposes.
• Utility Module: Provides helper functions and utilities (datautils, ndcg, plackett_luce, etc.) that support data handling, metrics calculation, and parameter validation.
External Components
• ML Model and Data Pipeline: Highlight that the package is typically used alongside a PyTorch model and data loaders. Illustrate how training workflows incorporate distance metric fitting and fairness training.
• Examples and Tutorials: Indicate the presence of the “examples” directory where various demos (e.g., sentiment analysis, synthetic data generation, adult income prediction) show typical usage patterns.
• Testing and CI Pipeline: Mention the tests directory for unit testing and configuration files such as .travis.yml that indicate continuous integration processes.
Relationships and Data Flow
• Data is processed by the Distances Module to compute dₓ and dᵧ.
• The computed distances and input data are passed to the Fair Algorithms module (for instance, using algorithms like SenSeI) which enforces fairness during training.
• The Auditor module can then evaluate the fairness of the trained model by comparing predictions and input similarities.
• If necessary, the Postprocessing module further adjusts model outputs.
• The Utility module serves throughout these processes to support computations and validations.
Architectural Patterns and Design Principles
• Modularity: Each subcomponent (auditor, distances, fairalgo, postprocessing) is encapsulated and independently testable.
• Separation of Concerns: Fairness auditing, fair learning, and metric computations are separated into their own modules.
• Extensibility: The clear interfaces between modules (e.g., datainterface in both auditor and postprocessing) promote integration and additional feature development.
• Testability: Presence of the tests directory ensures that each component is validated independently.
a. Auditor Module (with subnodes for each auditor type)
b. Distances Module (with subnodes for different distance computations)
c. Fair Algorithms Module (depicting SenSeI)
d. Postprocessing Module
e. Utilities Module