sonata-learn 0.1.0__tar.gz

sonata_learn-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Park Lab at Harvard Medical School
+
+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.

sonata_learn-0.1.0/PKG-INFO

@@ -0,0 +1,114 @@
+Metadata-Version: 2.4
+Name: sonata-learn
+Version: 0.1.0
+Summary: A Python toolkit for fitting and analyzing mutational signatures
+License-Expression: MIT
+License-File: LICENSE
+Keywords: AnnData,bioinformatics,cancer genomics,mutational signatures,NMF
+Author: Benedikt Geiger
+Author-email: benedikt_geiger@g.harvard.edu
+Maintainer: Benedikt Geiger
+Maintainer-email: benedikt_geiger@g.harvard.edu
+Requires-Python: >=3.10,<3.14
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Requires-Dist: adjustText (>=1.3,<2)
+Requires-Dist: anndata (>=0.11,<0.13)
+Requires-Dist: fastcluster (>=1.2.6,<2)
+Requires-Dist: matplotlib (>=3.8,<4)
+Requires-Dist: numba (>=0.61,<0.63)
+Requires-Dist: numpy (>=1.26,<3)
+Requires-Dist: pandas (>=2.2,<3)
+Requires-Dist: scikit-learn (>=1.6,<2)
+Requires-Dist: scipy (>=1.13,<2)
+Requires-Dist: seaborn (>=0.13,<0.14)
+Requires-Dist: umap-learn (>=0.5.7,<0.6)
+Project-URL: Documentation, https://github.com/parklab/Sonata/blob/main/docs/tutorial.md
+Project-URL: Homepage, https://github.com/parklab/Sonata
+Project-URL: Repository, https://github.com/parklab/Sonata
+Description-Content-Type: text/markdown
+
+# Sonata
+
+[![Python versions supported][python-image]][python-url]
+[![License][license-image]][license-url]
+[![Code style][style-image]][style-url]
+
+[python-image]: https://img.shields.io/badge/python-3.10%20|%203.11%20|%203.12%20|%203.13-blue.svg
+[python-url]: https://github.com/parklab/Sonata
+[license-image]: https://img.shields.io/badge/License-MIT-yellow.svg
+[license-url]: https://github.com/parklab/Sonata/blob/main/LICENSE
+[style-image]: https://img.shields.io/badge/code%20style-black-000000.svg
+[style-url]: https://github.com/psf/black
+
+Sonata is a Python toolkit for fitting and analyzing mutational signatures. It
+fits signatures and exposures in
+[AnnData](https://anndata.readthedocs.io/en/latest/) objects and provides
+analysis and plotting APIs for signature workflows.
+
+## Installation
+
+```bash
+pip install sonata-learn
+```
+
+The package is installed as `sonata-learn` and imported as `sonata`.
+
+## Quickstart
+
+```python
+import sonata as so
+
+model = so.models.NMF(n_signatures=6)
+model.fit(adata)
+
+so.pl.barplot(model.asignatures)
+so.pl.stacked_barplot(model.exposures)
+
+so.tl.reduce_dimension(
+    model.adata,
+    basis="exposures",
+    method="umap",
+)
+so.pl.embedding(model.adata, basis="umap")
+```
+
+## Data Format
+
+Sonata expects mutation counts in an `AnnData` object:
+
+- `adata.X`: count matrix with shape `n_samples x n_mutation_types`.
+- `adata.obs`: optional sample annotations.
+- `adata.var`: optional mutation-type annotations.
+
+After fitting, the model stores learned signatures in `model.asignatures` and
+sample exposures in `model.adata.obsm["exposures"]`.
+
+## Documentation
+
+For a complete workflow covering data preparation, NMF, visualization,
+fixed signatures, Cornet, and simple model selection, see the
+[Markdown tutorial][tutorial-md]. A runnable notebook with the same analysis and
+figure-generation code is available at [docs/tutorial.ipynb][tutorial-ipynb].
+
+## Models
+
+Sonata currently exposes three algorithms:
+
+- `so.models.NMF`: NMF with the generalized Kullback-Leibler divergence.
+- `so.models.MvNMF`: minimum-volume NMF.
+- `so.models.Cornet`: correlated NMF with joint sample and signature embeddings.
+
+## License
+
+MIT
+
+[tutorial-md]: https://github.com/parklab/Sonata/blob/main/docs/tutorial.md
+[tutorial-ipynb]: https://github.com/parklab/Sonata/blob/main/docs/tutorial.ipynb
+

sonata_learn-0.1.0/README.md

@@ -0,0 +1,77 @@
+# Sonata
+
+[![Python versions supported][python-image]][python-url]
+[![License][license-image]][license-url]
+[![Code style][style-image]][style-url]
+
+[python-image]: https://img.shields.io/badge/python-3.10%20|%203.11%20|%203.12%20|%203.13-blue.svg
+[python-url]: https://github.com/parklab/Sonata
+[license-image]: https://img.shields.io/badge/License-MIT-yellow.svg
+[license-url]: https://github.com/parklab/Sonata/blob/main/LICENSE
+[style-image]: https://img.shields.io/badge/code%20style-black-000000.svg
+[style-url]: https://github.com/psf/black
+
+Sonata is a Python toolkit for fitting and analyzing mutational signatures. It
+fits signatures and exposures in
+[AnnData](https://anndata.readthedocs.io/en/latest/) objects and provides
+analysis and plotting APIs for signature workflows.
+
+## Installation
+
+```bash
+pip install sonata-learn
+```
+
+The package is installed as `sonata-learn` and imported as `sonata`.
+
+## Quickstart
+
+```python
+import sonata as so
+
+model = so.models.NMF(n_signatures=6)
+model.fit(adata)
+
+so.pl.barplot(model.asignatures)
+so.pl.stacked_barplot(model.exposures)
+
+so.tl.reduce_dimension(
+    model.adata,
+    basis="exposures",
+    method="umap",
+)
+so.pl.embedding(model.adata, basis="umap")
+```
+
+## Data Format
+
+Sonata expects mutation counts in an `AnnData` object:
+
+- `adata.X`: count matrix with shape `n_samples x n_mutation_types`.
+- `adata.obs`: optional sample annotations.
+- `adata.var`: optional mutation-type annotations.
+
+After fitting, the model stores learned signatures in `model.asignatures` and
+sample exposures in `model.adata.obsm["exposures"]`.
+
+## Documentation
+
+For a complete workflow covering data preparation, NMF, visualization,
+fixed signatures, Cornet, and simple model selection, see the
+[Markdown tutorial][tutorial-md]. A runnable notebook with the same analysis and
+figure-generation code is available at [docs/tutorial.ipynb][tutorial-ipynb].
+
+## Models
+
+Sonata currently exposes three algorithms:
+
+- `so.models.NMF`: NMF with the generalized Kullback-Leibler divergence.
+- `so.models.MvNMF`: minimum-volume NMF.
+- `so.models.Cornet`: correlated NMF with joint sample and signature embeddings.
+
+## License
+
+MIT
+
+[tutorial-md]: https://github.com/parklab/Sonata/blob/main/docs/tutorial.md
+[tutorial-ipynb]: https://github.com/parklab/Sonata/blob/main/docs/tutorial.ipynb

sonata_learn-0.1.0/pyproject.toml

@@ -0,0 +1,70 @@
+[project]
+name = "sonata-learn"
+version = "0.1.0"
+description = "A Python toolkit for fitting and analyzing mutational signatures"
+readme = "README.md"
+requires-python = ">=3.10,<3.14"
+license = "MIT"
+authors = [
+    { name = "Benedikt Geiger", email = "benedikt_geiger@g.harvard.edu" },
+]
+maintainers = [
+    { name = "Benedikt Geiger", email = "benedikt_geiger@g.harvard.edu" },
+]
+keywords = [
+    "AnnData",
+    "bioinformatics",
+    "cancer genomics",
+    "mutational signatures",
+    "NMF",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Bio-Informatics",
+]
+dependencies = [
+    "adjustText>=1.3,<2",
+    "anndata>=0.11,<0.13",
+    "fastcluster>=1.2.6,<2",
+    "matplotlib>=3.8,<4",
+    "numba>=0.61,<0.63",
+    "numpy>=1.26,<3",
+    "pandas>=2.2,<3",
+    "scikit-learn>=1.6,<2",
+    "scipy>=1.13,<2",
+    "seaborn>=0.13,<0.14",
+    "umap-learn>=0.5.7,<0.6",
+]
+
+[project.urls]
+Homepage = "https://github.com/parklab/Sonata"
+Repository = "https://github.com/parklab/Sonata"
+Documentation = "https://github.com/parklab/Sonata/blob/main/docs/tutorial.md"
+
+[tool.poetry]
+packages = [{ include = "sonata", from = "src" }]
+
+[tool.poetry.group.dev.dependencies]
+mypy = ">=1.15,<2"
+pandas-stubs = ">=2.2,<3"
+pytest = ">=8.3,<9"
+pre-commit = ">=4.2,<5"
+tox = ">=4.25,<5"
+types-seaborn = ">=0.13,<0.14"
+twine = "^6.2.0"
+
+[tool.pytest.ini_options]
+# /site-packages/umap/__init__.py:36: DeprecationWarning: pkg_resources is deprecated as an API.
+filterwarnings = [
+    "ignore::DeprecationWarning:umap.*:",
+]
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"

sonata_learn-0.1.0/src/sonata/__init__.py

@@ -0,0 +1,19 @@
+"""
+Sonata: a non-negative matrix factorization toolkit for signature analysis
+==========================================================================
+"""
+
+from . import models
+from . import plot as pl
+from . import tools as tl
+
+__version__ = "0.1.0"
+
+pl.set_sonata_style()
+
+__all__ = [
+    "__version__",
+    "models",
+    "pl",
+    "tl",
+]

sonata_learn-0.1.0/src/sonata/consts.py

@@ -0,0 +1,95 @@
+from matplotlib.colors import LinearSegmentedColormap
+
+NUCLEOTIDES = ["A", "C", "G", "T"]
+
+SBS_TYPES_6 = ["C>A", "C>G", "C>T", "T>A", "T>C", "T>G"]
+SBS_TYPES_96 = [
+    f"{n1}[{sbs_6}]{n2}"
+    for sbs_6 in SBS_TYPES_6
+    for n1 in NUCLEOTIDES
+    for n2 in NUCLEOTIDES
+]
+
+# fmt: off
+INDEL_TYPES_83 = [
+    "DEL.C.1.1", "DEL.C.1.2", 'DEL.C.1.3', "DEL.C.1.4", "DEL.C.1.5", "DEL.C.1.6+",
+    "DEL.T.1.1", "DEL.T.1.2", 'DEL.T.1.3', "DEL.T.1.4", "DEL.T.1.5", "DEL.T.1.6+",
+    "INS.C.1.0", "INS.C.1.1", 'INS.C.1.2', "INS.C.1.3", "INS.C.1.4", "INS.C.1.5+",
+    "INS.T.1.0", "INS.T.1.1", 'INS.T.1.2', "INS.T.1.3", "INS.T.1.4", "INS.T.1.5+",
+    "DEL.repeats.2.1", "DEL.repeats.2.2", "DEL.repeats.2.3",
+    "DEL.repeats.2.4", "DEL.repeats.2.5", "DEL.repeats.2.6+",
+    "DEL.repeats.3.1", "DEL.repeats.3.2", "DEL.repeats.3.3",
+    "DEL.repeats.3.4", "DEL.repeats.3.5", "DEL.repeats.3.6+",
+    "DEL.repeats.4.1", "DEL.repeats.4.2", "DEL.repeats.4.3",
+    "DEL.repeats.4.4", "DEL.repeats.4.5", "DEL.repeats.4.6+",
+    "DEL.repeats.5+.1", "DEL.repeats.5+.2", "DEL.repeats.5+.3",
+    "DEL.repeats.5+.4", "DEL.repeats.5+.5", "DEL.repeats.5+.6+",
+    "INS.repeats.2.0", "INS.repeats.2.1", "INS.repeats.2.2",
+    "INS.repeats.2.3", "INS.repeats.2.4", "INS.repeats.2.5+",
+    "INS.repeats.3.0", "INS.repeats.3.1", "INS.repeats.3.2",
+    "INS.repeats.3.3", "INS.repeats.3.4", "INS.repeats.3.5+",
+    "INS.repeats.4.0", "INS.repeats.4.1", "INS.repeats.4.2",
+    "INS.repeats.4.3", "INS.repeats.4.4", "INS.repeats.4.5+",
+    "INS.repeats.5+.0", "INS.repeats.5+.1", "INS.repeats.5+.2",
+    "INS.repeats.5+.3", "INS.repeats.5+.4", "INS.repeats.5+.5+",
+    "DEL.MH.2.1",
+    "DEL.MH.3.1", "DEL.MH.3.2",
+    "DEL.MH.4.1", "DEL.MH.4.2", "DEL.MH.4.3",
+    "DEL.MH.5+.1", "DEL.MH.5+.2", "DEL.MH.5+.3", "DEL.MH.5+.4", "DEL.MH.5+.5+"
+]
+# fmt: on
+
+# 10 colors
+COLORS_MATHEMATICA = [
+    (0.368417, 0.506779, 0.709798),
+    (0.880722, 0.611041, 0.142051),
+    (0.560181, 0.691569, 0.194885),
+    (0.922526, 0.385626, 0.209179),
+    (0.528288, 0.470624, 0.701351),
+    (0.772079, 0.431554, 0.102387),
+    (0.363898, 0.618501, 0.782349),
+    (1.0, 0.75, 0.0),
+    (0.280264, 0.715, 0.429209),
+    (0.0, 0.0, 0.0),
+]
+
+# Trinucleotide colors for the 96 dimensional mutation spectrum
+COLORS_TRINUCLEOTIDES = [
+    "#427aa1ff",
+    (0.0, 0.0, 0.0),
+    "#d1664aff",
+    (0.78, 0.78, 0.78),
+    "#64b3aaff",
+    (0.89, 0.67, 0.72),
+]
+
+COLORS_SBS96 = [COLORS_TRINUCLEOTIDES[i // 16] for i in range(96)]
+
+DIVERGING_PALETTE = LinearSegmentedColormap.from_list(
+    "sonata_diverging",
+    ["#427aa1ff", "#FAFAFA", "#e07a5fff"],
+)
+
+COLORS_INDEL = [
+    "#FCBD6F",  # 1bp Del C
+    "#FD8001",  # 1bp Del T
+    "#B0DC8B",  # 1bp Ins C
+    "#35A02E",  # 1bp Ins T
+    "#FCC9B4",  # 2bp Del Repeats
+    "#FC896B",  # 3bp Del Repeats
+    "#F04432",  # 4bp Del Repeats
+    "#BC1A1A",  # 5+ bp Del Repeats
+    "#CFE0F0",  # 2bp Ins Repeats
+    "#94C3DF",  # 3bp Ins Repeats
+    "#4A98C8",  # 4bp Ins Repeats
+    "#1665AA",  # 5+ bp Ins Repeats
+    "#E1E0ED",  # 2bp Del MH
+    "#B5B5D8",  # 3bp Del MH
+    "#8683BC",  # 4bp Del MH
+    "#624099",  # 5+bp Del MH
+]
+
+# 12 * 6 + 11 = 83 colors
+n_times = 12 * [6] + [1, 2, 3, 5]
+COLORS_INDEL83 = [n * [col] for n, col in zip(n_times, COLORS_INDEL)]
+COLORS_INDEL83 = [col for color_list in COLORS_INDEL83 for col in color_list]

sonata_learn-0.1.0/src/sonata/initialization/__init__.py

@@ -0,0 +1 @@
+""""""