separability.functor.py

class rings.separability.functor.SeparabilityFunctor(comparator: Callable, n_jobs: int = 1, alpha: float = 0.01, **kwargs)

A functor for computing separability between multiple distributions.

This class computes all pairwise statistical comparisons between distributions, applies Bonferroni correction for multiple testing, and returns structured results. It’s designed to test whether different graph perturbations lead to statistically significant differences in model performance or metrics.

Parameters:

• comparator (callable) – A comparator class (e.g., KSComparator, WilcoxonComparator) that implements a __call__ method for comparing two distributions.

• n_jobs (int, default=1) – Number of jobs to run in parallel. If 1, no parallelism is used.

• alpha (float, default=0.01) – Family-wise significance level for hypothesis testing. After Bonferroni correction, a p-value less than alpha/num_tests is considered significant.

• **kwargs (dict) – Additional arguments passed to the comparator.

Examples

>>> import numpy as np
>>> from rings.separability.functor import SeparabilityFunctor
>>> from rings.separability.comparator import KSComparator
>>>
>>> # Create distributions to compare
>>> distributions = {
...     "Original": np.random.normal(0.8, 0.1, 30),  # High performance
...     "CompleteFeatures": np.random.normal(0.5, 0.1, 30),  # Low performance
...     "EmptyGraph": np.random.normal(0.5, 0.1, 30)  # Low performance
... }
>>>
>>> # Create functor and run analysis
>>> functor = SeparabilityFunctor(comparator=KSComparator(), alpha=0.05)
>>> results = functor.forward(distributions)
>>>
>>> # Results contain pairwise comparisons with significance tests
>>> print(results[['mode1', 'mode2', 'score', 'pvalue_adjusted', 'significant']])

__init__(comparator: Callable, n_jobs: int = 1, alpha: float = 0.01, **kwargs)

Initialize the SeparabilityFunctor.

Parameters:

• comparator (Callable) – An instance of a comparator class (e.g., KSComparator, WilcoxonComparator) that implements a compare() method.

• n_jobs (int, default=1) – Number of jobs to run in parallel. If 1, no parallelism is used.

• alpha (float, default=0.01) – Family-wise significance level for hypothesis testing.

• **kwargs (dict) – Additional arguments passed to the comparator.

forward(distributions: Dict[str, List[float] | ndarray], n_permutations: int = 10000, random_state: int | None = 42, as_dataframe: bool = True) → List[Dict[str, Any]] | DataFrame

Compute all pairwise separability tests between distributions.

This method performs statistical tests to determine whether distributions are significantly different from each other, applying Bonferroni correction for multiple comparisons.

Parameters:

• distributions (Dict[str, Union[List[float], np.ndarray]]) – Dictionary mapping mode names to performance distributions. Example: {“Original”: np.array([0.8, 0.7, …]), “EmptyGraph”: np.array([0.5, 0.6, …])}

• n_permutations (int, default=10_000) – Number of permutations for the statistical tests.

• random_state (Optional[int], default=42) – Random seed for reproducibility.

• as_dataframe (bool, default=True) – If True, return results as a pandas DataFrame, otherwise as a list of dictionaries.

Returns:

Results of all pairwise comparisons, either as a list of dictionaries or a pandas DataFrame. Each result contains the mode names, p-value, statistic, and significance indicator.

Return type:

Union[List[Dict[str, Any]], pd.DataFrame]

Examples

>>> functor = SeparabilityFunctor(comparator=KSComparator(), n_jobs=4, alpha=0.05)
>>> distributions = {
...     "Original": np.array([0.8, 0.7, 0.75, 0.82, 0.79]),
...     "EmptyGraph": np.array([0.5, 0.48, 0.52, 0.49, 0.51]),
...     "NoFeatures": np.array([0.45, 0.47, 0.5, 0.52, 0.48])
... }
>>> results = functor.forward(distributions)
>>> print(results)