structboost

Note that this package is under active development. The API is still moving, and a minor version bump may break it.

Structured representation learning for single-cell data. A latent space you can read gene by gene.

The Boosting Autoencoder (BAE) pairs a linear encoder fitted by componentwise L2 boosting with an MLP decoder trained by gradient descent. Each training iteration takes a gradient step on the latent code itself and hands the result to the boosting fit as a regression target, so the encoder is fitted against the gradient-updated latent code rather than by backpropagation. The target is that updated code rather than the gradient alone because the encoder is rebuilt from zero every iteration: it has to reproduce where the code should be, not the correction to where it already is. Componentwise boosting adds one gene at a time and shrinks each step, which keeps the encoder weights sparse by construction rather than by a post-hoc threshold.

Each latent dimension is therefore a short, signed gene list, and X_bae is exactly X @ varm["BAE_encoder_weights"].

The package also ships allboost, the componentwise boosting routine on its own, for sparse supervised problems with no autoencoder involved.

Relation to the original method

This is a scanpy-compatible Python re-implementation of the Boosting Autoencoder introduced in Hackenberg et al. (2025), where the method and its componentwise boosting core were developed in Julia.

Some methodological components differ from the original proposal. Defaults and several parts of the training procedure were re-derived here against simulated data with known ground truth, and the measurements behind each are recorded in the user guide next to the setting they justify. Results from this implementation should therefore not be assumed identical to the original paper's.

📖 Documentation · User guide · API reference · Changelog

Installation

Requires Python 3.10 or newer. The core depends on NumPy alone, and everything heavier is opt-in.

pip install "structboost[bae,plot]"     # the BAE
pip install structboost                 # allboost only, NumPy-only

See Installation for the from-source and development setups.

Quickstart

adata.X must be z-scored, which sc.pp.scale gives you.

from structboost import BAE, BAEConfig

model = BAE(adata.n_vars, BAEConfig(latent_dim=10))
model.fit(adata)

adata.obsm["X_bae"]                 # (n_cells, 10) latent space
adata.varm["BAE_encoder_weights"]   # (n_genes, 10), sparse

To integrate over a batch or any other unwanted covariate, name the obs column:

model.fit(adata, batch_key="batch")          # or ["batch", "donor"]

adata.uns["bae"]["latent_obs_r2_per_dim"]    # near zero means it worked

By default this both conditions the decoder on the covariate and adds it to the boosting design as a mandatory regressor, so a batch-correlated gene is not selected because of the batch. The covariate is never an encoder input, so transform stays gene-only and needs no batch labels on new data.

A single fit gives one gene list, and that list is not reproducible: in a high-dimensional feature space with strongly correlated genes the encoder support is not identifiable, so many different sparse gene sets reconstruct the data about equally well and a fit returns one of them. See gene selection before trusting a single list.

Componentwise L2 boosting on its own, no autoencoder involved:

from structboost import allboost

betamat = allboost(sourcemat, targetmat_std, stepno=20, nu=0.1)
# (n_targets, n_features), sparse

What else it does

Each of these has a guide page.

Exploratory features

The whole package is pre-1.0, but these four are under active development and less settled than the rest. They work, and each is documented with what is known about it — but their behaviour, defaults and APIs are more likely to change, and results from them warrant more scepticism than the core fit does.

Citation

If you use the BAE:

Hackenberg, M., Brunn, N., Vogel, T. et al. Infusing structural assumptions into dimensionality reduction for single-cell RNA sequencing data to identify small gene sets. Commun Biol 8, 414 (2025). https://doi.org/10.1038/s42003-025-07872-9

If you use allboost:

Binder, H., Schumacher, M. Incorporating pathway information into boosting estimation of high-dimensional risk prediction models. BMC Bioinformatics 10, 18 (2009). https://doi.org/10.1186/1471-2105-10-18

Development note

Claude Code (Anthropic) was used in building this package, to support implementation, to write tests, and to write the documentation. Individual commits record it as a co-author.

The methods, the design decisions, and the scientific claims are the authors'. Everything committed was reviewed, and the behavioural claims in the docstrings and the user guide are backed by the test suite or by the measurements cited alongside them.

Open points

Known gaps and planned work.

• Revise the early-stopping criterion. Early stopping is off by default because the training-loss rule is a convergence check being used as a quality check, and it stops well before gene selection has settled. No replacement has been found yet.
• Stability selection. Iteration mode carries no formal error control, and its per-dimension frequencies are only interpretable when dim_match_quality is high. A scheme with a defensible bound under a model fitted on the same cells is still open.
• Multimodal architecture — reconstruction-based, with a shared latent space across modalities, for paired single-cell data.
• Contrastive objective, as an alternative or addition to the reconstruction target the boosting step is currently fitted against.
• Stochastic gradient boosting (Friedman 2002): subsample the cells at each boosting step, which is both a regularizer and a route to cheaper iterations on large datasets.

Contributing

See CONTRIBUTING.md for the development setup, the versioning policy, and what a pull request needs. Planned work is tracked in the issue tracker.

Licensed under the MIT License.