structboost 0.2.0__tar.gz → 0.4.0__tar.gz

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

@@ -3,6 +3,122 @@
 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
+instead of two. Every removed option was off by default, so a fit that took the
+defaults is unaffected: the encoder matrix is bitwise identical across a plain
+fit, a batch-integrated fit, and both disentanglement methods. What changes is the
+surface you have to reason about.
+
+`boosting_nu` stays at `0.1`. Raising it to `0.3` was measured and deferred: at
+the default `stepno=50` it matches `0.1`'s marker recovery three to four times
+faster and wins outright on low-signal data, but then degrades if training
+continues, and the training-MSE stopping rule cannot see it happening. The guide
+records the numbers; the two changes belong together and will land together.
+
+**Checkpoints written by 0.2.0 no longer load.** `restore_payload` splats the
+stored config into `BAEConfig`, so a dropped field is an unexpected keyword
+argument rather than a missing one. The format is bumped to 5 and the loader
+refuses 4 by name. No migration is written: the method is under active
+development and a checkpoint is cheap to regenerate, whereas a compatibility
+shim for options that no longer exist is not.
+
+Removed from `BAEConfig`:
+
+- `decoder_dropout_rate` and `decoder_use_batch_norm`. Batch norm was already
+  documented as harmful (marker-recovery F1 0.59-0.73) because the boosting
+  target is computed with the decoder in eval mode and the update applied in
+  train mode. Dropout has exactly the same inconsistency and it was never written
+  down: the target comes from the full network, the update from a thinned one.
+  With both gone the decoder is a deterministic per-cell function, which is the
+  property `_compute_boosting_targets` has always relied on.
+- `disentanglement_standardize`. Both `disentanglement` methods stay.
+- `standardize_targets`. It was a genuine trade-off — higher selection precision,
+  roughly half the recall — but it is superseded by
+  `stability_selection(threshold=...)` -> `stable_encoder()` -> `apply_encoder()`,
+  which is the same trade with a dial that reports what it is doing. Two knobs for
+  one trade-off is worse than one.
+
+Removed from `fit`:
+
+- `balance_obs`, and with it the `sample_weights` parameter that threaded through
+  nine methods and both stability paths. Its own documentation conceded the
+  limit: the weights never reached the `allboost` fit, so gene selection stayed
+  unbalanced no matter what they were set to. The measured effect was modest (per
+  group reconstruction-MSE spread 0.231 -> 0.150) for a mechanism that promised
+  more than it delivered.
+
+`BAE.stability_selection` is now iteration mode only; `mode`, `subsample_frac`,
+`n_subsamples` and `n_iterations` are gone, and `fit(stability_selection=...)`
+takes a bool. Iteration mode was already the default and measures the lower
+false-discovery rate (0.26 against 0.31). The subsample path stays available as
+the standalone `structboost.stability_selection`, which is where it belongs: it
+resamples cells in the Meinshausen-Buhlmann scheme and works on an `allboost`
+problem, so supervised users with no training loop to iterate over still have it.
+The Meinshausen-Buhlmann bound it reports was measured to be violated by roughly
+an order of magnitude when the targets come from a model fitted on the same
+cells, and that warning moved with it.
+
+`uns["bae"]["variance_explained"]` is now written by every fit. It used to appear
+only when a covariate argument was passed, which left the quality workflow the
+guide documents — compare it against `linear_ceiling` — raising `KeyError` on a
+plain `fit(adata)`. The metric has nothing to do with covariates; only the
+per-group breakdown does, and that stays behind the covariate guard.
+
+Two fixes found along the way: the `allboost` example in the guide passed
+`mode="standard"`, an argument `allboost` has never accepted, so it raised
+`TypeError` as written. And `disentangle_boosting_targets` projects through the
+origin, with no intercept — exact residualization only on centered targets. That
+was masked by `disentanglement_standardize`, which centered them; with the flag
+gone the assumption is documented instead.
+
 ### [0.2.0] - 2026-08-05
 
 The boosting loop got faster without changing what it computes. Measured

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

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

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

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: structboost
-Version: 0.2.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
@@ -153,7 +153,7 @@ is not identifiable: many different sparse gene sets reconstruct the data about
 equally well, and a fit returns one of them.
 
 ```python
-res = model.stability_selection(adata, mode="iteration")
+res = model.stability_selection(adata)
 genes = [adata.var_names[res.stable_support[:, j]] for j in range(res.frequency.shape[1])]
 ```
 

{structboost-0.2.0 → structboost-0.4.0}/README.md

@@ -78,7 +78,7 @@ is not identifiable: many different sparse gene sets reconstruct the data about
 equally well, and a fit returns one of them.
 
 ```python
-res = model.stability_selection(adata, mode="iteration")
+res = model.stability_selection(adata)
 genes = [adata.var_names[res.stable_support[:, j]] for j in range(res.frequency.shape[1])]
 ```
 

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "structboost"
-version = "0.2.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.2.0 → structboost-0.4.0}/src/structboost/_decoder.py

@@ -55,11 +55,7 @@ class BAEDecoder(nn.Module):
 
         for i in range(len(dims) - 1):
             layers.append(nn.Linear(dims[i], dims[i + 1]))
-            if config.decoder_use_batch_norm:
-                layers.append(nn.BatchNorm1d(dims[i + 1]))
             layers.append(self.activation)
-            if config.decoder_dropout_rate > 0:
-                layers.append(nn.Dropout(config.decoder_dropout_rate))
 
         self.hidden = nn.Sequential(*layers)
         # Final projection to output space
@@ -83,8 +79,6 @@ class BAEDecoder(nn.Module):
         for module in self.modules():
             if isinstance(module, nn.Linear):
                 module.reset_parameters()
-            elif isinstance(module, nn.BatchNorm1d):
-                module.reset_parameters()
 
     def forward(self, z: torch.Tensor, covariates: torch.Tensor | None = None) -> torch.Tensor:
         """Decode latent representation to reconstruction.