m3-sc 0.3.0__tar.gz

m3_sc-0.3.0/.gitignore

@@ -0,0 +1,32 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+
+# torch checkpoints (nothing in the package writes one, but a stray checkpoint
+# from an ad-hoc script should never be committed)
+*.pth
+build/
+dist/
+.pytest_cache/
+.ipynb_checkpoints/
+
+# R
+.Rproj.user/
+.Rhistory
+.RData
+*.tar.gz
+
+# MkDocs
+website/site/
+website/.cache/
+
+# OS
+.DS_Store
+
+# NOTE: rendered tutorials (website/docs/notebooks/*.ipynb, r_*_media/) and the
+# packaged demo data (*.h5ad under datasets/_data) are TRACKED on purpose —
+# CI builds the docs from these without re-running the models.
+
+# build cache (mkdocs-jupyter, etc.)
+.cache/

m3_sc-0.3.0/LICENSE

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

m3_sc-0.3.0/PKG-INFO

@@ -0,0 +1,98 @@
+Metadata-Version: 2.4
+Name: m3-sc
+Version: 0.3.0
+Summary: Multimodal, multi-batch, condition-aware single-cell model with donor-level disease prediction
+Project-URL: Homepage, https://github.com/PYangLab/M3
+Project-URL: Documentation, https://pyanglab.github.io/M3/
+Project-URL: Repository, https://github.com/PYangLab/M3
+Author: CSB Yang Laboratory
+License: MIT
+License-File: LICENSE
+Keywords: CITE-seq,batch-integration,deep-learning,multiomics,patient-prediction,single-cell,variational-autoencoder
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Requires-Python: >=3.10
+Requires-Dist: anndata
+Requires-Dist: captum
+Requires-Dist: h5py
+Requires-Dist: numpy
+Requires-Dist: pandas
+Requires-Dist: scanpy
+Requires-Dist: scikit-learn
+Requires-Dist: scipy
+Requires-Dist: tqdm
+Provides-Extra: dev
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# M3
+
+**M3** is a deep generative framework for **condition-aware integration**,
+**patient-level inference**, and **multi-resolution interpretation** of multimodal
+single-cell omics data across many biological conditions and samples.
+
+From one shared, condition-aware representation, M3 delivers six downstream tasks:
+factorised dimension reduction, condition-aware batch correction, mosaic
+integration + imputation, patient-level condition inference, patient/sample
+generation, and multi-resolution attribution.
+
+📖 **Documentation & tutorials:** https://pyanglab.github.io/M3/
+
+## Install
+
+### Python
+
+```bash
+pip install m3-sc      # imported as `import m3`
+```
+
+PyTorch comes along automatically. If you need a build matched to a specific CUDA
+version, install it first and pip will keep it:
+
+```bash
+pip install torch --index-url https://download.pytorch.org/whl/cu121
+pip install m3-sc
+```
+
+For the development version: `pip install "git+https://github.com/PYangLab/M3.git"`.
+
+### R
+
+```r
+install.packages("remotes")
+remotes::install_github("PYangLab/M3", subdir = "m3-r")
+```
+
+The R package provisions its own Python engine through
+[basilisk](https://bioconductor.org/packages/basilisk/) on first use — no manual
+Python / PyTorch setup, and R and Python produce identical results.
+
+## Quickstart (Python)
+
+```python
+import m3
+
+data  = m3.datasets.liu_demo()                                  # built-in demo
+model = m3.M3(data, condition_keys=["cond_group"],
+              celltype_key="mergedcelltype").train()
+emb   = model.embedding(part="bio")                             # integrated embedding
+```
+
+## Repository layout
+
+| Path | What |
+|---|---|
+| `src/m3/` | the `m3-sc` Python package (PyTorch engine vendored under `_engine/`) |
+| `m3-r/` | the R package — `library(m3)`, basilisk-wrapped, same engine |
+| `website/` | documentation site (MkDocs Material); `mkdocs serve -f website/mkdocs.yml` |
+| `.github/workflows/deploy.yml` | builds + publishes the docs to GitHub Pages |
+| `tests/` | Python test suite |
+
+## License
+
+See [LICENSE](LICENSE).

m3_sc-0.3.0/README.md

@@ -0,0 +1,66 @@
+# M3
+
+**M3** is a deep generative framework for **condition-aware integration**,
+**patient-level inference**, and **multi-resolution interpretation** of multimodal
+single-cell omics data across many biological conditions and samples.
+
+From one shared, condition-aware representation, M3 delivers six downstream tasks:
+factorised dimension reduction, condition-aware batch correction, mosaic
+integration + imputation, patient-level condition inference, patient/sample
+generation, and multi-resolution attribution.
+
+📖 **Documentation & tutorials:** https://pyanglab.github.io/M3/
+
+## Install
+
+### Python
+
+```bash
+pip install m3-sc      # imported as `import m3`
+```
+
+PyTorch comes along automatically. If you need a build matched to a specific CUDA
+version, install it first and pip will keep it:
+
+```bash
+pip install torch --index-url https://download.pytorch.org/whl/cu121
+pip install m3-sc
+```
+
+For the development version: `pip install "git+https://github.com/PYangLab/M3.git"`.
+
+### R
+
+```r
+install.packages("remotes")
+remotes::install_github("PYangLab/M3", subdir = "m3-r")
+```
+
+The R package provisions its own Python engine through
+[basilisk](https://bioconductor.org/packages/basilisk/) on first use — no manual
+Python / PyTorch setup, and R and Python produce identical results.
+
+## Quickstart (Python)
+
+```python
+import m3
+
+data  = m3.datasets.liu_demo()                                  # built-in demo
+model = m3.M3(data, condition_keys=["cond_group"],
+              celltype_key="mergedcelltype").train()
+emb   = model.embedding(part="bio")                             # integrated embedding
+```
+
+## Repository layout
+
+| Path | What |
+|---|---|
+| `src/m3/` | the `m3-sc` Python package (PyTorch engine vendored under `_engine/`) |
+| `m3-r/` | the R package — `library(m3)`, basilisk-wrapped, same engine |
+| `website/` | documentation site (MkDocs Material); `mkdocs serve -f website/mkdocs.yml` |
+| `.github/workflows/deploy.yml` | builds + publishes the docs to GitHub Pages |
+| `tests/` | Python test suite |
+
+## License
+
+See [LICENSE](LICENSE).

m3_sc-0.3.0/pyproject.toml

@@ -0,0 +1,63 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "m3-sc"
+# Single source of truth: src/m3/__init__.py (see [tool.hatch.version] below)
+dynamic = ["version"]
+description = "Multimodal, multi-batch, condition-aware single-cell model with donor-level disease prediction"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "CSB Yang Laboratory" }]
+keywords = [
+    "single-cell", "multiomics", "CITE-seq", "batch-integration",
+    "patient-prediction", "variational-autoencoder", "deep-learning",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Topic :: Scientific/Engineering :: Bio-Informatics",
+]
+# torch arrives transitively via captum, so `pip install m3-sc` works unaided.
+# Only users who need a specific CUDA build install torch themselves first.
+dependencies = [
+    "numpy",
+    "scipy",
+    "pandas",
+    "anndata",
+    "h5py",
+    "scikit-learn",
+    "scanpy",
+    "tqdm",
+    "captum",
+]
+
+[project.optional-dependencies]
+dev = ["pytest", "ruff"]
+
+[project.urls]
+Homepage = "https://github.com/PYangLab/M3"
+Documentation = "https://pyanglab.github.io/M3/"
+Repository = "https://github.com/PYangLab/M3"
+
+[tool.hatch.version]
+path = "src/m3/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/m3"]
+
+[tool.hatch.build.targets.sdist]
+include = ["/src/m3", "/tests", "/README.md", "/LICENSE", "/pyproject.toml"]
+
+[tool.pytest.ini_options]
+addopts = "-q"
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+extend-exclude = ["src/m3/_engine"]

m3_sc-0.3.0/src/m3/__init__.py

@@ -0,0 +1,29 @@
+"""m3 -- multimodal, multi-batch, condition-aware single-cell model."""
+
+from m3.io import read_matrix, from_anndata, read_h5ad, read_h5
+from m3._concat import concat
+from m3 import datasets
+
+__version__ = "0.3.0"
+
+__all__ = [
+    "read_matrix", "from_anndata", "read_h5ad", "read_h5", "concat",
+    "M3", "Attribution", "M3CapabilityError",
+    "datasets",
+]
+
+# The model and its readouts need torch; import them lazily so that `import m3`
+# and the torch-free readers (io) and bundled datasets stay usable without a
+# torch install. Accessing m3.M3 (etc.) triggers the torch-backed import.
+_LAZY = {"M3", "Attribution", "M3CapabilityError"}
+
+
+def __getattr__(name):
+    if name in _LAZY:
+        from m3 import _model
+        return getattr(_model, name)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+def __dir__():
+    return sorted(__all__)

m3_sc-0.3.0/src/m3/_bridge.py

@@ -0,0 +1,77 @@
+"""Bridge: marshal a :class:`m3.Dataset` to the engine's file-based inputs.
+
+The engine (``m3._engine.run_M3``) consumes per-modality lists of
+paper-format HDF5 files (one element per batch, ``None`` where a batch lacks a
+modality) plus a per-batch metadata CSV list. This module writes those temp
+files from an in-memory ``Dataset`` so the proven engine path runs unchanged.
+
+Paper HDF5 layout (what ``m3._engine.util.read_h5_data`` expects):
+``matrix/data`` is genes x cells (transpose of our cells x genes), and
+``matrix/features`` holds the feature names.
+"""
+
+from __future__ import annotations
+
+import os
+import tempfile
+
+import h5py
+import numpy as np
+
+_MODALITY_ORDER = ("rna", "adt", "atac")  # maps to engine modality1/2/3_path
+
+
+def _write_paper_h5(path: str, counts_cells_by_features, feature_names) -> None:
+    dense = np.asarray(counts_cells_by_features.todense()
+                       if hasattr(counts_cells_by_features, "todense")
+                       else counts_cells_by_features, dtype=np.float32)
+    # Store cells x features (the Liu/Stephenson layout). The engine's
+    # read_h5_data + load_data_from_list double-transpose nets back to cells x features.
+    with h5py.File(path, "w") as f:
+        g = f.create_group("matrix")
+        g.create_dataset("data", data=dense)
+        g.create_dataset("features", data=np.array([str(x) for x in feature_names], dtype="S"))
+
+
+def marshal(dataset, tmpdir: str | None = None) -> dict:
+    """Write a Dataset to temp paper-format h5 + metadata CSVs.
+
+    Returns a dict with:
+      modality_paths: {"rna": [path|None per batch], "adt": [...], "atac": [...]}
+      metadata_paths: [csv path per batch]
+      batches: ordered batch labels (row order of the engine's concatenation)
+      tmpdir: the directory holding the temp files (caller may clean up)
+    """
+    if tmpdir is None:
+        tmpdir = tempfile.mkdtemp(prefix="m3_marshal_")
+    os.makedirs(tmpdir, exist_ok=True)
+
+    obs = dataset.obs
+    batches = list(dataset.batches)
+    batch_rows = {c: (obs["batch"].to_numpy() == c) for c in batches}
+
+    modality_paths: dict[str, list] = {m: [] for m in _MODALITY_ORDER}
+    metadata_paths: list[str] = []
+
+    for ci, c in enumerate(batches):
+        rows = batch_rows[c]
+        # metadata CSV for this batch (engine reads with pandas; needs the role columns)
+        meta_path = os.path.join(tmpdir, f"metadata_{ci}.csv")
+        obs.loc[rows].reset_index(drop=True).to_csv(meta_path, index=False)
+        metadata_paths.append(meta_path)
+
+        for m in _MODALITY_ORDER:
+            if m in dataset.modalities and bool(dataset.present[m][rows].any()):
+                mat = dataset.modalities[m][rows]
+                path = os.path.join(tmpdir, f"{m}_{ci}.h5")
+                _write_paper_h5(path, mat, dataset.var[m])
+                modality_paths[m].append(path)
+            else:
+                modality_paths[m].append(None)
+
+    return {
+        "modality_paths": modality_paths,
+        "metadata_paths": metadata_paths,
+        "batches": batches,
+        "tmpdir": tmpdir,
+    }

m3_sc-0.3.0/src/m3/_concat.py

@@ -0,0 +1,72 @@
+"""Multi-batch assembly: stack single-batch Datasets into one."""
+
+from __future__ import annotations
+
+import warnings
+
+import numpy as np
+import pandas as pd
+import scipy.sparse as sp
+
+from m3._dataset import Dataset
+
+
+def _intersect_ordered(indices: list[pd.Index]) -> pd.Index:
+    common = set(indices[0])
+    for idx in indices[1:]:
+        common &= set(idx)
+    # stable order: follow the first batch's ordering
+    return pd.Index([g for g in indices[0] if g in common])
+
+
+def concat(datasets: list[Dataset]) -> Dataset:
+    """Combine single-batch Datasets into one multi-batch Dataset.
+
+    - features per modality are harmonized by NAME intersection (first batch's order)
+    - a batch missing a whole modality is zero-filled with present[modality]=False
+    - batch labels must be unique across inputs
+    """
+    if not datasets:
+        raise ValueError("concat requires at least one Dataset.")
+    if len(datasets) == 1:
+        return datasets[0]
+
+    labels = [c for d in datasets for c in d.batches]
+    if len(labels) != len(set(labels)):
+        raise ValueError(f"batch labels must be unique across inputs; got {labels}.")
+
+    all_mods = sorted({m for d in datasets for m in d.modality_names})
+    n_total = sum(d.n_cells for d in datasets)
+
+    out_mods: dict[str, sp.csr_matrix] = {}
+    out_var: dict[str, pd.Index] = {}
+    out_present: dict[str, np.ndarray] = {}
+
+    for mod in all_mods:
+        carriers = [d for d in datasets if mod in d.modalities]
+        common = _intersect_ordered([d.var[mod] for d in carriers])
+        if len(common) == 0:
+            raise ValueError(f"modality '{mod}': empty feature intersection across batches.")
+        if any(len(common) < len(d.var[mod]) for d in carriers):
+            warnings.warn(
+                f"modality '{mod}': intersection kept {len(common)} features "
+                f"(batches had {[len(d.var[mod]) for d in carriers]}).",
+                stacklevel=2,
+            )
+        blocks = []
+        present = []
+        for d in datasets:
+            if mod in d.modalities:
+                col_pos = [d.var[mod].get_loc(g) for g in common]
+                blocks.append(d.modalities[mod][:, col_pos])
+                present.append(np.ones(d.n_cells, dtype=bool))
+            else:
+                blocks.append(sp.csr_matrix((d.n_cells, len(common)), dtype=np.float32))
+                present.append(np.zeros(d.n_cells, dtype=bool))
+        out_mods[mod] = sp.vstack(blocks).tocsr()
+        out_var[mod] = common
+        out_present[mod] = np.concatenate(present)
+
+    obs = pd.concat([d.obs for d in datasets], ignore_index=True)
+    assert obs.shape[0] == n_total
+    return Dataset(modalities=out_mods, obs=obs, var=out_var, present=out_present)

m3_sc-0.3.0/src/m3/_dataset.py

@@ -0,0 +1,63 @@
+"""Canonical m3 input container."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import numpy as np
+import pandas as pd
+import scipy.sparse as sp
+
+
+@dataclass
+class Dataset:
+    """Multimodal, multi-batch raw-count container.
+
+    modalities: {name -> csr_matrix [n_cells, n_features]} raw counts
+    obs:        DataFrame [n_cells, ...]; must contain a 'batch' column
+    var:        {name -> pd.Index of feature names}, aligned to each modality's columns
+    present:    {name -> bool ndarray [n_cells]} per-cell modality presence
+    """
+
+    modalities: dict[str, sp.csr_matrix]
+    obs: pd.DataFrame
+    var: dict[str, pd.Index]
+    present: dict[str, np.ndarray]
+
+    def __post_init__(self) -> None:
+        if not self.modalities:
+            raise ValueError("Dataset requires at least one modality.")
+        n = self.obs.shape[0]
+        if "batch" not in self.obs.columns:
+            raise ValueError("obs must contain a 'batch' column.")
+        for name, mat in self.modalities.items():
+            if mat.shape[0] != n:
+                raise ValueError(
+                    f"modality '{name}' has {mat.shape[0]} rows but obs has {n} (n_cells)."
+                )
+            if name not in self.var or len(self.var[name]) != mat.shape[1]:
+                raise ValueError(
+                    f"var['{name}'] length must equal modality '{name}' column count."
+                )
+            if pd.Index(self.var[name]).has_duplicates:
+                raise ValueError(
+                    f"var['{name}'] has duplicate feature names; names must be unique."
+                )
+            if name not in self.present or self.present[name].shape[0] != n:
+                raise ValueError(f"present['{name}'] must be a length-{n} boolean array.")
+
+    @property
+    def n_cells(self) -> int:
+        return self.obs.shape[0]
+
+    @property
+    def modality_names(self) -> list[str]:
+        return list(self.modalities.keys())
+
+    @property
+    def batches(self) -> list[str]:
+        return list(pd.unique(self.obs["batch"]))
+
+    def __repr__(self) -> str:
+        mods = ", ".join(f"{k}:{v.shape[1]}" for k, v in self.modalities.items())
+        return f"Dataset(n_cells={self.n_cells}, batches={self.batches}, modalities=[{mods}])"

m3_sc-0.3.0/src/m3/_engine/__init__.py

@@ -0,0 +1,4 @@
+"""Not part of the public API. The user-facing :class:`m3.M3` orchestrates these
+modules. Modules keep their original relative imports (``from .util import ...``)
+and run unchanged; only their location moved into the ``m3._engine`` package.
+"""