structboost 0.1.0__tar.gz

structboost-0.1.0/.gitignore

@@ -0,0 +1,107 @@
+__pycache__/
+*.py[cod]
+*.pyd
+.Python
+build/
+dist/
+*.egg-info/
+.eggs/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+.ipynb_checkpoints/
+.venv/
+venv/
+.DS_Store
+
+# IDE
+.vscode/
+.idea/
+
+# Environment
+.env
+*.env.local
+
+# PyTorch
+*.pt
+*.pth
+runs/
+lightning_logs/
+
+# Data (large files)
+*.h5ad
+data/
+https:/
+
+# Notebooks and scratch scripts. Kept local while a clean tutorial set is
+# written: the existing notebooks store their outputs, so 96% of their bytes are
+# base64 images and every re-execution added megabytes to history permanently.
+examples/
+
+# Agents. Skills stay local for now: they are tooling around the package, not
+# part of it, and the package repo is being kept to what ships.
+agent_instructions_logs/
+agent_instructions/
+CLAUDE.md
+AGENTS.md
+docs/plans/
+.claude/
+.codex/
+
+# Agent transcript history
+agent_transcript_history/
+
+# Documentation build output. `docs/api/generated/` is autosummary output,
+# regenerated on every build -- tracking it produced spurious diffs.
+docs/_build/
+docs/api/generated/
+docs/generated/
+
+# Julia code implementations
+julia_componentwise_boosting_functions/
+.juliaup_home/
+.juliaup_home_test/
+.julia_depot_test/
+.julia_depot_bench_sandbox/
+.julia_depot_nb/
+.julia_depot/
+
+# Benchmark outputs
+benchmarks/bool_allboost/results/*.csv
+benchmarks/bool_allboost/figures/*.png
+
+# Numba JIT cache artifacts (v8 uses @njit(cache=True))
+benchmarks/bool_allboost/versions/**/*.nbi
+benchmarks/bool_allboost/versions/**/*.nbc
+
+# Cython build artifacts for bool_allboost v9
+benchmarks/bool_allboost/versions/_v9_kernel.c
+benchmarks/bool_allboost/versions/_v9_kernel*.so
+benchmarks/bool_allboost/versions/build/
+
+# Manuscript work. Separate lifecycle from the package; belongs in its own repo.
+paper_analysis/
+PAPER_PLAN.md
+
+# Design notes for work that is not implemented yet. Publishing them would
+# advertise behaviour the package does not have; move into docs/ when it lands.
+SCALING.md
+BAE_TARGET_SCALING.md
+
+# Binary-predictor boosting, held back from the initial package. It is the
+# intended encoder fitter for a planned Bernoulli BAE variant and is not wired
+# into BAE.fit, so it ships with nothing and is kept local until that lands.
+src/structboost/_bool_boosting.py
+tests/test_bool_boosting.py
+
+# Micro-optimization experiments for it, kept out of the package repo too.
+benchmarks/
+# Their equivalence tests go with them. Kept on disk so the local benchmark
+# workflow still runs; they import benchmarks/ and cannot pass in a fresh clone.
+tests/benchmarks/
+tests/test_bool_allboost_shared.py
+tests/test_bool_allboost_bench_equivalence.py
+# Loads .codex/skills/... by path, so it goes wherever the skills go.
+tests/test_explore_bae_results_skill.py

structboost-0.1.0/CHANGELOG.md

@@ -0,0 +1,32 @@
+## Changelog
+
+Releases follow [semantic versioning](https://semver.org). While the project is
+pre-1.0, a minor bump may break API.
+
+### [0.1.0] - 2026-07-31
+
+First public release.
+
+Batch integration is one argument. `BAE.fit(batch_key=...)` names the covariate,
+following scVI's spelling, and `batch_integration_mode` chooses between
+`"decoder"`, `"encoder"` and `"both"`, defaulting to `"both"`. No `batch_key`
+means no integration, and naming a mode without one raises rather than quietly
+integrating nothing.
+
+`"encoder"` names the half of the model the mechanism protects, not a tensor the
+covariate is fed to: it enters the boosting design as a mandatory regressor so
+gene selection is not confounded by it. `transform` remains gene-only and needs
+no covariate labels under any mode.
+
+The ridge that stabilizes near-collinear covariates is `BAEConfig.nuisance_ridge`.
+It is a numerical knob rather than a modelling one, so it sits with the other
+algorithm settings.
+
+The `test` extra pulls the runtime dependencies. The sdist carries `tests/` and
+`conftest.py` so that downstream packagers can run the suite at build time, and
+with pytest alone that did not work: 360 of the 411 test functions sit behind an
+`importorskip` for torch or anndata, so `pip install .[test] && pytest` ran ~51
+tests, skipped the rest and reported success. Installing `[test]` now brings in
+`[bae]`, so a green build means the suite actually ran. Documenting the
+requirement in `CONTRIBUTING.md` instead was rejected, because the reader who
+needs it is an automated build script rather than a person.

structboost-0.1.0/CITATION.cff

@@ -0,0 +1,9 @@
+cff-version: 1.2.0
+message: "If you use structboost in your research, please cite it."
+title: "structboost"
+type: software
+license: MIT
+authors:
+  - family-names: Brunn
+    given-names: Niklas
+repository-code: "https://github.com/NiklasBrunn/structboost"

structboost-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,8 @@
+## Code of Conduct
+
+This project follows the Contributor Covenant (v2.1) in spirit: be respectful, assume good faith, and keep discussions constructive.
+
+Unacceptable behavior includes harassment, discrimination, and sustained disruption of project discussions.
+
+If an issue arises, please contact the maintainer(s) via a private channel (e.g. email or a direct message) and include relevant context.
+

structboost-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,65 @@
+## Contributing
+
+Thank you for your interest in contributing to `structboost`.
+
+[Claude Code](https://claude.com/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. You are welcome to
+use coding agents on a contribution. What is asked of a pull request is the same
+either way: the change is reviewed by you before you open it, the tests pass, and
+any behavioural claim added to a docstring is backed by a test or by a
+measurement you can point to.
+
+- **Bug reports / feature requests**: please open an issue with a minimal reproduction or clear proposal.
+- **Pull requests**:
+  - Keep changes focused and add tests where feasible.
+  - Run locally:
+    - `ruff check .`
+    - `ruff format .`
+    - `pytest`
+
+### Development install
+
+With [uv](https://docs.astral.sh/uv/), which is much faster and what CI uses:
+
+```bash
+uv venv
+uv pip install -e ".[bae,plot,dev,test,docs]"
+uv run pre-commit install
+```
+
+Or with plain pip, which is fully supported:
+
+```bash
+python -m pip install -U pip
+python -m pip install -e ".[dev,test]"
+pre-commit install
+```
+
+Either way the package builds with Hatchling and end users install it from PyPI
+with pip. uv is only a developer convenience. A committed `uv.lock` pins the
+CI/development environment for reproducibility. It does not constrain the
+dependency ranges that downstream users resolve against. After changing
+dependencies in `pyproject.toml`, refresh it with `uv lock` and commit the
+result.
+
+### Versioning and releases
+
+Releases follow [semantic versioning](https://semver.org): `MAJOR.MINOR.PATCH`.
+
+While the project is pre-1.0, **a minor bump may break API**. The version
+communicates the size of a change, not a compatibility promise. `1.0.0` will
+mark the point at which that promise begins.
+
+Every user-facing change (new feature, bug fix, behavioural change) needs:
+
+1. A `CHANGELOG.md` entry under the correct `### [MAJOR.MINOR.PATCH]` heading,
+   in the house style, meaning a bold sentence naming the symbol, then *why*, including
+   any measurements and rejected alternatives, and a **Migration:** note for
+   anything breaking.
+2. A matching `version` bump in `pyproject.toml`.
+
+Releases are cut by pushing a tag that matches `pyproject.toml` exactly
+(`git tag v0.1.0 && git push --tags`). `.github/workflows/release.yml` verifies
+the two agree and refuses to publish if they do not.
+

structboost-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 niklas-br
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

structboost-0.1.0/PKG-INFO

@@ -0,0 +1,219 @@
+Metadata-Version: 2.4
+Name: structboost
+Version: 0.1.0
+Summary: Boosting Autoencoders (BAE) and componentwise L2 boosting utilities for scverse-style workflows.
+Project-URL: Homepage, https://github.com/NiklasBrunn/structboost
+Project-URL: Repository, https://github.com/NiklasBrunn/structboost
+Project-URL: Issues, https://github.com/NiklasBrunn/structboost/issues
+Author: Niklas Brunn
+License: MIT License
+        
+        Copyright (c) 2026 niklas-br
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: autoencoder,boosting,dimensionality-reduction,gene-selection,scverse,single-cell
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.23
+Provides-Extra: bae
+Requires-Dist: anndata>=0.10; extra == 'bae'
+Requires-Dist: pandas>=1.5; extra == 'bae'
+Requires-Dist: scipy>=1.10; extra == 'bae'
+Requires-Dist: torch>=2; extra == 'bae'
+Requires-Dist: tqdm>=4.60; extra == 'bae'
+Provides-Extra: dev
+Requires-Dist: pre-commit>=3.6; extra == 'dev'
+Requires-Dist: ruff<0.17,>=0.16; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: furo>=2024.1.29; extra == 'docs'
+Requires-Dist: myst-parser>=2.0; extra == 'docs'
+Requires-Dist: sphinx-copybutton>=0.5; extra == 'docs'
+Requires-Dist: sphinx-design>=0.5; extra == 'docs'
+Requires-Dist: sphinx>=7.2; extra == 'docs'
+Provides-Extra: io
+Requires-Dist: pandas>=1.5; extra == 'io'
+Requires-Dist: pyarrow>=12; extra == 'io'
+Provides-Extra: plot
+Requires-Dist: matplotlib>=3.7; extra == 'plot'
+Provides-Extra: test
+Requires-Dist: anndata>=0.10; extra == 'test'
+Requires-Dist: pandas>=1.5; extra == 'test'
+Requires-Dist: pytest>=7.4; extra == 'test'
+Requires-Dist: scipy>=1.10; extra == 'test'
+Requires-Dist: torch>=2; extra == 'test'
+Requires-Dist: tqdm>=4.60; extra == 'test'
+Description-Content-Type: text/markdown
+
+# 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
+negative gradient of the reconstruction loss rather than by backpropagation.
+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)](https://doi.org/10.1038/s42003-025-07872-9),
+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](https://niklasbrunn.github.io/structboost/guide/index.html)
+next to the setting they justify. Results from this implementation should
+therefore not be assumed identical to the original paper's.
+
+📖 **[Documentation](https://niklasbrunn.github.io/structboost)** · 
+[User guide](https://niklasbrunn.github.io/structboost/guide/index.html) · 
+[API reference](https://niklasbrunn.github.io/structboost/api/index.html) · 
+[Changelog](CHANGELOG.md)
+
+## Installation
+
+Requires Python 3.10 or newer. The core depends on NumPy alone, and everything
+heavier is opt-in.
+
+```bash
+pip install "structboost[bae,plot]"     # the BAE
+pip install structboost                 # allboost only, NumPy-only
+```
+
+| Extra | Brings in | Needed for |
+| --- | --- | --- |
+| *(none)* | numpy | `allboost`, `stability_selection` |
+| `bae` | torch, anndata, scipy, pandas, tqdm | `BAE`, the simulator, everything AnnData |
+| `plot` | matplotlib | the `plot_*` functions |
+| `io` | pyarrow | Parquet encoder-weight files |
+
+Not on PyPI yet. Until it is, install from source or from TestPyPI. Pin the
+version: TestPyPI also carries older pre-release builds under this name, and an
+unpinned install resolves to one of those rather than to the current code.
+
+```bash
+pip install --index-url https://test.pypi.org/simple/ \
+            --extra-index-url https://pypi.org/simple/ "structboost[bae]==0.1.0"
+```
+
+See [Installation](https://niklasbrunn.github.io/structboost/installation.html)
+for the from-source and development setups.
+
+## Quickstart
+
+`adata.X` must be z-scored, which `sc.pp.scale` gives you.
+
+```python
+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
+```
+
+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: 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")
+genes = [adata.var_names[res.stable_support[:, j]] for j in range(res.frequency.shape[1])]
+```
+
+Componentwise L2 boosting on its own, no autoencoder involved:
+
+```python
+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.
+
+| | |
+| --- | --- |
+| [Batch integration](https://niklasbrunn.github.io/structboost/guide/tasks/batch-integration.html) | `batch_key` names the covariate and `batch_integration_mode` chooses whether it conditions the decoder, protects gene selection, or both. `transform` stays gene-only and needs no batch labels. |
+| [Transfer](https://niklasbrunn.github.io/structboost/guide/tasks/transfer.html) | Carry a trained encoder matrix onto a new dataset with `from_reference`, aligned by gene name, with the prior programs frozen. |
+| [Persistence](https://niklasbrunn.github.io/structboost/guide/tasks/persistence.html) | `save` and `load` a fitted model as one checkpoint, readable with `weights_only=True`. |
+| [Interpretation](https://niklasbrunn.github.io/structboost/guide/tasks/interpreting.html) | Ranked gene lists per dimension, stored functional annotations, and a self-contained interactive HTML explorer. |
+| [Simulation](https://niklasbrunn.github.io/structboost/guide/tasks/simulating.html) | Negative-binomial counts with planted gene programs and a cell-type hierarchy, so marker recovery can be scored against ground truth. |
+
+## 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](https://claude.com/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.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the development setup, the versioning
+policy, and what a pull request needs. Planned work is tracked in the
+[issue tracker](https://github.com/NiklasBrunn/structboost/issues).
+
+Licensed under the [MIT License](LICENSE).

structboost-0.1.0/README.md

@@ -0,0 +1,147 @@
+# 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
+negative gradient of the reconstruction loss rather than by backpropagation.
+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)](https://doi.org/10.1038/s42003-025-07872-9),
+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](https://niklasbrunn.github.io/structboost/guide/index.html)
+next to the setting they justify. Results from this implementation should
+therefore not be assumed identical to the original paper's.
+
+📖 **[Documentation](https://niklasbrunn.github.io/structboost)** · 
+[User guide](https://niklasbrunn.github.io/structboost/guide/index.html) · 
+[API reference](https://niklasbrunn.github.io/structboost/api/index.html) · 
+[Changelog](CHANGELOG.md)
+
+## Installation
+
+Requires Python 3.10 or newer. The core depends on NumPy alone, and everything
+heavier is opt-in.
+
+```bash
+pip install "structboost[bae,plot]"     # the BAE
+pip install structboost                 # allboost only, NumPy-only
+```
+
+| Extra | Brings in | Needed for |
+| --- | --- | --- |
+| *(none)* | numpy | `allboost`, `stability_selection` |
+| `bae` | torch, anndata, scipy, pandas, tqdm | `BAE`, the simulator, everything AnnData |
+| `plot` | matplotlib | the `plot_*` functions |
+| `io` | pyarrow | Parquet encoder-weight files |
+
+Not on PyPI yet. Until it is, install from source or from TestPyPI. Pin the
+version: TestPyPI also carries older pre-release builds under this name, and an
+unpinned install resolves to one of those rather than to the current code.
+
+```bash
+pip install --index-url https://test.pypi.org/simple/ \
+            --extra-index-url https://pypi.org/simple/ "structboost[bae]==0.1.0"
+```
+
+See [Installation](https://niklasbrunn.github.io/structboost/installation.html)
+for the from-source and development setups.
+
+## Quickstart
+
+`adata.X` must be z-scored, which `sc.pp.scale` gives you.
+
+```python
+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
+```
+
+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: 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")
+genes = [adata.var_names[res.stable_support[:, j]] for j in range(res.frequency.shape[1])]
+```
+
+Componentwise L2 boosting on its own, no autoencoder involved:
+
+```python
+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.
+
+| | |
+| --- | --- |
+| [Batch integration](https://niklasbrunn.github.io/structboost/guide/tasks/batch-integration.html) | `batch_key` names the covariate and `batch_integration_mode` chooses whether it conditions the decoder, protects gene selection, or both. `transform` stays gene-only and needs no batch labels. |
+| [Transfer](https://niklasbrunn.github.io/structboost/guide/tasks/transfer.html) | Carry a trained encoder matrix onto a new dataset with `from_reference`, aligned by gene name, with the prior programs frozen. |
+| [Persistence](https://niklasbrunn.github.io/structboost/guide/tasks/persistence.html) | `save` and `load` a fitted model as one checkpoint, readable with `weights_only=True`. |
+| [Interpretation](https://niklasbrunn.github.io/structboost/guide/tasks/interpreting.html) | Ranked gene lists per dimension, stored functional annotations, and a self-contained interactive HTML explorer. |
+| [Simulation](https://niklasbrunn.github.io/structboost/guide/tasks/simulating.html) | Negative-binomial counts with planted gene programs and a cell-type hierarchy, so marker recovery can be scored against ground truth. |
+
+## 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](https://claude.com/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.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the development setup, the versioning
+policy, and what a pull request needs. Planned work is tracked in the
+[issue tracker](https://github.com/NiklasBrunn/structboost/issues).
+
+Licensed under the [MIT License](LICENSE).

structboost-0.1.0/conftest.py

@@ -0,0 +1,35 @@
+"""Reject a too-old interpreter before anything imports the package.
+
+``pythonpath = ["src", "."]`` in ``pyproject.toml`` makes pytest import this
+checkout rather than an installed copy. That is deliberate, so that a bare
+``pytest`` tests the code in front of you. It also means nothing was installed,
+so nothing enforced ``requires-python = ">=3.10"``. On an older interpreter the
+first import instead dies inside ``_boosting.py`` on a runtime ``X | Y`` union,
+with a ``TypeError`` that names the two operands and not the cause.
+
+The usual way this happens is a stale ``pytest`` sitting earlier on ``PATH`` than
+the project's own interpreter, so the message names that and the way out.
+
+This file has to stay importable on the versions it rejects: no ``X | Y``
+annotations, nothing newer than the floor below.
+"""
+
+import sys
+
+import pytest
+
+#: Keep in step with ``requires-python`` in ``pyproject.toml``.
+MIN_PYTHON = (3, 10)
+
+
+def pytest_configure(config):
+    """Abort with a readable message instead of a TypeError during collection."""
+    if sys.version_info < MIN_PYTHON:
+        wanted = ".".join(str(part) for part in MIN_PYTHON)
+        running = ".".join(str(part) for part in sys.version_info[:3])
+        raise pytest.UsageError(
+            f"structboost needs Python >= {wanted} but this pytest runs on "
+            f"{running} ({sys.executable}). A stale pytest earlier on PATH than "
+            "the project interpreter is the usual cause: run 'python -m pytest' "
+            "instead, or put the project's environment first on PATH."
+        )