structboost 0.3.0__tar.gz → 0.4.0__tar.gz

{structboost-0.3.0 → structboost-0.4.0}/CHANGELOG.md

@@ -3,6 +3,52 @@
 Releases follow [semantic versioning](https://semver.org). While the project is
 pre-1.0, a minor bump may break API.
 
+### [0.4.0] - 2026-08-12
+
+Three defaults change. No configuration fields are added or removed, and anyone
+who sets these explicitly is unaffected.
+
+**`enable_early_stopping` now defaults to `False`.** The criterion is a
+convergence check being used as a quality check. There is no validation split, so
+the training loss cannot see a model that is starting to memorize, and patience
+fires long before the model is done: measured against ground truth it stopped at
+iteration 90 on a dataset peaking at 259, and at 196 on a simulated scenario
+peaking at 560, returning marker-recovery F1 0.502 against 0.787. Across three
+real datasets (mouse cortex, human pancreas, human immune) the best iteration
+ranged from 154 to 1975 — always past where patience fires.
+
+**No stopping rule replaced it, deliberately.** Latent stability, encoder-support
+overlap and held-out reconstruction were each measured as candidates and each
+rejected. The representation settles long before gene selection does — on one
+dataset consecutive latent codes were rank-identical while the gene set still
+turned over 65% cumulatively — and no observable signal tracks the quality peak.
+A latent-stability rule was built and tuned; it fired at iteration ~109 on all
+three real datasets regardless of where quality peaked, and on one of them it was
+worse than not stopping at all. It is not shipped, not even off by default: an
+option that should never be enabled is pure carrying cost, which is the same
+argument that removed four fields in 0.3.0. `max_iterations=1000` is a defensible
+middle of the measured range, not an optimum.
+
+**`BAE.stability_selection(threshold=...)` now defaults to `0.5`, from `0.7`.**
+0.7 is too aggressive whenever the latent representation is still moving: across
+three real datasets it removed 21-52% of recovered marker genes relative to the
+fitted encoder, and 0-7% even when the representation had settled. At 0.5 the
+worst loss over the same six runs was 6%. The standalone
+`structboost.stability_selection` keeps 0.7, because its Meinshausen-Buhlmann
+bound is undefined at or below 0.5.
+
+**The `dim_match_quality` warning now fires below 0.85, from 0.5.** It is the gate
+on whether iteration frequencies mean anything: they describe gene-set drift only
+if the counted iterations describe one representation. Runs sitting at 0.70-0.79 —
+comfortably above the old warning — already lost a quarter to a half of their
+recovered markers at the default threshold, while runs at 0.93 and above lost
+none. The guide now documents it as a lookup: at least 0.93, either threshold is
+safe; 0.70-0.79, use 0.3-0.5 and prefer the flat union.
+
+Also fixed: the gene-selection guide still showed
+`fit(adata, stability_selection="iteration")`, which stopped being valid in 0.3.0
+when that argument became a bool.
+
 ### [0.3.0] - 2026-08-11
 
 **Breaking.** Five settings are gone and `BAE.stability_selection` has one mode

{structboost-0.3.0 → structboost-0.4.0}/CITATION.cff

@@ -2,7 +2,7 @@ cff-version: 1.2.0
 message: "If you use structboost in your research, please cite it."
 title: "structboost"
 type: software
-version: "0.3.0"
+version: "0.4.0"
 date-released: "2026-08-11"
 license: MIT
 authors:

{structboost-0.3.0 → structboost-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: structboost
-Version: 0.3.0
+Version: 0.4.0
 Summary: Boosting Autoencoders (BAE) and componentwise L2 boosting utilities for scverse-style workflows.
 Project-URL: Homepage, https://github.com/NiklasBrunn/structboost
 Project-URL: Documentation, https://niklasbrunn.github.io/structboost

{structboost-0.3.0 → structboost-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "structboost"
-version = "0.3.0"
+version = "0.4.0"
 description = "Boosting Autoencoders (BAE) and componentwise L2 boosting utilities for scverse-style workflows."
 readme = "README.md"
 license = { file = "LICENSE" }

{structboost-0.3.0 → structboost-0.4.0}/src/structboost/_model.py

@@ -29,6 +29,14 @@ if TYPE_CHECKING:
 # "iteration" is generated at the end, not accumulated.
 _REPORT_FIELDS: tuple[str, ...] = tuple(TrainingReport.__dataclass_fields__)
 
+# Below this mean matched |cosine| between an iteration's latent dimensions and the
+# fitted model's, iteration-mode stability frequencies stop describing a single
+# representation and a frequency threshold becomes destructive. Raised from 0.5 in
+# 0.4.0: measured runs sitting at 0.70-0.79 already lost a quarter to a half of
+# their recovered markers at the default threshold, while runs at 0.93 and above
+# lost none.
+_DIM_MATCH_WARN: float = 0.85
+
 # Per-group reconstruction losses are reported only for obs columns with at most
 # this many levels; beyond it the breakdown is per-cell noise rather than a
 # summary. Columns above the limit are skipped with a warning, never silently.
@@ -2404,11 +2412,16 @@ class BAE(nn.Module):
             self.decoder.load_state_dict(saved_decoder)
 
         quality = float(np.mean(match_scores)) if match_scores else float("nan")
-        if np.isfinite(quality) and quality < 0.5:
+        if np.isfinite(quality) and quality < _DIM_MATCH_WARN:
             warnings.warn(
                 f"Latent dimensions matched the fitted model poorly across iterations "
-                f"(mean |cosine| {quality:.2f}). Per-dimension frequencies are unreliable "
-                "here; use frequency.max(axis=1) for the flat union instead.",
+                f"(mean |cosine| {quality:.2f}, below {_DIM_MATCH_WARN}). The counted "
+                "iterations are not describing one representation, so a frequency "
+                "threshold prunes genes that are simply attached to a different "
+                "version of the latent space: measured on real data this removed "
+                "21-52% of recovered markers at the default threshold. Lower "
+                "`threshold` to 0.3-0.5, and prefer frequency.max(axis=1), the flat "
+                "union, over the per-dimension split.",
                 UserWarning,
                 stacklevel=3,
             )
@@ -2429,7 +2442,7 @@ class BAE(nn.Module):
         adata: AnnData,
         *,
         n_runs: int = 300,
-        threshold: float = 0.7,
+        threshold: float = 0.5,
         seed: int | None = None,
         verbose: bool = True,
     ):
@@ -2472,7 +2485,19 @@ class BAE(nn.Module):
             ~0.45 at lag 100 on measured data), so short windows give highly
             correlated, near-duplicate samples.
         threshold
-            Selection-frequency cutoff for the stable support.
+            Selection-frequency cutoff for the stable support. Default 0.5,
+            lowered from 0.7 in 0.4.0.
+
+            0.7 was measured to be too aggressive whenever the latent
+            representation is still moving: across three real datasets it removed
+            21-52% of recovered marker genes relative to the fitted encoder, and
+            0-7% even when the representation had settled. At 0.5 the worst loss
+            over the same six runs was 6%. Raising it back toward 0.7-0.9 buys
+            precision and is reasonable when ``dim_match_quality`` is high; see
+            that field on the result before doing so.
+
+            Note the standalone :func:`structboost.stability_selection` keeps 0.7,
+            because its Meinshausen-Buhlmann bound is undefined at or below 0.5.
         seed
             Seeds torch for the continued training iterations.
         verbose

{structboost-0.3.0 → structboost-0.4.0}/src/structboost/_types.py

@@ -166,12 +166,27 @@ class BAEConfig:
     max_iterations
         Maximum number of training iterations.
     enable_early_stopping
-        If True (default), stop training early when the checkpoint-selection loss
-        does not decrease for `early_stopping_patience` iterations. This is the
-        decoder training MSE for ``disentanglement="none"`` and
-        ``"leave_one_out"``; for ``"correlation"`` it additionally includes the
-        weighted disentanglement penalty. If False, train for exactly
-        `max_iterations`.
+        If True, stop training early when the checkpoint-selection loss does not
+        decrease for `early_stopping_patience` iterations. This is the decoder
+        training MSE for ``disentanglement="none"`` and ``"leave_one_out"``; for
+        ``"correlation"`` it additionally includes the weighted disentanglement
+        penalty. **Default False**: train for exactly `max_iterations`.
+
+        The default changed in 0.4.0 because the criterion is a *convergence*
+        check being used as a *quality* check, and it stops far too early. There
+        is no validation split, so the training loss cannot see a model that is
+        beginning to memorize; measured against ground truth it stopped at
+        iteration 90 on one dataset whose marker recovery peaked at 259, and at
+        196 on a simulated scenario peaking at 560 (returning F1 0.502 against
+        0.787). Across three real datasets the best iteration ranged from 154 to
+        1975, always past where patience fires.
+
+        No stopping rule replaced it, because none was found that works. Latent
+        stability, support overlap and held-out reconstruction were each measured
+        as candidates; the representation settles long before gene selection
+        does, and nothing observable tracks the quality peak. Run the iteration
+        budget and let :meth:`BAE.stability_selection` absorb the variance
+        instead — that is what it is for.
     early_stopping_patience
         Number of consecutive iterations without checkpoint-selection loss
         improvement required to trigger early stopping. Only used if
@@ -215,7 +230,7 @@ class BAEConfig:
     decoder_weight_decay: float = 0.0
     decoder_updates_per_iteration: int = 10
     max_iterations: int = 1000
-    enable_early_stopping: bool = True
+    enable_early_stopping: bool = False
     early_stopping_patience: int = 50
     batch_size: int = 2**9
     seed: int | None = None

{structboost-0.3.0 → structboost-0.4.0}/tests/test_bae.py

@@ -1271,6 +1271,29 @@ def test_bae_nuisance_only_needs_no_obs_for_reconstruction():
     assert model.reconstruct(without_obs).shape == x.shape
 
 
+def test_fit_runs_the_full_budget_by_default():
+    """Early stopping is off by default, so a fit uses its whole iteration budget.
+
+    Changed in 0.4.0: the training-loss criterion is a convergence check standing in
+    for a quality check, and it fires long before marker recovery peaks.
+    """
+    _require_bae_deps()
+    import anndata as ad
+
+    from structboost import BAE, BAEConfig
+
+    rng = np.random.default_rng(0)
+    x = rng.normal(size=(40, 12)).astype(np.float32)
+    x = (x - x.mean(axis=0)) / x.std(axis=0)
+    adata = ad.AnnData(x)
+    config = BAEConfig(latent_dim=2, max_iterations=6, early_stopping_patience=1)
+    assert config.enable_early_stopping is False
+    BAE(12, config).fit(adata, verbose=False)
+
+    # Patience 1 would have stopped almost immediately had it been active.
+    assert len(adata.uns["bae"]["training_history"]["train_loss"]) == 6
+
+
 def test_variance_explained_is_written_by_a_plain_fit():
     """It is a quality metric, not a covariate one.
 

{structboost-0.3.0 → structboost-0.4.0}/tests/test_stability.py

@@ -394,6 +394,55 @@ def test_iteration_loop_matches_the_training_loop():
     np.testing.assert_array_equal(supports_cont[0], second_iteration_support)
 
 
+def test_shipped_defaults_are_the_measured_ones():
+    """The three 0.4.0 defaults, pinned so they cannot drift back silently.
+
+    Each replaced a value measured to be harmful: patience-50 early stopping stops
+    before the quality peak on every dataset tried (best iteration 154-1975);
+    threshold 0.7 removes 21-52% of recovered markers when the latent is still
+    moving; and the 0.5 dim_match_quality warning never fired on runs at 0.70-0.79
+    that had already lost a quarter to a half of their markers.
+    """
+    import inspect
+
+    from structboost import BAE, BAEConfig
+    from structboost import stability_selection as standalone
+    from structboost._model import _DIM_MATCH_WARN
+
+    assert BAEConfig().enable_early_stopping is False
+    assert inspect.signature(BAE.stability_selection).parameters["threshold"].default == 0.5
+    assert _DIM_MATCH_WARN == 0.85
+
+    # The standalone function keeps 0.7: its Meinshausen-Buhlmann bound is
+    # undefined at or below 0.5, so the two defaults differ deliberately.
+    assert inspect.signature(standalone).parameters["threshold"].default == 0.7
+
+
+def test_poor_dimension_matching_warns_below_the_gate():
+    """The gate must fire when dimensions stop keeping their identity.
+
+    A short fit on structured data permutes its dimensions enough to land under the
+    gate, which is the case the warning exists for: the counted iterations are then
+    describing different representations, and a frequency threshold prunes genes
+    attached to the wrong one.
+    """
+    _require_bae()
+    from structboost import BAE, BAEConfig, sim_scrnaseq_anndata
+    from structboost._model import _DIM_MATCH_WARN
+
+    a = sim_scrnaseq_anndata(n=300, n_genes=120, stageno=4, stagep=10, seed=2)
+    model = BAE(
+        a.n_vars,
+        BAEConfig(latent_dim=4, max_iterations=20, enable_early_stopping=False, seed=0),
+    )
+    model.fit(a, verbose=False)
+
+    with pytest.warns(UserWarning, match="matched the fitted model poorly") as caught:
+        res = model.stability_selection(a, n_runs=6, seed=0, verbose=False)
+    assert res.dim_match_quality < _DIM_MATCH_WARN
+    assert f"below {_DIM_MATCH_WARN}" in str(caught[0].message)
+
+
 def test_iteration_mode_rejects_bad_arguments():
     pytest.importorskip("torch")
     adata = _tiny_adata()