isovae 0.1.0__tar.gz

isovae-0.1.0/LICENSE

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

isovae-0.1.0/PKG-INFO

@@ -0,0 +1,125 @@
+Metadata-Version: 2.4
+Name: isovae
+Version: 0.1.0
+Summary: IsoVAE: isoform-usage prediction and long-read isoform-usage denoising for single-cell RNA-seq
+Author: IsoVAE developers
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/your-username/IsoVAE
+Project-URL: Documentation, https://your-username.github.io/IsoVAE/
+Project-URL: Repository, https://github.com/your-username/IsoVAE
+Project-URL: Issues, https://github.com/your-username/IsoVAE/issues
+Keywords: single-cell RNA-seq,isoform usage,long-read RNA-seq,variational autoencoder,denoising
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.23
+Requires-Dist: pandas>=1.5
+Requires-Dist: scipy>=1.9
+Requires-Dist: scikit-learn>=1.2
+Requires-Dist: anndata>=0.9
+Requires-Dist: torch>=2.0
+Requires-Dist: matplotlib>=3.6
+Requires-Dist: seaborn>=0.12
+Provides-Extra: docs
+Requires-Dist: mkdocs>=1.5; extra == "docs"
+Requires-Dist: mkdocs-material>=9.5; extra == "docs"
+Requires-Dist: mkdocstrings[python]>=0.24; extra == "docs"
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Dynamic: license-file
+
+# IsoVAE
+
+IsoVAE is a Python package for single-cell isoform-usage analysis. It supports:
+
+1. **Isoform-usage prediction** from short-read single-cell gene-expression profiles.
+2. **Long-read isoform-usage denoising** from sparse long-read isoform count matrices.
+
+IsoVAE models **within-gene isoform usage proportions**, not absolute transcript abundance.
+
+## Installation
+
+```bash
+pip install isovae
+```
+
+For local development:
+
+```bash
+git clone https://github.com/your-username/IsoVAE.git
+cd IsoVAE
+pip install -e .
+```
+
+## Quick start
+
+```python
+import scanpy as sc
+from isovae import (
+    load_artifact,
+    reconstruct_preprocessor_from_training_data,
+    predict_isoform_usage,
+    denoise_isoform_usage,
+)
+
+model_path = "path/to/vae_xda_model.pt"
+
+gene_train = sc.read("path/to/training_gene_matrix.h5ad")
+iso_train = sc.read("path/to/training_isoform_matrix.h5ad")
+
+preprocessor = reconstruct_preprocessor_from_training_data(
+    model_path,
+    adata_gene_train=gene_train,
+    adata_iso_train=iso_train,
+    seed=42,
+)
+
+artifact = load_artifact(model_path, preprocessor=preprocessor, device="cpu")
+
+# Predict isoform usage from short-read data.
+gene_query = sc.read("path/to/query_gene_matrix.h5ad")
+pred_usage, pred_meta = predict_isoform_usage(artifact, gene_query)
+pred_usage.to_csv("predicted_isoform_usage.csv")
+
+# Denoise long-read isoform usage.
+iso_query = sc.read("path/to/query_isoform_matrix.h5ad")
+denoised_usage, noisy_usage, denoise_meta = denoise_isoform_usage(artifact, iso_query)
+denoised_usage.to_csv("denoised_isoform_usage.csv")
+```
+
+## Documentation
+
+The documentation source is in `docs/` and can be built with MkDocs:
+
+```bash
+pip install -e ".[docs]"
+mkdocs serve
+```
+
+To deploy to GitHub Pages:
+
+```bash
+mkdocs gh-deploy
+```
+
+See `docs/deployment.md` for deployment instructions for GitHub Pages, Read the Docs, Netlify and Vercel.
+
+## Repository layout
+
+```text
+.
+├── src/isovae/        # Python package
+├── docs/              # Documentation source
+├── mkdocs.yml         # Documentation configuration
+├── pyproject.toml     # Package metadata
+├── requirements.txt
+├── LICENSE
+└── README.md
+```
+
+Large data files, AnnData objects, model checkpoints and manuscript outputs are not included in the package.
+
+## Citation
+
+If you use IsoVAE, please cite the accompanying manuscript after publication.

isovae-0.1.0/README.md

@@ -0,0 +1,94 @@
+# IsoVAE
+
+IsoVAE is a Python package for single-cell isoform-usage analysis. It supports:
+
+1. **Isoform-usage prediction** from short-read single-cell gene-expression profiles.
+2. **Long-read isoform-usage denoising** from sparse long-read isoform count matrices.
+
+IsoVAE models **within-gene isoform usage proportions**, not absolute transcript abundance.
+
+## Installation
+
+```bash
+pip install isovae
+```
+
+For local development:
+
+```bash
+git clone https://github.com/your-username/IsoVAE.git
+cd IsoVAE
+pip install -e .
+```
+
+## Quick start
+
+```python
+import scanpy as sc
+from isovae import (
+    load_artifact,
+    reconstruct_preprocessor_from_training_data,
+    predict_isoform_usage,
+    denoise_isoform_usage,
+)
+
+model_path = "path/to/vae_xda_model.pt"
+
+gene_train = sc.read("path/to/training_gene_matrix.h5ad")
+iso_train = sc.read("path/to/training_isoform_matrix.h5ad")
+
+preprocessor = reconstruct_preprocessor_from_training_data(
+    model_path,
+    adata_gene_train=gene_train,
+    adata_iso_train=iso_train,
+    seed=42,
+)
+
+artifact = load_artifact(model_path, preprocessor=preprocessor, device="cpu")
+
+# Predict isoform usage from short-read data.
+gene_query = sc.read("path/to/query_gene_matrix.h5ad")
+pred_usage, pred_meta = predict_isoform_usage(artifact, gene_query)
+pred_usage.to_csv("predicted_isoform_usage.csv")
+
+# Denoise long-read isoform usage.
+iso_query = sc.read("path/to/query_isoform_matrix.h5ad")
+denoised_usage, noisy_usage, denoise_meta = denoise_isoform_usage(artifact, iso_query)
+denoised_usage.to_csv("denoised_isoform_usage.csv")
+```
+
+## Documentation
+
+The documentation source is in `docs/` and can be built with MkDocs:
+
+```bash
+pip install -e ".[docs]"
+mkdocs serve
+```
+
+To deploy to GitHub Pages:
+
+```bash
+mkdocs gh-deploy
+```
+
+See `docs/deployment.md` for deployment instructions for GitHub Pages, Read the Docs, Netlify and Vercel.
+
+## Repository layout
+
+```text
+.
+├── src/isovae/        # Python package
+├── docs/              # Documentation source
+├── mkdocs.yml         # Documentation configuration
+├── pyproject.toml     # Package metadata
+├── requirements.txt
+├── LICENSE
+└── README.md
+```
+
+Large data files, AnnData objects, model checkpoints and manuscript outputs are not included in the package.
+
+## Citation
+
+If you use IsoVAE, please cite the accompanying manuscript after publication.

isovae-0.1.0/pyproject.toml

@@ -0,0 +1,54 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "isovae"
+version = "0.1.0"
+description = "IsoVAE: isoform-usage prediction and long-read isoform-usage denoising for single-cell RNA-seq"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [
+  {name = "IsoVAE developers"}
+]
+keywords = [
+  "single-cell RNA-seq",
+  "isoform usage",
+  "long-read RNA-seq",
+  "variational autoencoder",
+  "denoising"
+]
+dependencies = [
+  "numpy>=1.23",
+  "pandas>=1.5",
+  "scipy>=1.9",
+  "scikit-learn>=1.2",
+  "anndata>=0.9",
+  "torch>=2.0",
+  "matplotlib>=3.6",
+  "seaborn>=0.12"
+]
+
+[project.optional-dependencies]
+docs = [
+  "mkdocs>=1.5",
+  "mkdocs-material>=9.5",
+  "mkdocstrings[python]>=0.24"
+]
+dev = [
+  "pytest",
+  "ruff"
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.ruff]
+line-length = 100
+
+[project.urls]
+Homepage = "https://github.com/your-username/IsoVAE"
+Documentation = "https://your-username.github.io/IsoVAE/"
+Repository = "https://github.com/your-username/IsoVAE"
+Issues = "https://github.com/your-username/IsoVAE/issues"

isovae-0.1.0/setup.cfg

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

isovae-0.1.0/src/isovae/__init__.py

@@ -0,0 +1,39 @@
+"""IsoVAE public API.
+
+IsoVAE predicts gene-wise isoform usage from short-read single-cell gene
+expression and denoises sparse long-read isoform-usage measurements.
+"""
+
+from .data import (
+    IsoVAEPreprocessor,
+    align_paired_cells,
+    counts_to_gene_usage,
+    prepare_paired_data,
+)
+from .inference import (
+    IsoVAEArtifact,
+    denoise_isoform_usage,
+    load_artifact,
+    predict_isoform_usage,
+    reconstruct_preprocessor_from_training_data,
+)
+from .model import IsoVAEConfig, IsoVAEModel
+from .utils import select_device, set_seed
+
+__all__ = [
+    "IsoVAEArtifact",
+    "IsoVAEConfig",
+    "IsoVAEModel",
+    "IsoVAEPreprocessor",
+    "align_paired_cells",
+    "counts_to_gene_usage",
+    "denoise_isoform_usage",
+    "load_artifact",
+    "predict_isoform_usage",
+    "prepare_paired_data",
+    "reconstruct_preprocessor_from_training_data",
+    "select_device",
+    "set_seed",
+]
+
+__version__ = "0.1.0"

isovae-0.1.0/src/isovae/data.py

@@ -0,0 +1,268 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Dict, Iterable, List, Optional, Sequence, Tuple
+
+import anndata as ad
+import numpy as np
+import pandas as pd
+import scipy.sparse as sp
+from sklearn.model_selection import train_test_split
+from sklearn.preprocessing import StandardScaler
+
+from .utils import set_seed
+
+Array = np.ndarray
+
+
+def _as_array(x: Any) -> Array:
+    if sp.issparse(x):
+        return x.toarray()
+    return np.asarray(x)
+
+
+def strip_barcode_suffix(index: pd.Index) -> pd.Index:
+    """Normalize 10x-style cell barcodes by removing a trailing ``-1`` suffix."""
+    return index.astype(str).str.replace(r"-1$", "", regex=True)
+
+
+def align_paired_cells(
+    adata_gene: ad.AnnData,
+    adata_iso: ad.AnnData,
+    strict: bool = True,
+) -> Tuple[ad.AnnData, ad.AnnData]:
+    """Align paired short-read and long-read AnnData objects by cell barcode."""
+    gene_barcodes = strip_barcode_suffix(adata_gene.obs_names)
+    iso_barcodes = strip_barcode_suffix(adata_iso.obs_names)
+
+    gene_pos = {barcode: i for i, barcode in enumerate(gene_barcodes)}
+    iso_pos = {barcode: i for i, barcode in enumerate(iso_barcodes)}
+    common = sorted(set(gene_pos) & set(iso_pos))
+    if strict and not common:
+        raise ValueError("No common cells found after barcode normalization.")
+
+    gene_idx = [gene_pos[barcode] for barcode in common]
+    iso_idx = [iso_pos[barcode] for barcode in common]
+    gene_aligned = adata_gene[gene_idx, :].copy()
+    iso_aligned = adata_iso[iso_idx, :].copy()
+    normalized_index = pd.Index(common, name="barcode")
+    gene_aligned.obs["barcode_raw"] = gene_aligned.obs_names.astype(str)
+    iso_aligned.obs["barcode_raw"] = iso_aligned.obs_names.astype(str)
+    gene_aligned.obs_names = normalized_index
+    iso_aligned.obs_names = normalized_index
+    return gene_aligned, iso_aligned
+
+
+def make_unique_gene_symbol_view(adata_gene: ad.AnnData) -> ad.AnnData:
+    """Return a copy with unique gene-symbol columns."""
+    if "gene_symbol" in adata_gene.var.columns:
+        symbols = adata_gene.var["gene_symbol"].astype(str).values
+    else:
+        symbols = adata_gene.var_names.astype(str).values
+        adata_gene = adata_gene.copy()
+        adata_gene.var["gene_symbol"] = symbols
+    keep = ~pd.Index(symbols).duplicated(keep="first")
+    return adata_gene[:, keep].copy()
+
+
+def _col_var(x: Any) -> Array:
+    if sp.issparse(x):
+        mean = np.asarray(x.mean(axis=0)).ravel()
+        sq_mean = np.asarray(x.power(2).mean(axis=0)).ravel()
+        return sq_mean - mean**2
+    return np.asarray(x).var(axis=0)
+
+
+def normalize_gene_counts(x: Any) -> Array:
+    """Library-size normalize selected short-read gene counts and apply log1p."""
+    if sp.issparse(x):
+        lib = np.asarray(x.sum(axis=1)).ravel().astype(np.float32)
+        scale = (1e4 / np.maximum(lib, 1e-6)).astype(np.float32)
+        return x.multiply(scale[:, None]).log1p().toarray().astype(np.float32)
+
+    x = np.asarray(x, dtype=np.float32)
+    lib = x.sum(axis=1, keepdims=True)
+    return np.log1p((x / np.maximum(lib, 1e-6)) * 1e4).astype(np.float32)
+
+
+def counts_to_gene_usage(
+    y_counts: Any,
+    isoform_gene: Sequence[str],
+) -> Tuple[Array, List[Array], Array]:
+    """Convert transcript counts to within-gene isoform-usage proportions."""
+    y_counts = _as_array(y_counts).astype(np.float32)
+    gene_to_idx: Dict[str, List[int]] = {}
+    for j, g in enumerate(np.asarray(isoform_gene).astype(str)):
+        gene_to_idx.setdefault(g, []).append(j)
+
+    genes = np.array(list(gene_to_idx.keys()), dtype=object)
+    groups = [np.array(v, dtype=np.int64) for v in gene_to_idx.values()]
+    y_usage = np.zeros_like(y_counts, dtype=np.float32)
+    for idx in groups:
+        denom = y_counts[:, idx].sum(axis=1, keepdims=True)
+        rows = np.where(denom[:, 0] > 0)[0]
+        if rows.size:
+            y_usage[np.ix_(rows, idx)] = y_counts[np.ix_(rows, idx)] / denom[rows]
+    return y_usage, groups, genes
+
+
+@dataclass
+class IsoVAEPreprocessor:
+    """Feature names and scaler needed for short-read-only prediction."""
+
+    genes: List[str]
+    isoforms: List[str]
+    isoform_gene: List[str]
+    gene_groups: List[Array]
+    scaler: StandardScaler
+
+    def transform_gene_adata(self, adata_gene: ad.AnnData) -> Tuple[Array, int]:
+        """Extract and scale the model input genes from a short-read AnnData object."""
+        adata_gene = make_unique_gene_symbol_view(adata_gene)
+        symbols = adata_gene.var["gene_symbol"].astype(str).values
+        symbol_to_pos = {g: i for i, g in enumerate(symbols)}
+        cols = []
+        n_found = 0
+        for gene in self.genes:
+            if gene in symbol_to_pos:
+                cols.append(adata_gene.X[:, symbol_to_pos[gene]])
+                n_found += 1
+            else:
+                cols.append(sp.csr_matrix((adata_gene.n_obs, 1), dtype=np.float32))
+        x_raw = sp.hstack(cols, format="csr") if sp.issparse(cols[0]) else np.column_stack(cols)
+        x = normalize_gene_counts(x_raw)
+        return self.scaler.transform(x).astype(np.float32), n_found
+
+    def extract_iso_counts(self, adata_iso: ad.AnnData) -> Tuple[Array, int]:
+        """Extract model isoform-count features from a long-read AnnData object."""
+        transcript = (
+            adata_iso.var["transcript_id"].astype(str).values
+            if "transcript_id" in adata_iso.var.columns
+            else adata_iso.var_names.astype(str).values
+        )
+        tx_to_pos = {t: i for i, t in enumerate(transcript)}
+        cols = []
+        n_found = 0
+        for tx in self.isoforms:
+            if tx in tx_to_pos:
+                cols.append(adata_iso.X[:, tx_to_pos[tx]])
+                n_found += 1
+            else:
+                cols.append(sp.csr_matrix((adata_iso.n_obs, 1), dtype=np.float32))
+        y = sp.hstack(cols, format="csr") if sp.issparse(cols[0]) else np.column_stack(cols)
+        return _as_array(y).astype(np.float32), n_found
+
+
+def prepare_paired_data(
+    adata_gene: ad.AnnData,
+    adata_iso: ad.AnnData,
+    gene_hvg: int = 1200,
+    min_iso_cells: int = 10,
+    test_size: float = 0.20,
+    val_size_within_train: float = 0.20,
+    seed: int = 42,
+) -> Dict[str, Any]:
+    """Prepare paired data for training/evaluation.
+
+    Feature selection and scaler fitting are performed using training cells only.
+    """
+    set_seed(seed)
+    adata_gene, adata_iso = align_paired_cells(adata_gene, adata_iso)
+    adata_gene = make_unique_gene_symbol_view(adata_gene)
+
+    all_idx = np.arange(adata_gene.n_obs)
+    train_idx, test_idx = train_test_split(all_idx, test_size=test_size, random_state=seed)
+    train_idx, val_idx = train_test_split(
+        train_idx, test_size=val_size_within_train, random_state=seed
+    )
+
+    gene_symbols = adata_gene.var["gene_symbol"].astype(str).values
+    iso_gene_all = adata_iso.var["gene_id"].astype(str).values
+    common_genes = np.intersect1d(np.unique(gene_symbols), np.unique(iso_gene_all))
+    if common_genes.size == 0:
+        raise ValueError("No overlap between short-read gene_symbol and LR isoform gene_id.")
+
+    common_mask = np.isin(gene_symbols, common_genes)
+    adata_gene_common = adata_gene[:, common_mask]
+    var = _col_var(adata_gene_common.X[train_idx, :])
+    top_idx = np.argsort(var)[::-1][: min(gene_hvg, adata_gene_common.n_vars)]
+    selected_genes = adata_gene_common.var["gene_symbol"].astype(str).values[top_idx]
+
+    iso_mask = np.isin(iso_gene_all, selected_genes)
+    adata_iso_sel = adata_iso[:, iso_mask].copy()
+    iso_nonzero_cells = np.asarray((adata_iso_sel.X[train_idx, :] > 0).sum(axis=0)).ravel()
+    adata_iso_sel = adata_iso_sel[:, iso_nonzero_cells >= min_iso_cells].copy()
+
+    iso_gene = adata_iso_sel.var["gene_id"].astype(str).values
+    gene_to_idx: Dict[str, List[int]] = {}
+    for j, g in enumerate(iso_gene):
+        gene_to_idx.setdefault(g, []).append(j)
+    genes_keep = [g for g, idx in gene_to_idx.items() if len(idx) >= 2]
+    if not genes_keep:
+        raise ValueError("No genes with >=2 isoforms after filtering.")
+
+    iso_keep_idx = np.concatenate([gene_to_idx[g] for g in genes_keep]).astype(np.int64)
+    adata_iso_sel = adata_iso_sel[:, iso_keep_idx].copy()
+    isoform_gene = adata_iso_sel.var["gene_id"].astype(str).values
+    isoforms = (
+        adata_iso_sel.var["transcript_id"].astype(str).values
+        if "transcript_id" in adata_iso_sel.var.columns
+        else adata_iso_sel.var_names.astype(str).values
+    )
+    y_counts = _as_array(adata_iso_sel.X).astype(np.float32)
+    y_usage, gene_groups, genes = counts_to_gene_usage(y_counts, isoform_gene)
+    genes = genes.astype(str)
+
+    # Build short-read inputs in retained gene-group order.
+    # Manual extraction before scaler is fitted.
+    adata_gene_u = make_unique_gene_symbol_view(adata_gene)
+    symbols = adata_gene_u.var["gene_symbol"].astype(str).values
+    symbol_to_pos = {g: i for i, g in enumerate(symbols)}
+    cols = []
+    n_gene_found = 0
+    for g in genes:
+        if g in symbol_to_pos:
+            cols.append(adata_gene_u.X[:, symbol_to_pos[g]])
+            n_gene_found += 1
+        else:
+            cols.append(sp.csr_matrix((adata_gene_u.n_obs, 1), dtype=np.float32))
+    x_raw = sp.hstack(cols, format="csr") if sp.issparse(cols[0]) else np.column_stack(cols)
+    x_norm = normalize_gene_counts(x_raw)
+    scaler = StandardScaler().fit(x_norm[train_idx])
+    x_all = scaler.transform(x_norm).astype(np.float32)
+
+    preprocessor = IsoVAEPreprocessor(
+        genes=list(map(str, genes)),
+        isoforms=list(map(str, isoforms)),
+        isoform_gene=list(map(str, isoform_gene)),
+        gene_groups=gene_groups,
+        scaler=scaler,
+    )
+    return {
+        "x_train": x_all[train_idx],
+        "x_val": x_all[val_idx],
+        "x_test": x_all[test_idx],
+        "y_train_usage": y_usage[train_idx],
+        "y_val_usage": y_usage[val_idx],
+        "y_test_usage": y_usage[test_idx],
+        "y_train_counts": y_counts[train_idx],
+        "y_val_counts": y_counts[val_idx],
+        "y_test_counts": y_counts[test_idx],
+        "train_obs_names": adata_gene.obs_names[train_idx].astype(str).tolist(),
+        "val_obs_names": adata_gene.obs_names[val_idx].astype(str).tolist(),
+        "test_obs_names": adata_gene.obs_names[test_idx].astype(str).tolist(),
+        "preprocessor": preprocessor,
+        "gene_groups": gene_groups,
+        "genes_final": genes.astype(str),
+        "isoforms_final": np.asarray(isoforms).astype(str),
+        "isoform_gene": np.asarray(isoform_gene).astype(str),
+        "meta": {
+            "n_cells": int(adata_gene.n_obs),
+            "n_train": int(len(train_idx)),
+            "n_val": int(len(val_idx)),
+            "n_test": int(len(test_idx)),
+            "n_gene_groups": int(len(gene_groups)),
+            "n_isoforms_output": int(len(isoforms)),
+            "n_gene_features_found": int(n_gene_found),
+        },
+    }

isovae-0.1.0/src/isovae/inference.py

@@ -0,0 +1,269 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Dict, List, Optional, Sequence, Tuple
+
+import anndata as ad
+import numpy as np
+import pandas as pd
+import scipy.sparse as sp
+import torch
+from sklearn.model_selection import train_test_split
+from sklearn.preprocessing import StandardScaler
+
+from .data import (
+    IsoVAEPreprocessor,
+    align_paired_cells,
+    counts_to_gene_usage,
+    make_unique_gene_symbol_view,
+    normalize_gene_counts,
+)
+from .model import (
+    IsoVAEModel,
+    iso_encoder_input_from_counts,
+    logits_to_usage,
+    make_config_from_checkpoint,
+)
+from .utils import select_device
+
+Array = np.ndarray
+
+
+@dataclass
+class IsoVAEArtifact:
+    """Loaded model plus feature metadata.
+
+    A fitted ``preprocessor`` is required for short-read-only prediction.
+    Older checkpoints contain feature names but not the scaler; in that case,
+    pass a preprocessor reconstructed from the original training data.
+    """
+
+    model: IsoVAEModel
+    genes: List[str]
+    isoforms: List[str]
+    isoform_gene: List[str]
+    gene_groups: List[Array]
+    preprocessor: Optional[IsoVAEPreprocessor] = None
+    device: str = "cpu"
+
+    def to(self, device: str) -> "IsoVAEArtifact":
+        self.device = device
+        self.model.to(device)
+        self.model.eval()
+        return self
+
+
+def load_artifact(
+    checkpoint: str | Path,
+    preprocessor: Optional[IsoVAEPreprocessor] = None,
+    device: Optional[str] = None,
+) -> IsoVAEArtifact:
+    """Load an IsoVAE checkpoint saved by the training scripts."""
+    device = device or select_device(prefer_cuda=True)
+    ckpt = torch.load(checkpoint, map_location="cpu", weights_only=False)
+    genes = list(map(str, ckpt["genes_final"]))
+    isoforms = list(map(str, ckpt["isoforms_final"]))
+    isoform_gene = list(map(str, ckpt["isoform_gene"]))
+    groups = [np.asarray(g, dtype=np.int64) for g in ckpt["gene_groups"]]
+    config = make_config_from_checkpoint(ckpt.get("model_config", {}), ckpt.get("model_state"))
+    model = IsoVAEModel(
+        n_gene_inputs=len(genes),
+        n_isoforms=len(isoforms),
+        n_gene_groups=len(groups),
+        config=config,
+    )
+    model.load_state_dict(ckpt["model_state"], strict=True)
+    model.to(device)
+    model.eval()
+
+    if preprocessor is not None:
+        # Ensure model and preprocessor features agree.
+        if list(preprocessor.genes) != genes:
+            raise ValueError("Preprocessor genes do not match checkpoint genes.")
+        if list(preprocessor.isoforms) != isoforms:
+            raise ValueError("Preprocessor isoforms do not match checkpoint isoforms.")
+
+    return IsoVAEArtifact(
+        model=model,
+        genes=genes,
+        isoforms=isoforms,
+        isoform_gene=isoform_gene,
+        gene_groups=groups,
+        preprocessor=preprocessor,
+        device=device,
+    )
+
+
+def reconstruct_preprocessor_from_training_data(
+    checkpoint: str | Path,
+    adata_gene_train: ad.AnnData,
+    adata_iso_train: Optional[ad.AnnData] = None,
+    seed: int = 42,
+    test_size: float = 0.20,
+    val_size_within_train: float = 0.20,
+) -> IsoVAEPreprocessor:
+    """Reconstruct preprocessing metadata for older checkpoints.
+
+    The final manuscript checkpoint stores feature names and model weights, but
+    not the fitted ``StandardScaler``. This helper rebuilds the scaler from the
+    original paired training data using the same deterministic split. If
+    ``adata_iso_train`` is provided, cells are first aligned exactly as in
+    training.
+    """
+    ckpt = torch.load(checkpoint, map_location="cpu", weights_only=False)
+    genes = list(map(str, ckpt["genes_final"]))
+    isoforms = list(map(str, ckpt["isoforms_final"]))
+    isoform_gene = list(map(str, ckpt["isoform_gene"]))
+    groups = [np.asarray(g, dtype=np.int64) for g in ckpt["gene_groups"]]
+
+    if adata_iso_train is not None:
+        adata_gene_train, _ = align_paired_cells(adata_gene_train, adata_iso_train)
+    adata_gene_train = make_unique_gene_symbol_view(adata_gene_train)
+    symbols = adata_gene_train.var["gene_symbol"].astype(str).values
+    symbol_to_pos = {g: i for i, g in enumerate(symbols)}
+    cols = []
+    for gene in genes:
+        if gene in symbol_to_pos:
+            cols.append(adata_gene_train.X[:, symbol_to_pos[gene]])
+        else:
+            cols.append(sp.csr_matrix((adata_gene_train.n_obs, 1), dtype=np.float32))
+    x_raw = sp.hstack(cols, format="csr") if sp.issparse(cols[0]) else np.column_stack(cols)
+    x_norm = normalize_gene_counts(x_raw)
+
+    all_idx = np.arange(adata_gene_train.n_obs)
+    train_idx, _ = train_test_split(all_idx, test_size=test_size, random_state=seed)
+    train_idx, _ = train_test_split(
+        train_idx, test_size=val_size_within_train, random_state=seed
+    )
+    scaler = StandardScaler().fit(x_norm[train_idx])
+    return IsoVAEPreprocessor(
+        genes=genes,
+        isoforms=isoforms,
+        isoform_gene=isoform_gene,
+        gene_groups=groups,
+        scaler=scaler,
+    )
+
+
+@torch.no_grad()
+def predict_usage_array(
+    model: IsoVAEModel,
+    x: Array,
+    groups: Sequence[Array],
+    device: str = "cpu",
+    batch_size: int = 512,
+) -> Array:
+    """Predict isoform usage from a scaled gene-expression matrix."""
+    model.eval()
+    preds: List[Array] = []
+    for start in range(0, x.shape[0], batch_size):
+        xb = torch.from_numpy(x[start : start + batch_size].astype(np.float32)).to(device)
+        logits, _, _ = model.predict_from_gene(xb)
+        preds.append(logits_to_usage(logits, groups))
+    return np.vstack(preds)
+
+
+@torch.no_grad()
+def denoise_usage_array(
+    model: IsoVAEModel,
+    y_counts: Array,
+    groups: Sequence[Array],
+    device: str = "cpu",
+    keep_rate: Optional[float] = None,
+    batch_size: int = 512,
+) -> Tuple[Array, Array]:
+    """Denoise long-read isoform counts into within-gene isoform usage.
+
+    If ``keep_rate`` is provided, counts are first binomially downsampled. This
+    is useful for simulated denoising experiments.
+    """
+    model.eval()
+    group_tensors = [torch.as_tensor(g, dtype=torch.long, device=device) for g in groups]
+    preds: List[Array] = []
+    noisy_counts: List[Array] = []
+    for start in range(0, y_counts.shape[0], batch_size):
+        yc = torch.from_numpy(y_counts[start : start + batch_size].astype(np.float32)).to(device)
+        if keep_rate is None:
+            yn = yc
+        else:
+            yn = torch.binomial(torch.clamp(yc, min=0.0), torch.full_like(yc, float(keep_rate)))
+        iso_in = iso_encoder_input_from_counts(yn, group_tensors)
+        logits, _, _ = model.denoise_from_iso(iso_in)
+        preds.append(logits_to_usage(logits, groups))
+        noisy_counts.append(yn.detach().cpu().numpy().astype(np.float32))
+    return np.vstack(preds), np.vstack(noisy_counts)
+
+
+def predict_isoform_usage(
+    artifact: IsoVAEArtifact,
+    adata_gene: ad.AnnData,
+    batch_size: int = 512,
+) -> Tuple[pd.DataFrame, Dict[str, int]]:
+    """Predict isoform usage from short-read-only AnnData."""
+    if artifact.preprocessor is None:
+        raise ValueError(
+            "A fitted IsoVAEPreprocessor is required for AnnData prediction. "
+            "Reconstruct it from the paired training data or load one saved with your model."
+        )
+    x, n_found = artifact.preprocessor.transform_gene_adata(adata_gene)
+    pred = predict_usage_array(
+        artifact.model, x, artifact.gene_groups, device=artifact.device, batch_size=batch_size
+    )
+    df = pd.DataFrame(pred, index=adata_gene.obs_names.astype(str), columns=artifact.isoforms)
+    return df, {"n_gene_features_found": int(n_found), "n_gene_features_total": len(artifact.genes)}
+
+
+def denoise_isoform_usage(
+    artifact: IsoVAEArtifact,
+    adata_iso: ad.AnnData,
+    keep_rate: Optional[float] = None,
+    batch_size: int = 512,
+) -> Tuple[pd.DataFrame, pd.DataFrame, Dict[str, int]]:
+    """Denoise long-read isoform counts from AnnData.
+
+    Returns denoised usage, direct observed/noisy usage, and a metadata dict.
+    """
+    if artifact.preprocessor is not None:
+        counts, n_found = artifact.preprocessor.extract_iso_counts(adata_iso)
+    else:
+        # Feature extraction can still be done from checkpoint metadata.
+        pre = IsoVAEPreprocessor(
+            genes=artifact.genes,
+            isoforms=artifact.isoforms,
+            isoform_gene=artifact.isoform_gene,
+            gene_groups=artifact.gene_groups,
+            scaler=None,  # type: ignore[arg-type]
+        )
+        counts, n_found = pre.extract_iso_counts(adata_iso)
+
+    denoised, noisy_counts = denoise_usage_array(
+        artifact.model,
+        counts,
+        artifact.gene_groups,
+        device=artifact.device,
+        keep_rate=keep_rate,
+        batch_size=batch_size,
+    )
+    observed_usage, _, _ = counts_to_gene_usage(noisy_counts, artifact.isoform_gene)
+    den_df = pd.DataFrame(denoised, index=adata_iso.obs_names.astype(str), columns=artifact.isoforms)
+    obs_df = pd.DataFrame(observed_usage, index=adata_iso.obs_names.astype(str), columns=artifact.isoforms)
+    return den_df, obs_df, {"n_isoforms_found": int(n_found), "n_isoforms_total": len(artifact.isoforms)}
+
+
+def usage_long_table(
+    usage: pd.DataFrame,
+    isoform_gene: Sequence[str],
+    obs_columns: Optional[pd.DataFrame] = None,
+) -> pd.DataFrame:
+    """Convert a cell-by-isoform usage matrix to a long table for plotting."""
+    long = usage.reset_index(names="cell").melt(
+        id_vars="cell", var_name="isoform", value_name="usage"
+    )
+    gene_map = pd.DataFrame({"isoform": usage.columns.astype(str), "gene": list(isoform_gene)})
+    long = long.merge(gene_map, on="isoform", how="left")
+    if obs_columns is not None:
+        meta = obs_columns.copy()
+        meta["cell"] = meta.index.astype(str)
+        long = long.merge(meta, on="cell", how="left")
+    return long

isovae-0.1.0/src/isovae/metrics.py

@@ -0,0 +1,68 @@
+from __future__ import annotations
+
+from typing import Dict, List, Sequence
+
+import numpy as np
+
+Array = np.ndarray
+
+
+def evaluate_usage_metrics(
+    pred_usage: Array,
+    y_usage: Array,
+    y_counts: Array,
+    groups: Sequence[Array],
+    eps: float = 1e-8,
+) -> Dict[str, float]:
+    """Evaluate predicted within-gene isoform usage against observed usage."""
+    ce_num = 0.0
+    ce_den = 0.0
+    top1_correct = 0
+    top2_correct = 0
+    total = 0
+    mae_list: List[float] = []
+    pearson_list: List[float] = []
+    cosine_list: List[float] = []
+
+    for idx in groups:
+        pred = pred_usage[:, idx]
+        truth = y_usage[:, idx]
+        counts = y_counts[:, idx]
+        cov = counts.sum(axis=1)
+        mask = cov > 0
+        if not mask.any():
+            continue
+
+        ce = -(truth[mask] * np.log(pred[mask] + eps)).sum(axis=1)
+        w = np.sqrt(cov[mask] + 1.0)
+        ce_num += float(np.sum(ce * w))
+        ce_den += float(np.sum(w))
+
+        obs_top = np.argmax(truth[mask], axis=1)
+        pred_order = np.argsort(pred[mask], axis=1)[:, ::-1]
+        top1_correct += int(np.sum(pred_order[:, 0] == obs_top))
+        top2_correct += int(np.sum([obs_top[i] in pred_order[i, :2] for i in range(len(obs_top))]))
+        total += int(mask.sum())
+        mae_list.append(float(np.mean(np.abs(pred[mask] - truth[mask]))))
+
+        if len(idx) >= 3:
+            p = pred[mask]
+            t = truth[mask]
+            dot = np.sum(p * t, axis=1)
+            denom = np.linalg.norm(p, axis=1) * np.linalg.norm(t, axis=1) + eps
+            cosine_list.extend((dot / denom).astype(float).tolist())
+            for i in range(p.shape[0]):
+                if np.std(p[i]) > eps and np.std(t[i]) > eps:
+                    r = np.corrcoef(p[i], t[i])[0, 1]
+                    if np.isfinite(r):
+                        pearson_list.append(float(r))
+
+    return {
+        "weighted_ce": float(ce_num / max(ce_den, eps)),
+        "top1": float(top1_correct / max(total, 1)),
+        "top2": float(top2_correct / max(total, 1)),
+        "group_mae": float(np.mean(mae_list)) if mae_list else float("nan"),
+        "gene_cell_pearson": float(np.mean(pearson_list)) if pearson_list else float("nan"),
+        "gene_cell_cosine": float(np.mean(cosine_list)) if cosine_list else float("nan"),
+        "n_effective_gene_cell_pairs": int(total),
+    }

isovae-0.1.0/src/isovae/model.py

@@ -0,0 +1,175 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import List, Optional, Sequence, Tuple
+
+import numpy as np
+import torch
+from torch import nn
+
+Array = np.ndarray
+
+
+@dataclass
+class IsoVAEConfig:
+    """Neural network configuration for IsoVAE."""
+
+    gene_hidden: Tuple[int, int] = (512, 256)
+    iso_hidden: Tuple[int, int] = (512, 256)
+    decoder_hidden: Tuple[int, int] = (256, 512)
+    latent_dim: int = 32
+    dropout: float = 0.20
+
+
+class GaussianEncoder(nn.Module):
+    def __init__(
+        self,
+        in_dim: int,
+        hidden: Tuple[int, int],
+        latent_dim: int,
+        dropout: float,
+    ) -> None:
+        super().__init__()
+        h1, h2 = hidden
+        self.net = nn.Sequential(
+            nn.Linear(in_dim, h1),
+            nn.LayerNorm(h1),
+            nn.GELU(),
+            nn.Dropout(dropout),
+            nn.Linear(h1, h2),
+            nn.LayerNorm(h2),
+            nn.GELU(),
+            nn.Dropout(dropout),
+        )
+        self.mu = nn.Linear(h2, latent_dim)
+        self.logvar = nn.Linear(h2, latent_dim)
+
+    def forward(self, x: torch.Tensor) -> Tuple[torch.Tensor, torch.Tensor]:
+        h = self.net(x)
+        return self.mu(h), torch.clamp(self.logvar(h), min=-10.0, max=6.0)
+
+
+class IsoVAEModel(nn.Module):
+    """Multimodal hierarchical VAE for isoform-usage prediction and denoising."""
+
+    def __init__(
+        self,
+        n_gene_inputs: int,
+        n_isoforms: int,
+        n_gene_groups: int,
+        config: IsoVAEConfig,
+    ) -> None:
+        super().__init__()
+        self.n_gene_inputs = int(n_gene_inputs)
+        self.n_isoforms = int(n_isoforms)
+        self.n_gene_groups = int(n_gene_groups)
+        self.latent_dim = int(config.latent_dim)
+
+        self.gene_encoder = GaussianEncoder(
+            self.n_gene_inputs, config.gene_hidden, config.latent_dim, config.dropout
+        )
+        self.iso_encoder = GaussianEncoder(
+            self.n_isoforms + self.n_gene_groups,
+            config.iso_hidden,
+            config.latent_dim,
+            config.dropout,
+        )
+        d1, d2 = config.decoder_hidden
+        self.decoder = nn.Sequential(
+            nn.Linear(config.latent_dim, d1),
+            nn.LayerNorm(d1),
+            nn.GELU(),
+            nn.Dropout(config.dropout),
+            nn.Linear(d1, d2),
+            nn.LayerNorm(d2),
+            nn.GELU(),
+            nn.Dropout(config.dropout),
+        )
+        self.iso_head = nn.Linear(d2, self.n_isoforms)
+
+    @staticmethod
+    def reparameterize(mu: torch.Tensor, logvar: torch.Tensor) -> torch.Tensor:
+        if not torch.is_grad_enabled():
+            return mu
+        std = torch.exp(0.5 * logvar)
+        return mu + torch.randn_like(std) * std
+
+    def encode_gene(self, x: torch.Tensor) -> Tuple[torch.Tensor, torch.Tensor, torch.Tensor]:
+        mu, logvar = self.gene_encoder(x)
+        z = self.reparameterize(mu, logvar) if self.training else mu
+        return z, mu, logvar
+
+    def encode_iso(self, iso_input: torch.Tensor) -> Tuple[torch.Tensor, torch.Tensor, torch.Tensor]:
+        mu, logvar = self.iso_encoder(iso_input)
+        z = self.reparameterize(mu, logvar) if self.training else mu
+        return z, mu, logvar
+
+    def decode_logits(self, z: torch.Tensor) -> torch.Tensor:
+        return self.iso_head(self.decoder(z))
+
+    def predict_from_gene(self, x: torch.Tensor) -> Tuple[torch.Tensor, torch.Tensor, torch.Tensor]:
+        z, mu, logvar = self.encode_gene(x)
+        return self.decode_logits(z), mu, logvar
+
+    def denoise_from_iso(self, iso_input: torch.Tensor) -> Tuple[torch.Tensor, torch.Tensor, torch.Tensor]:
+        z, mu, logvar = self.encode_iso(iso_input)
+        return self.decode_logits(z), mu, logvar
+
+
+def usage_from_counts_torch(
+    y_counts: torch.Tensor,
+    group_tensors: Sequence[torch.Tensor],
+    eps: float = 1e-8,
+) -> Tuple[torch.Tensor, torch.Tensor]:
+    """Convert count tensor to usage tensor plus gene-level coverage features."""
+    usage = torch.zeros_like(y_counts)
+    covs: List[torch.Tensor] = []
+    for idx in group_tensors:
+        counts_g = y_counts.index_select(1, idx)
+        cov = counts_g.sum(dim=1, keepdim=True)
+        usage_g = counts_g / (cov + eps)
+        usage[:, idx] = torch.where(cov > 0, usage_g, torch.zeros_like(usage_g))
+        covs.append(cov)
+    return usage, torch.cat(covs, dim=1)
+
+
+def iso_encoder_input_from_counts(
+    y_counts: torch.Tensor,
+    group_tensors: Sequence[torch.Tensor],
+) -> torch.Tensor:
+    """Build long-read encoder input: isoform usage + standardized log gene coverage."""
+    usage, cov = usage_from_counts_torch(y_counts, group_tensors)
+    cov_feat = torch.log1p(cov)
+    cov_feat = (cov_feat - cov_feat.mean(dim=1, keepdim=True)) / (
+        cov_feat.std(dim=1, keepdim=True) + 1e-6
+    )
+    return torch.cat([usage, cov_feat], dim=1)
+
+
+def logits_to_usage(
+    logits: torch.Tensor,
+    groups: Sequence[Array],
+) -> Array:
+    """Apply gene-wise softmax to logits and return isoform-usage proportions."""
+    out = np.zeros(tuple(logits.shape), dtype=np.float32)
+    for idx_np in groups:
+        idx = torch.as_tensor(idx_np, dtype=torch.long, device=logits.device)
+        out[:, idx_np] = torch.softmax(logits.index_select(1, idx), dim=1).detach().cpu().numpy()
+    return out
+
+
+def make_config_from_checkpoint(config_dict: dict, state_dict: Optional[dict] = None) -> IsoVAEConfig:
+    """Create a clean IsoVAEConfig from older checkpoints.
+
+    Historical checkpoints may contain extra keys from attention experiments.
+    They are ignored here so that the public package loads the final model.
+    """
+    allowed = {"gene_hidden", "iso_hidden", "decoder_hidden", "latent_dim", "dropout"}
+    clean = {k: v for k, v in (config_dict or {}).items() if k in allowed}
+    if "gene_hidden" in clean:
+        clean["gene_hidden"] = tuple(clean["gene_hidden"])
+    if "iso_hidden" in clean:
+        clean["iso_hidden"] = tuple(clean["iso_hidden"])
+    if "decoder_hidden" in clean:
+        clean["decoder_hidden"] = tuple(clean["decoder_hidden"])
+    return IsoVAEConfig(**clean)

isovae-0.1.0/src/isovae/utils.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+import random
+
+import numpy as np
+import torch
+
+
+def set_seed(seed: int = 42) -> None:
+    """Set random seeds for reproducible NumPy/PyTorch experiments."""
+    random.seed(seed)
+    np.random.seed(seed)
+    torch.manual_seed(seed)
+    if torch.cuda.is_available():
+        torch.cuda.manual_seed_all(seed)
+
+
+def select_device(prefer_cuda: bool = True) -> str:
+    """Return ``cuda`` when available and requested, otherwise ``cpu``."""
+    return "cuda" if prefer_cuda and torch.cuda.is_available() else "cpu"

isovae-0.1.0/src/isovae/viz.py

@@ -0,0 +1,62 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Optional, Sequence
+
+import matplotlib.pyplot as plt
+import pandas as pd
+import seaborn as sns
+
+
+def plot_gene_usage_boxplot(
+    usage_long: pd.DataFrame,
+    gene: str,
+    groupby: Optional[str] = None,
+    ax: Optional[plt.Axes] = None,
+) -> plt.Axes:
+    """Plot isoform-usage distributions for one gene.
+
+    ``usage_long`` should contain at least columns: ``gene``, ``isoform``,
+    ``usage`` and optionally a grouping column such as stage or cell type.
+    """
+    data = usage_long.loc[usage_long["gene"].astype(str) == str(gene)].copy()
+    if data.empty:
+        raise ValueError(f"No rows found for gene={gene!r}.")
+    if ax is None:
+        _, ax = plt.subplots(figsize=(max(5, data["isoform"].nunique() * 1.2), 4))
+    if groupby and groupby in data.columns:
+        sns.boxplot(data=data, x=groupby, y="usage", hue="isoform", ax=ax, fliersize=0.5)
+        ax.tick_params(axis="x", rotation=45)
+    else:
+        sns.violinplot(data=data, x="isoform", y="usage", ax=ax, cut=0, inner="box")
+        ax.tick_params(axis="x", rotation=45)
+    ax.set_title(f"{gene} isoform usage")
+    ax.set_xlabel(groupby if groupby else "Isoform")
+    ax.set_ylabel("Isoform usage")
+    return ax
+
+
+def plot_usage_heatmap(
+    usage: pd.DataFrame,
+    isoforms: Optional[Sequence[str]] = None,
+    max_cells: int = 200,
+    ax: Optional[plt.Axes] = None,
+) -> plt.Axes:
+    """Plot a compact heatmap of cell-by-isoform usage values."""
+    mat = usage.loc[:, list(isoforms)] if isoforms is not None else usage
+    if mat.shape[0] > max_cells:
+        mat = mat.iloc[:max_cells]
+    if ax is None:
+        _, ax = plt.subplots(figsize=(8, 5))
+    sns.heatmap(mat, cmap="viridis", xticklabels=False, yticklabels=False, ax=ax)
+    ax.set_xlabel("Isoforms")
+    ax.set_ylabel("Cells")
+    return ax
+
+
+def savefig(path: str | Path, dpi: int = 300) -> None:
+    """Save current matplotlib figure with tight layout."""
+    path = Path(path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    plt.tight_layout()
+    plt.savefig(path, dpi=dpi, bbox_inches="tight")

isovae-0.1.0/src/isovae.egg-info/PKG-INFO

@@ -0,0 +1,125 @@
+Metadata-Version: 2.4
+Name: isovae
+Version: 0.1.0
+Summary: IsoVAE: isoform-usage prediction and long-read isoform-usage denoising for single-cell RNA-seq
+Author: IsoVAE developers
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/your-username/IsoVAE
+Project-URL: Documentation, https://your-username.github.io/IsoVAE/
+Project-URL: Repository, https://github.com/your-username/IsoVAE
+Project-URL: Issues, https://github.com/your-username/IsoVAE/issues
+Keywords: single-cell RNA-seq,isoform usage,long-read RNA-seq,variational autoencoder,denoising
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.23
+Requires-Dist: pandas>=1.5
+Requires-Dist: scipy>=1.9
+Requires-Dist: scikit-learn>=1.2
+Requires-Dist: anndata>=0.9
+Requires-Dist: torch>=2.0
+Requires-Dist: matplotlib>=3.6
+Requires-Dist: seaborn>=0.12
+Provides-Extra: docs
+Requires-Dist: mkdocs>=1.5; extra == "docs"
+Requires-Dist: mkdocs-material>=9.5; extra == "docs"
+Requires-Dist: mkdocstrings[python]>=0.24; extra == "docs"
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Dynamic: license-file
+
+# IsoVAE
+
+IsoVAE is a Python package for single-cell isoform-usage analysis. It supports:
+
+1. **Isoform-usage prediction** from short-read single-cell gene-expression profiles.
+2. **Long-read isoform-usage denoising** from sparse long-read isoform count matrices.
+
+IsoVAE models **within-gene isoform usage proportions**, not absolute transcript abundance.
+
+## Installation
+
+```bash
+pip install isovae
+```
+
+For local development:
+
+```bash
+git clone https://github.com/your-username/IsoVAE.git
+cd IsoVAE
+pip install -e .
+```
+
+## Quick start
+
+```python
+import scanpy as sc
+from isovae import (
+    load_artifact,
+    reconstruct_preprocessor_from_training_data,
+    predict_isoform_usage,
+    denoise_isoform_usage,
+)
+
+model_path = "path/to/vae_xda_model.pt"
+
+gene_train = sc.read("path/to/training_gene_matrix.h5ad")
+iso_train = sc.read("path/to/training_isoform_matrix.h5ad")
+
+preprocessor = reconstruct_preprocessor_from_training_data(
+    model_path,
+    adata_gene_train=gene_train,
+    adata_iso_train=iso_train,
+    seed=42,
+)
+
+artifact = load_artifact(model_path, preprocessor=preprocessor, device="cpu")
+
+# Predict isoform usage from short-read data.
+gene_query = sc.read("path/to/query_gene_matrix.h5ad")
+pred_usage, pred_meta = predict_isoform_usage(artifact, gene_query)
+pred_usage.to_csv("predicted_isoform_usage.csv")
+
+# Denoise long-read isoform usage.
+iso_query = sc.read("path/to/query_isoform_matrix.h5ad")
+denoised_usage, noisy_usage, denoise_meta = denoise_isoform_usage(artifact, iso_query)
+denoised_usage.to_csv("denoised_isoform_usage.csv")
+```
+
+## Documentation
+
+The documentation source is in `docs/` and can be built with MkDocs:
+
+```bash
+pip install -e ".[docs]"
+mkdocs serve
+```
+
+To deploy to GitHub Pages:
+
+```bash
+mkdocs gh-deploy
+```
+
+See `docs/deployment.md` for deployment instructions for GitHub Pages, Read the Docs, Netlify and Vercel.
+
+## Repository layout
+
+```text
+.
+├── src/isovae/        # Python package
+├── docs/              # Documentation source
+├── mkdocs.yml         # Documentation configuration
+├── pyproject.toml     # Package metadata
+├── requirements.txt
+├── LICENSE
+└── README.md
+```
+
+Large data files, AnnData objects, model checkpoints and manuscript outputs are not included in the package.
+
+## Citation
+
+If you use IsoVAE, please cite the accompanying manuscript after publication.

isovae-0.1.0/src/isovae.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+LICENSE
+README.md
+pyproject.toml
+src/isovae/__init__.py
+src/isovae/data.py
+src/isovae/inference.py
+src/isovae/metrics.py
+src/isovae/model.py
+src/isovae/utils.py
+src/isovae/viz.py
+src/isovae.egg-info/PKG-INFO
+src/isovae.egg-info/SOURCES.txt
+src/isovae.egg-info/dependency_links.txt
+src/isovae.egg-info/requires.txt
+src/isovae.egg-info/top_level.txt

isovae-0.1.0/src/isovae.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

isovae-0.1.0/src/isovae.egg-info/requires.txt

@@ -0,0 +1,17 @@
+numpy>=1.23
+pandas>=1.5
+scipy>=1.9
+scikit-learn>=1.2
+anndata>=0.9
+torch>=2.0
+matplotlib>=3.6
+seaborn>=0.12
+
+[dev]
+pytest
+ruff
+
+[docs]
+mkdocs>=1.5
+mkdocs-material>=9.5
+mkdocstrings[python]>=0.24

isovae-0.1.0/src/isovae.egg-info/top_level.txt

@@ -0,0 +1 @@
+isovae