structboost 0.1.0__py3-none-any.whl

structboost-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,19 @@
+structboost/__init__.py,sha256=ncxIpTmmanaAY0iYjntj7oQUYIrurIpUcsLgWORcXVk,2697
+structboost/_annotation.py,sha256=cNnI8YXvoN75mklf10lFG5EtrJChXANvJ6wdQZWB71c,7856
+structboost/_boosting.py,sha256=SCMs_J2tO5iFHS3CR2f9wrC298D42cGpUWsjVW4a5to,24713
+structboost/_decoder.py,sha256=Z40q4TxfCJYlUsxHZ1NltRRfGkpSKZIpBnagwtYcDRU,3753
+structboost/_encoder.py,sha256=FOXI4_LFyaUHs2MlGYspAzm8QPWxaCdZS0UBlt7cb6A,2781
+structboost/_explorer.py,sha256=iDUC9_3UApp0RTtraVF6alZ8s9aK0AgS3shfgErrG40,27614
+structboost/_io.py,sha256=c_2DKoujsolRGwKvUlK12N2D14Rx9MAzdergkfJr7mQ,11443
+structboost/_model.py,sha256=_seWBkhfkuVvxUO3R9_CMBbS2ZLmzHjxHQrZpRPOYN4,161703
+structboost/_persistence.py,sha256=GVN8lOfB40yUVoEHnITM-gtnon0cXu8HsgOLT7Y51bg,13929
+structboost/_plotting.py,sha256=AM5rI2o7FFS22l7pWMdfueqsohy1B9RBw_SS6dPBhno,9945
+structboost/_simulation.py,sha256=VsC37HA2B-1kPiVGFQzkV_PzOueguN1c5fiyeKsR5qE,34826
+structboost/_stability.py,sha256=vO21nKAyAlInKcZrJHw3RhHp8SwSMIey5f3-lvuwxA8,19170
+structboost/_types.py,sha256=ZIAFdUPP1te82tD11zluu91zeoCwzok4EyytveTL4QM,19908
+structboost/_utils.py,sha256=OuykUPWpW0T4xX6gGNsrS0v7IHmN1kMswj2dL6u7qGc,17936
+structboost/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+structboost-0.1.0.dist-info/METADATA,sha256=IvaliqScaFijXxIWORnleaTjfTgiTcUq0ERth6k0mfs,10029
+structboost-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+structboost-0.1.0.dist-info/licenses/LICENSE,sha256=P057TCLBWXhAiz9l2IwmOx9PZ7JMcOepMU-G5-0s7PQ,1066
+structboost-0.1.0.dist-info/RECORD,,

structboost-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

structboost-0.1.0.dist-info/licenses/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.