Rename rank stability and homogeneize interface

Author: mdbenito

docs/value/semi-values.md

@@ -115,13 +115,14 @@ $\mathbf{S}_{\not{\ni} i}$ are the subsets not containing the index $i$.
 
 The function implementing this method is
 [compute_msr_banzhaf_semivalues][pydvl.value.semivalues.compute_msr_banzhaf_semivalues].
+
 ```python
-from pydvl.value import compute_msr_banzhaf_semivalues, RankStability, Utility
+from pydvl.value import compute_msr_banzhaf_semivalues, RankCorrelation, Utility
 
 utility = Utility(model, data)
 values = compute_msr_banzhaf_semivalues(
-    u=utility, done=RankStability(rtol=0.001),
-)
+  u=utility, done=RankCorrelation(rtol=0.001),
+  )
 ```
 For further details on how to use this method and a comparison of the sample 
 efficiency, we suggest to take a look at the example notebook 

notebooks/msr_banzhaf_digits.ipynb

@@ -694,7 +694,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Computing the values is the same, but we now use a better stopping criterion. Instead of fixing the number of utility evaluations with [MaxChecks](../../api/pydvl/value/stopping/#pydvl.value.stopping.MaxChecks), we use [RankStability](../../api/pydvl/value/stopping/#pydvl.value.stopping.RankStability) to stop when the change in Spearman correlation between the ranking of two successive iterations is below a threshold. "
+    "Computing the values is the same, but we now use a better stopping criterion. Instead of fixing the number of utility evaluations with [MaxChecks](../../api/pydvl/value/stopping/#pydvl.value.stopping.MaxChecks), we use [RankCorrelation](../../api/pydvl/value/stopping/#pydvl.value.stopping.RankCorrelation) to stop when the change in Spearman correlation between the ranking of two successive iterations is below a threshold. "
    ]
   },
   {
@@ -715,7 +715,7 @@
    "source": [
     "values = compute_msr_banzhaf_semivalues(\n",
     "    utility,\n",
-    "    done=RankStability(0.0001),\n",
+    "    done=RankCorrelation(rtol=0.0001, burn_in=10),\n",
     "    n_jobs=n_jobs,\n",
     "    progress=True,\n",
     ")\n",

src/pydvl/value/semivalues.py

@@ -117,7 +117,7 @@
     SampleT,
     StochasticSampler,
 )
-from pydvl.value.stopping import MaxUpdates, RankStability, StoppingCriterion
+from pydvl.value.stopping import MaxUpdates, RankCorrelation, StoppingCriterion
 
 __all__ = [
     "compute_banzhaf_semivalues",
@@ -635,7 +635,7 @@ def compute_banzhaf_semivalues(
 def compute_msr_banzhaf_semivalues(
     u: Utility,
     *,
-    done: StoppingCriterion = RankStability(0.01),
+    done: StoppingCriterion = RankCorrelation(0.01),
     sampler_t: Type[StochasticSampler] = MSRSampler,
     batch_size: int = 1,
     n_jobs: int = 1,

src/pydvl/value/stopping.py

@@ -143,7 +143,7 @@
     "MinUpdates",
     "MaxTime",
     "HistoryDeviation",
-    "RankStability",
+    "RankCorrelation",
 ]
 
 logger = logging.getLogger(__name__)
@@ -630,7 +630,7 @@ def __str__(self):
         return f"HistoryDeviation(n_steps={self.n_steps}, rtol={self.rtol})"
 
 
-class RankStability(StoppingCriterion):
+class RankCorrelation(StoppingCriterion):
     r"""A check for stability of Spearman correlation between checks.
 
     When the change in rank correlation between two successive iterations is
@@ -645,23 +645,31 @@ class RankStability(StoppingCriterion):
 
     Args:
         rtol: Relative tolerance for convergence ($\epsilon$ in the formula)
+        modify_result: If `True`, the status of the input
+            [ValuationResult][pydvl.value.result.ValuationResult] is modified in
+            place after the call.
+        burn_in: The minimum number of iterations before checking for
+            convergence. This is required because the first correlation is
+            meaningless.
+
+    !!! tip "Added in 0.9.0"
     """
 
     def __init__(
         self,
         rtol: float,
+        burn_in: int,
         modify_result: bool = True,
-        min_iterations: int = 10,
     ):
         super().__init__(modify_result=modify_result)
         if rtol <= 0 or rtol >= 1:
             raise ValueError("rtol must be in (0, 1)")
         self.rtol = rtol
-        self._memory = None  # type: ignore
+        self.burn_in = burn_in
+        self._memory: NDArray[np.float_] | None = None
         self._corr = 0.0
         self._completion = 0.0
         self._iterations = 0
-        self.min_iterations = min_iterations
 
     def _check(self, r: ValuationResult) -> Status:
         self._iterations += 1
@@ -675,11 +683,11 @@ def _check(self, r: ValuationResult) -> Status:
         self._update_completion(corr)
         if (
             np.isclose(corr, self._corr, rtol=self.rtol)
-            and self._iterations > self.min_iterations
+            and self._iterations > self.burn_in
         ):
             self._converged = np.full(len(r), True)
             logger.debug(
-                f"RankStability has converged with {corr=} in iteration {self._iterations}"
+                f"RankCorrelation has converged with {corr=} in iteration {self._iterations}"
             )
             return Status.Converged
         self._corr = np.nan_to_num(corr, nan=0.0)
@@ -702,4 +710,4 @@ def reset(self):
         self._corr = 0.0
 
     def __str__(self):
-        return f"RankStability(rtol={self.rtol})"
+        return f"RankCorrelation(rtol={self.rtol})"

tests/value/test_stopping.py

@@ -13,7 +13,7 @@
     MaxTime,
     MaxUpdates,
     MinUpdates,
-    RankStability,
+    RankCorrelation,
     StoppingCriterion,
     make_criterion,
 )
@@ -199,12 +199,12 @@ def test_max_checks():
     assert done(v)
 
 
-def test_rank_stability():
-    """Test the RankStability stopping criterion."""
+def test_rank_correlation():
+    """Test the RankCorrelation stopping criterion."""
     v = ValuationResult.zeros(indices=range(5))
     arr = np.arange(5)
 
-    done = RankStability(rtol=0.1)
+    done = RankCorrelation(rtol=0.1)
     for i in range(20):
         arr = np.roll(arr, 1)
         for j in range(5):
@@ -213,14 +213,14 @@ def test_rank_stability():
     assert not done(v)
     assert done(v)
 
-    done = RankStability(rtol=0.1, min_iterations=3)
+    done = RankCorrelation(rtol=0.1, burn_in=3)
     v = ValuationResult.from_random(size=5)
     assert not done(v)
     assert not done(v)
     assert not done(v)
     assert done(v)
 
-    done = RankStability(rtol=0.1, min_iterations=2)
+    done = RankCorrelation(rtol=0.1, burn_in=2)
     v = ValuationResult.from_random(size=5)
     assert not done(v)
     assert not done(v)