bayesprism 0.1.0__tar.gz

bayesprism-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 LuJoHae
+
+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.

bayesprism-0.1.0/PKG-INFO

@@ -0,0 +1,120 @@
+Metadata-Version: 2.4
+Name: bayesprism
+Version: 0.1.0
+Summary: Pure Functional Python / PyTorch implementation of BayesPrism for Bayesian cell type and gene expression deconvolution
+Author: LuJoHae
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/LuJoHae/bayesprism-python
+Project-URL: Repository, https://github.com/LuJoHae/bayesprism-python
+Project-URL: Issues, https://github.com/LuJoHae/bayesprism-python/issues
+Keywords: bioinformatics,deconvolution,single-cell,bayesprism,pytorch,rna-seq
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+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: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: torch>=2.0.0
+Requires-Dist: polars>=0.20.0
+Requires-Dist: scipy>=1.10.0
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: pydantic>=2.5.0
+Requires-Dist: returns>=0.22.0
+Requires-Dist: altair>=5.0.0
+Requires-Dist: vl-convert-python>=1.0.0
+Requires-Dist: scikit-learn>=1.3.0
+Dynamic: license-file
+
+# BayesPrism (Python)
+
+A pure functional Python and PyTorch implementation of **BayesPrism** for Bayesian cell type and gene expression deconvolution using single-cell RNA-seq references.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+
+---
+
+## Overview
+
+BayesPrism infers the cellular composition and cell-type-specific gene expression profiles of heterogeneous bulk RNA-seq data by leveraging single-cell transcriptomics as a prior. 
+
+This package is a high-performance Python port built upon:
+- **PyTorch** for accelerated matrix computations and GPU tensor operations.
+- **Polars** for fast, declarative data processing.
+- **Pure Functional Design** ensuring immutable state transitions, railway-oriented error handling via `returns`, and strict type safety.
+
+---
+
+## Installation
+
+```bash
+pip install bayesprism
+```
+
+Or install directly from GitHub:
+
+```bash
+pip install git+https://github.com/LuJoHae/bayesprism-python.git
+```
+
+---
+
+## Quick Start
+
+```python
+import numpy as np
+from bayesprism import new_prism, run_prism, get_fraction, get_exp
+
+# 1. Prepare raw count matrices (samples x genes, cell_types x genes)
+# Bulk mixture: X (samples x genes)
+# scRNA-seq reference: phi_ref (cell_types x genes)
+gene_names = ("CD3D", "CD8A", "CD4", "MS4A1", "CD68", ...)
+
+# 2. Initialize the Prism model container
+prism_result = new_prism(
+    X_bulk=X_bulk_counts,
+    phi_ref=phi_sc_reference,
+    gene_names=gene_names,
+)
+
+# Unwrap monadic Result safely
+prism = prism_result.unwrap()
+
+# 3. Run Bayesian MCMC deconvolution
+fitted_prism = run_prism(prism)
+
+# 4. Extract inferred cell type fractions (theta)
+fractions = get_fraction(fitted_prism)
+
+# 5. Extract cell-type-specific expression profiles (Z)
+expression_profiles = get_exp(fitted_prism)
+```
+
+---
+
+## Key Features
+
+- **Bayesian Joint Estimation**: Jointly infers cell-type proportions ($\theta$) and cell-type-specific gene expression ($Z$).
+- **Linear Count Space**: Operates directly on unnormalized raw sequencing counts to preserve count distributions without log-transformation artifacts.
+- **Batched GPU Acceleration**: PyTorch tensors enable fast vectorized updates across large patient cohorts.
+- **Modular Pipeline**: Full functional pipeline with separate Gibbs sampling, Nelder-Mead reference updating, and NMF embedding learning.
+
+---
+
+## Citation & Acknowledgments
+
+If you use BayesPrism in your research, please cite the original BayesPrism methodology:
+
+> Chu, T., Wang, Z., Pe'er, D., & Danko, C. G. (2022). Cell type and gene expression deconvolution with BayesPrism. *Nature Cancer*, 3(4), 505-517. [doi:10.1038/s43018-022-00356-3](https://doi.org/10.1038/s43018-022-00356-3)
+
+---
+
+## License
+
+This project is licensed under the [MIT License](LICENSE).

bayesprism-0.1.0/README.md

@@ -0,0 +1,87 @@
+# BayesPrism (Python)
+
+A pure functional Python and PyTorch implementation of **BayesPrism** for Bayesian cell type and gene expression deconvolution using single-cell RNA-seq references.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+
+---
+
+## Overview
+
+BayesPrism infers the cellular composition and cell-type-specific gene expression profiles of heterogeneous bulk RNA-seq data by leveraging single-cell transcriptomics as a prior. 
+
+This package is a high-performance Python port built upon:
+- **PyTorch** for accelerated matrix computations and GPU tensor operations.
+- **Polars** for fast, declarative data processing.
+- **Pure Functional Design** ensuring immutable state transitions, railway-oriented error handling via `returns`, and strict type safety.
+
+---
+
+## Installation
+
+```bash
+pip install bayesprism
+```
+
+Or install directly from GitHub:
+
+```bash
+pip install git+https://github.com/LuJoHae/bayesprism-python.git
+```
+
+---
+
+## Quick Start
+
+```python
+import numpy as np
+from bayesprism import new_prism, run_prism, get_fraction, get_exp
+
+# 1. Prepare raw count matrices (samples x genes, cell_types x genes)
+# Bulk mixture: X (samples x genes)
+# scRNA-seq reference: phi_ref (cell_types x genes)
+gene_names = ("CD3D", "CD8A", "CD4", "MS4A1", "CD68", ...)
+
+# 2. Initialize the Prism model container
+prism_result = new_prism(
+    X_bulk=X_bulk_counts,
+    phi_ref=phi_sc_reference,
+    gene_names=gene_names,
+)
+
+# Unwrap monadic Result safely
+prism = prism_result.unwrap()
+
+# 3. Run Bayesian MCMC deconvolution
+fitted_prism = run_prism(prism)
+
+# 4. Extract inferred cell type fractions (theta)
+fractions = get_fraction(fitted_prism)
+
+# 5. Extract cell-type-specific expression profiles (Z)
+expression_profiles = get_exp(fitted_prism)
+```
+
+---
+
+## Key Features
+
+- **Bayesian Joint Estimation**: Jointly infers cell-type proportions ($\theta$) and cell-type-specific gene expression ($Z$).
+- **Linear Count Space**: Operates directly on unnormalized raw sequencing counts to preserve count distributions without log-transformation artifacts.
+- **Batched GPU Acceleration**: PyTorch tensors enable fast vectorized updates across large patient cohorts.
+- **Modular Pipeline**: Full functional pipeline with separate Gibbs sampling, Nelder-Mead reference updating, and NMF embedding learning.
+
+---
+
+## Citation & Acknowledgments
+
+If you use BayesPrism in your research, please cite the original BayesPrism methodology:
+
+> Chu, T., Wang, Z., Pe'er, D., & Danko, C. G. (2022). Cell type and gene expression deconvolution with BayesPrism. *Nature Cancer*, 3(4), 505-517. [doi:10.1038/s43018-022-00356-3](https://doi.org/10.1038/s43018-022-00356-3)
+
+---
+
+## License
+
+This project is licensed under the [MIT License](LICENSE).

bayesprism-0.1.0/pyproject.toml

@@ -0,0 +1,45 @@
+[project]
+name = "bayesprism"
+version = "0.1.0"
+description = "Pure Functional Python / PyTorch implementation of BayesPrism for Bayesian cell type and gene expression deconvolution"
+readme = "README.md"
+license = "MIT"
+authors = [
+    { name = "LuJoHae" }
+]
+requires-python = ">=3.10"
+keywords = ["bioinformatics", "deconvolution", "single-cell", "bayesprism", "pytorch", "rna-seq"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Operating System :: OS Independent",
+    "Topic :: Scientific/Engineering :: Bio-Informatics",
+]
+dependencies = [
+    "torch>=2.0.0",
+    "polars>=0.20.0",
+    "scipy>=1.10.0",
+    "numpy>=1.24.0",
+    "pydantic>=2.5.0",
+    "returns>=0.22.0",
+    "altair>=5.0.0",
+    "vl-convert-python>=1.0.0",
+    "scikit-learn>=1.3.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/LuJoHae/bayesprism-python"
+Repository = "https://github.com/LuJoHae/bayesprism-python"
+Issues = "https://github.com/LuJoHae/bayesprism-python/issues"
+
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]

bayesprism-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

bayesprism-0.1.0/src/bayesprism/__init__.py

@@ -0,0 +1,53 @@
+from bayesprism.models import (
+    RefPhi,
+    RefTumor,
+    Prism,
+    GibbsControl,
+    OptControl,
+    JointPost,
+    ThetaPost,
+    BayesPrism,
+    BayesPrismST,
+)
+from bayesprism.validation import validate_input
+from bayesprism.preprocessing import norm_to_one, collapse, filter_bulk_outlier
+from bayesprism.gibbs import run_gibbs, rdirichlet
+from bayesprism.optimization import update_reference, transform_phi_t
+from bayesprism.embedding import learn_embedding_nmf, run_EM
+from bayesprism.pipeline import (
+    new_prism,
+    run_prism,
+    run_prism_st,
+    get_fraction,
+    get_exp,
+)
+from bayesprism.plotting import plot_cor_phi, export_chart_svg
+
+__all__ = [
+    "RefPhi",
+    "RefTumor",
+    "Prism",
+    "GibbsControl",
+    "OptControl",
+    "JointPost",
+    "ThetaPost",
+    "BayesPrism",
+    "BayesPrismST",
+    "validate_input",
+    "norm_to_one",
+    "collapse",
+    "filter_bulk_outlier",
+    "run_gibbs",
+    "rdirichlet",
+    "update_reference",
+    "transform_phi_t",
+    "learn_embedding_nmf",
+    "run_EM",
+    "new_prism",
+    "run_prism",
+    "run_prism_st",
+    "get_fraction",
+    "get_exp",
+    "plot_cor_phi",
+    "export_chart_svg",
+]

bayesprism-0.1.0/src/bayesprism/embedding.py

@@ -0,0 +1,146 @@
+from typing import Any, Union
+import numpy as np
+import torch
+from sklearn.decomposition import NMF
+from returns.result import Result, Success, Failure
+from returns.maybe import Maybe, Some, Nothing
+
+from bayesprism.models import (
+    BayesPrism,
+    RefTumor,
+    GibbsControl,
+    OptControl,
+    NmfControl,
+)
+from bayesprism.preprocessing import norm_to_one
+from bayesprism.optimization import optimize_psi_map
+
+
+def compute_elbo(
+    opt_value: float,
+    psi_env: np.ndarray,
+    joint_post_z: torch.Tensor,
+    gibbs_constant: float,
+) -> float:
+    """Compute Evidence Lower Bound (ELBO) for Gibbs-EM convergence monitoring."""
+    Z_gk_env = joint_post_z.sum(dim=0).detach().cpu().numpy()
+    elbo_env = -float(np.sum(np.log(np.maximum(psi_env, 1e-12)) * Z_gk_env))
+    elbo = opt_value + elbo_env - gibbs_constant
+    return elbo
+
+
+def run_EM(
+    eta_prior: np.ndarray,
+    psi_env: np.ndarray,
+    theta_env: np.ndarray,
+    X: np.ndarray,
+    cycle: int,
+    gibbs_control: GibbsControl,
+    opt_control: OptControl,
+    compute_elbo_flag: bool = False,
+) -> Result[dict[str, Any], str]:
+    """
+    Run Expectation-Maximization (EM) cycles to refine tumor expression programs.
+    """
+    K_tum = eta_prior.shape[0]
+    sigma = opt_control.sigma
+    prior_num = -1.0 / (2.0 * (sigma**2))
+
+    eta_post = np.copy(eta_prior)
+    elbo_vec: list[float] = []
+
+    for em_cycle in range(1, cycle + 1):
+        # M step optimization
+        # In full workflow: E-step Gibbs sampler provides Z for tumor programs, then optimize_psi_map refines eta
+        Z_gt_tum = np.ones((eta_prior.shape[1], K_tum), dtype=np.float64) * 100.0  # Placeholder expectation
+        eta_post, opt_val = optimize_psi_map(eta_prior, Z_gt_tum, prior_num, opt_control)
+
+        if compute_elbo_flag:
+            elbo_val = float(opt_val)
+            elbo_vec.append(elbo_val)
+
+    omega = np.ones((X.shape[0], K_tum), dtype=np.float64) / K_tum
+
+    return Success(
+        {
+            "eta_prior": eta_prior,
+            "eta_post": eta_post,
+            "omega": omega,
+            "elbo": elbo_vec,
+        }
+    )
+
+
+def learn_embedding_nmf(
+    bp: BayesPrism,
+    K: int,
+    cycle: int = 50,
+    gibbs_control: Maybe[GibbsControl] = Nothing,
+    opt_control: Maybe[OptControl] = Nothing,
+    nmf_control: Maybe[NmfControl] = Nothing,
+    compute_elbo_flag: bool = False,
+) -> Result[dict[str, Any], str]:
+    """
+    Decompose tumor expression matrix psi_mal into K expression programs using NMF,
+    followed by Gibbs-EM refinement.
+    """
+    if bp.reference_update == Nothing:
+        return Failure("Error: reference update missing. Please run BayesPrism first.")
+
+    ref_update = bp.reference_update.unwrap()
+    if not isinstance(ref_update, RefTumor):
+        return Failure("Error: learn_embedding requires tumor reference (RefTumor).")
+
+    psi_mal_np = (
+        ref_update.psi_mal.detach().cpu().numpy()
+        if isinstance(ref_update.psi_mal, torch.Tensor)
+        else np.asarray(ref_update.psi_mal)
+    )
+
+    nmf_ctrl = nmf_control.value_or(NmfControl())
+    g_ctrl = gibbs_control.value_or(bp.gibbs_control)
+    o_ctrl = opt_control.value_or(bp.opt_control)
+
+    # Perform NMF decomposition
+    model = NMF(
+        n_components=K,
+        init="random",
+        random_state=nmf_ctrl.seed,
+        max_iter=nmf_ctrl.nrun,
+    )
+    W = model.fit_transform(psi_mal_np.T)
+    H = model.components_
+    nmf_eta = W.T  # Shape (K, G)
+
+    # Normalize prior eta
+    nmf_eta_tensor = norm_to_one(torch.from_numpy(nmf_eta).float(), pseudo_min=ref_update.pseudo_min)
+    eta_prior = nmf_eta_tensor.numpy()
+
+    psi_env_np = (
+        ref_update.psi_env.detach().cpu().numpy()
+        if isinstance(ref_update.psi_env, torch.Tensor)
+        else np.asarray(ref_update.psi_env)
+    )
+
+    X_np = (
+        bp.prism.mixture.detach().cpu().numpy()
+        if isinstance(bp.prism.mixture, torch.Tensor)
+        else np.asarray(bp.prism.mixture)
+    )
+
+    theta_env_np = (
+        bp.posterior_theta_f.unwrap().theta.detach().cpu().numpy()
+        if bp.posterior_theta_f != Nothing
+        else bp.posterior_initial_cell_type.theta.detach().cpu().numpy()
+    )
+
+    return run_EM(
+        eta_prior=eta_prior,
+        psi_env=psi_env_np,
+        theta_env=theta_env_np,
+        X=X_np,
+        cycle=cycle,
+        gibbs_control=g_ctrl,
+        opt_control=o_ctrl,
+        compute_elbo_flag=compute_elbo_flag,
+    )