bsvae 0.1.1__tar.gz

bsvae-0.1.1/PKG-INFO

@@ -0,0 +1,168 @@
+Metadata-Version: 2.4
+Name: bsvae
+Version: 0.1.1
+Summary: 
+Author: Kynon J Benjamin
+Author-email: kj.benjamin90@gmail.com
+Requires-Python: >=3.11,<3.14
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: mygene (>=3.2.2,<4.0.0)
+Requires-Dist: networkx (>=3.5,<4.0)
+Requires-Dist: numpy (<2.3)
+Requires-Dist: pandas (>=2.3.2,<3.0.0)
+Requires-Dist: scikit-learn (>=1.7.2,<2.0.0)
+Requires-Dist: scipy (>=1.16.2,<2.0.0)
+Requires-Dist: torch (>=2.8.0,<3.0.0)
+Requires-Dist: tqdm (>=4.67.1,<5.0.0)
+Description-Content-Type: text/markdown
+
+# BSVAE: Biologically Structured Variational Autoencoder
+
+[![PyTorch](https://img.shields.io/badge/PyTorch-%3E%3D2.0-orange)](https://pytorch.org/)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+**BSVAE** is a PyTorch package for **Structured Factor Variational Autoencoders** (StructuredFactorVAE).  
+It is designed for **gene expression modeling with biological priors**, integrating **protein–protein interaction (PPI) networks** and **sparsity constraints** for interpretable latent representations.
+
+---
+
+## Features
+
+- **Structured VAE architecture** (`StructuredFactorVAE`)
+  - Factorized encoder/decoder with group sparsity
+  - Optional Laplacian regularization from PPI networks
+- **Dataset utilities**
+  - Load gene expression matrices (`GeneExpression`)
+  - Support for CSV full-matrix mode or pre-split train/test mode
+- **Biological priors**
+  - Fetch and cache STRING PPI networks by NCBI TaxID
+  - Map gene symbols / Ensembl IDs to protein IDs using MyGene.info or BioMart
+- **Training and evaluation**
+  - Unified training loop (`Trainer`)
+  - Evaluation with reconstruction, KL, sparsity, and Laplacian penalties (`Evaluator`)
+- **Reproducibility**
+  - Save/load models + metadata (`modelIO`)
+  - Configurable hyperparameters via `hyperparam.ini`
+
+---
+
+## Installation
+
+Clone the repo and install with [Poetry](https://python-poetry.org/) (recommended):
+
+```bash
+git clone https://github.com/YOUR-LAB/BSVAE.git
+cd BSVAE
+poetry install
+````
+
+Or using pip:
+
+```bash
+pip install -e .
+```
+
+Dependencies:
+
+* Python 3.9+
+* PyTorch ≥ 2.0
+* pandas, numpy, scikit-learn
+* networkx, scipy
+* mygene (for gene annotation)
+
+---
+
+## Quickstart
+
+### 1. Prepare gene expression data
+
+BSVAE expects **genes × samples** CSVs.
+
+* **Full-matrix mode**:
+  Provide `expr.csv` with all samples → 10-fold CV split is created.
+* **Pre-split mode**:
+  Provide directory with `X_train.csv` and `X_test.csv`.
+
+### 2. Train a model
+
+```bash
+poetry run python -m bsvae.main exp1 \
+    --gene-expression-filename data/expr.csv \
+    --epochs 50 \
+    --latent-dim 10 \
+    --ppi-taxid 9606
+```
+
+* Results (checkpoints, logs, metadata) saved under `results/exp1/`.
+
+### 3. Evaluate a trained model
+
+```bash
+poetry run python -m bsvae.main exp1 \
+    --gene-expression-filename data/expr.csv \
+    --is-eval-only
+```
+
+---
+
+## ⚙Configuration
+
+Hyperparameters can be set via `hyperparam.ini`:
+
+```ini
+[Custom]
+seed = 42
+no_cuda = False
+epochs = 100
+batch_size = 64
+latent_dim = 10
+hidden_dims = [128, 64]
+dropout = 0.1
+l1_strength = 1e-3
+lap_strength = 1e-4
+```
+
+Override from CLI if needed:
+
+```bash
+--epochs 50 --latent-dim 20
+```
+
+---
+
+## PPI Priors
+
+BSVAE supports automatic download & caching of **STRING v12.0 PPI networks**.
+
+* Supported species (via NCBI TaxID):
+
+  * Human (`9606`)
+  * Mouse (`10090`)
+  * Rat (`10116`)
+  * Fly (`7227`)
+* Cache location defaults to `~/.bsvae/ppi` (override via `--ppi-cache`).
+
+---
+
+## Citation
+
+If you use **BSVAE** in your research, please cite:
+
+```
+@article{Benjamin2025bsvae,
+  title={Structured Factor Variational Autoencoder with Biological Priors},
+  author={Kynon J. M. Benjamin},
+  year={2025},
+  journal={N/A}
+}
+```
+
+---
+
+## License
+
+This project is licensed under the [MIT License](LICENSE).
+

bsvae-0.1.1/README.md

@@ -0,0 +1,146 @@
+# BSVAE: Biologically Structured Variational Autoencoder
+
+[![PyTorch](https://img.shields.io/badge/PyTorch-%3E%3D2.0-orange)](https://pytorch.org/)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+**BSVAE** is a PyTorch package for **Structured Factor Variational Autoencoders** (StructuredFactorVAE).  
+It is designed for **gene expression modeling with biological priors**, integrating **protein–protein interaction (PPI) networks** and **sparsity constraints** for interpretable latent representations.
+
+---
+
+## Features
+
+- **Structured VAE architecture** (`StructuredFactorVAE`)
+  - Factorized encoder/decoder with group sparsity
+  - Optional Laplacian regularization from PPI networks
+- **Dataset utilities**
+  - Load gene expression matrices (`GeneExpression`)
+  - Support for CSV full-matrix mode or pre-split train/test mode
+- **Biological priors**
+  - Fetch and cache STRING PPI networks by NCBI TaxID
+  - Map gene symbols / Ensembl IDs to protein IDs using MyGene.info or BioMart
+- **Training and evaluation**
+  - Unified training loop (`Trainer`)
+  - Evaluation with reconstruction, KL, sparsity, and Laplacian penalties (`Evaluator`)
+- **Reproducibility**
+  - Save/load models + metadata (`modelIO`)
+  - Configurable hyperparameters via `hyperparam.ini`
+
+---
+
+## Installation
+
+Clone the repo and install with [Poetry](https://python-poetry.org/) (recommended):
+
+```bash
+git clone https://github.com/YOUR-LAB/BSVAE.git
+cd BSVAE
+poetry install
+````
+
+Or using pip:
+
+```bash
+pip install -e .
+```
+
+Dependencies:
+
+* Python 3.9+
+* PyTorch ≥ 2.0
+* pandas, numpy, scikit-learn
+* networkx, scipy
+* mygene (for gene annotation)
+
+---
+
+## Quickstart
+
+### 1. Prepare gene expression data
+
+BSVAE expects **genes × samples** CSVs.
+
+* **Full-matrix mode**:
+  Provide `expr.csv` with all samples → 10-fold CV split is created.
+* **Pre-split mode**:
+  Provide directory with `X_train.csv` and `X_test.csv`.
+
+### 2. Train a model
+
+```bash
+poetry run python -m bsvae.main exp1 \
+    --gene-expression-filename data/expr.csv \
+    --epochs 50 \
+    --latent-dim 10 \
+    --ppi-taxid 9606
+```
+
+* Results (checkpoints, logs, metadata) saved under `results/exp1/`.
+
+### 3. Evaluate a trained model
+
+```bash
+poetry run python -m bsvae.main exp1 \
+    --gene-expression-filename data/expr.csv \
+    --is-eval-only
+```
+
+---
+
+## ⚙Configuration
+
+Hyperparameters can be set via `hyperparam.ini`:
+
+```ini
+[Custom]
+seed = 42
+no_cuda = False
+epochs = 100
+batch_size = 64
+latent_dim = 10
+hidden_dims = [128, 64]
+dropout = 0.1
+l1_strength = 1e-3
+lap_strength = 1e-4
+```
+
+Override from CLI if needed:
+
+```bash
+--epochs 50 --latent-dim 20
+```
+
+---
+
+## PPI Priors
+
+BSVAE supports automatic download & caching of **STRING v12.0 PPI networks**.
+
+* Supported species (via NCBI TaxID):
+
+  * Human (`9606`)
+  * Mouse (`10090`)
+  * Rat (`10116`)
+  * Fly (`7227`)
+* Cache location defaults to `~/.bsvae/ppi` (override via `--ppi-cache`).
+
+---
+
+## Citation
+
+If you use **BSVAE** in your research, please cite:
+
+```
+@article{Benjamin2025bsvae,
+  title={Structured Factor Variational Autoencoder with Biological Priors},
+  author={Kynon J. M. Benjamin},
+  year={2025},
+  journal={N/A}
+}
+```
+
+---
+
+## License
+
+This project is licensed under the [MIT License](LICENSE).

bsvae-0.1.1/pyproject.toml

@@ -0,0 +1,40 @@
+[tool.poetry]
+name = "bsvae"
+version = "0.1.1"
+description = ""
+readme = "README.md"
+authors = ["Kynon J Benjamin <kj.benjamin90@gmail.com>"]
+packages = [{ include = "bsvae", from = "src" }]
+
+[tool.poetry.dependencies]
+python = ">=3.11,<3.14"
+torch = ">=2.8.0,<3.0.0"
+numpy = "<2.3"
+pandas = ">=2.3.2,<3.0.0"
+scikit-learn = ">=1.7.2,<2.0.0"
+tqdm = ">=4.67.1,<5.0.0"
+mygene = ">=3.2.2,<4.0.0"
+networkx = ">=3.5,<4.0"
+scipy = ">=1.16.2,<2.0.0"
+
+[tool.poetry.scripts]
+bsvae-train = "bsvae.main:cli"
+
+[tool.poetry.group.dev.dependencies]
+pytest = ">=8.4.2,<9.0.0"
+pytest-cov = ">=7.0.0,<8.0.0"
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+
+[tool.poetry-dynamic-versioning]
+enable = false
+style = "pep440"
+dirty = false
+
+[build-system]
+requires = [
+    "poetry-core>=2.0.0,<3.0.0",
+    "poetry-dynamic-versioning[plugin]"
+]
+build-backend = "poetry_dynamic_versioning.backend"

bsvae-0.1.1/src/bsvae/hyperparam.ini

@@ -0,0 +1,82 @@
+[Custom]
+    # General options
+    log_level = "info"
+    no_progress_bar = False
+    no_cuda = False
+    seed = 1234
+
+    # Training options
+    epochs = 100
+    batch_size = 64
+    lr = 5e-4
+    checkpoint_every = 30
+    dataset = "genenet"
+    experiment = "structured"
+
+    # Model options
+    model = "StructuredFactorVAE"
+    latent_dim = 10
+    hidden_dims = [512, 256]   # encoder hidden layers
+    dropout = 0.1
+    init_sd = 0.02
+    learn_var = False          # decoder per-gene variance
+
+    # Loss options
+    loss = "beta"
+    beta = 1.0                 # KL weight
+    l1_strength = 1e-3         # sparsity regularizer
+    lap_strength = 1e-4        # Laplacian smoothness
+
+    # Evaluations
+    is_metrics = True
+    no_test = False
+    is_eval_only = False
+    eval_batchsize = 512
+
+
+# ### DATASET COMMON ###
+[Common_genenet]
+    dataset = "genenet"
+    checkpoint_every = 100
+    epochs = 400
+
+
+# ### LOSS COMMON ###
+[Common_VAE]
+    loss = "VAE"
+    lr = 5e-4
+[Common_beta]
+    loss = "beta"
+    beta = 4.0
+    lr = 5e-4
+
+
+# ### EXPERIMENT SPECIFIC ###
+
+[VAE_genenet]
+    dataset = "genenet"
+    model = "StructuredFactorVAE"
+    loss = "VAE"
+    latent_dim = 8
+    epochs = 400
+    checkpoint_every = 50
+    lr = 1e-4
+    l1_strength = 1e-3
+    lap_strength = 1e-4
+
+[beta_genenet]
+    dataset = "genenet"
+    model = "StructuredFactorVAE"
+    loss = "beta"
+    beta = 4.0
+    latent_dim = 8
+    epochs = 400
+    checkpoint_every = 50
+    lr = 1e-4
+    l1_strength = 5e-4
+    lap_strength = 5e-5
+
+[debug]
+    epochs = 1
+    log_level = "debug"
+    no_test = True

bsvae-0.1.1/src/bsvae/main.py

@@ -0,0 +1,237 @@
+#!/usr/bin/env python
+
+import sys
+import logging
+import argparse
+from os.path import join, dirname
+from configparser import ConfigParser
+
+import torch
+from torch import optim
+
+from bsvae.models import StructuredFactorVAE
+from bsvae.models.losses import BaseLoss
+from bsvae.utils.datasets import get_dataloaders
+from bsvae.utils.helpers import (
+    set_seed,
+    get_device,
+    get_n_params,
+    create_safe_directory,
+    FormatterNoDuplicate,
+    get_config_section,
+    update_namespace_,
+)
+from bsvae.utils import Trainer, Evaluator
+from bsvae.utils.ppi import load_ppi_laplacian
+from bsvae.utils.modelIO import save_model, load_model, load_metadata
+
+RES_DIR = "results"
+
+def load_config(config_path: str, section: str = "Custom") -> dict:
+    """Load hyperparameters from .ini file."""
+    parser = ConfigParser()
+    parser.read(config_path)
+    if section not in parser:
+        raise ValueError(f"Config section [{section}] not found in {config_path}")
+    return {k: ast_literal_eval(v) for k, v in parser[section].items()}
+
+
+def ast_literal_eval(val):
+    """Helper to parse lists, ints, floats from strings safely."""
+    import ast
+    try:
+        return ast.literal_eval(val)
+    except Exception:
+        return val
+
+
+def parse_arguments(cli_args):
+    """Parse CLI args, with defaults pulled from hyperparam.ini."""
+    pre_parser = argparse.ArgumentParser(add_help=False)
+    pre_parser.add_argument("--config", "-c", type=str,
+                            default=join(dirname(__file__), "hyperparam.ini"),
+                            help="Path to hyperparam.ini")
+    pre_parser.add_argument("--section", type=str, default="Custom",
+                            help="Section of .ini to load")
+    config_args, _ = pre_parser.parse_known_args(cli_args)
+
+    # Load defaults from config
+    config = load_config(config_args.config, config_args.section)
+
+    parser = argparse.ArgumentParser(
+        description="Training and evaluation for StructuredFactorVAE.",
+        formatter_class=FormatterNoDuplicate,
+        parents=[pre_parser],
+    )
+
+    # General
+    parser.add_argument("name", type=str, help="Experiment name.")
+    parser.add_argument("--seed", type=int, default=config.get("seed", 13))
+    parser.add_argument("--no-cuda", action="store_true",
+                        default=config.get("no_cuda", False))
+
+    # Training
+    parser.add_argument("--epochs", type=int, default=config.get("epochs", 100))
+    parser.add_argument("--batch-size", type=int,
+                        default=config.get("batch_size", 64))
+    parser.add_argument("--lr", type=float, default=config.get("lr", 5e-4))
+    parser.add_argument("--checkpoint-every", type=int,
+                        default=config.get("checkpoint_every", 10))
+
+    # Model
+    parser.add_argument("--latent-dim", "-z", type=int,
+                        default=config.get("latent_dim", 10))
+    parser.add_argument("--hidden-dims", "-Z", type=ast_literal_eval,
+                        default=config.get("hidden_dims", [128, 64]))
+    parser.add_argument("--dropout", type=float,
+                        default=config.get("dropout", 0.1))
+    parser.add_argument("--learn-var", action="store_true",
+                        default=config.get("learn_var", False))
+    parser.add_argument("--init-sd", type=float,
+                        default=config.get("init_sd", 0.02))
+
+    # Loss
+    parser.add_argument("--loss", type=str, default=config.get("loss", "VAE"),
+                        choices=["VAE", "beta"])
+    parser.add_argument("--beta", type=float, default=config.get("beta", 1.0))
+    parser.add_argument("--l1-strength", type=float,
+                        default=config.get("l1_strength", 1e-3))
+    parser.add_argument("--lap-strength", type=float,
+                        default=config.get("lap_strength", 1e-4))
+
+    # Evaluation
+    parser.add_argument("--is-eval-only", action="store_true",
+                        default=config.get("is_eval_only"))
+    parser.add_argument("--no-test", action="store_true",
+                        default=config.get("no_test"))
+    parser.add_argument("--eval-batchsize", type=int,
+                        default=config.get("eval_batchsize"))
+
+    # Dataset
+    parser.add_argument("--dataset", type=str,
+                        default=config.get("dataset", "genenet"))
+    parser.add_argument("--gene-expression-filename", type=str,
+                        default=config.get("gene_expression_filename", None),
+                        help="CSV with gene expression (genes x samples).")
+    parser.add_argument("--gene-expression-dir", type=str,
+                        default=config.get("gene_expression_dir", None),
+                        help="Directory with train/test splits (X_train.csv, X_test.csv).")
+
+    # PPI Priors
+    parser.add_argument("--ppi-taxid", type=str, default=config.get("ppi_taxid", "9606"))
+    parser.add_argument("--ppi-cache", type=str, default=config.get("ppi_cache", None))
+
+    args = parser.parse_args(cli_args)
+
+    # Validate dataset input
+    if bool(args.gene_expression_filename) == bool(args.gene_expression_dir):
+        parser.error("Specify exactly one of --gene-expression-filename or --gene-expression-dir.")
+
+    parser.set_defaults(**vars(args))
+    return parser.parse_args(cli_args)
+
+
+def setup_logging():
+    log_fmt = "%(asctime)s %(levelname)s: %(message)s"
+    logging.basicConfig(level=logging.INFO, format=log_fmt)
+    return logging.getLogger(__name__)
+
+
+def main(args):
+    logger = setup_logging()
+    set_seed(args.seed)
+    device = get_device(use_gpu=not args.no_cuda)
+    exp_dir = join(RES_DIR, args.name)
+    logger.info(f"Experiment directory: {exp_dir}")
+
+    # Training
+    if not args.is_eval_only:
+        create_safe_directory(exp_dir, logger=logger)
+
+        # Data
+        train_loader = get_dataloaders(
+            dataset=args.dataset,
+            batch_size=args.batch_size,
+            logger=logger,
+            train=True,
+            drop_last=True,
+            gene_expression_filename=args.gene_expression_filename,
+            gene_expression_dir=args.gene_expression_dir,
+        )
+        n_genes = train_loader.dataset[0][0].shape[-1]
+        logger.info(f"Training dataset size: {len(train_loader.dataset)}")
+
+        # PPI Laplacian
+        try:
+            gene_list = getattr(train_loader.dataset, "genes", None)
+            if gene_list is not None:
+                L, G = load_ppi_laplacian(
+                    gene_list,
+                    taxid=args.ppi_taxid,
+                    min_score=700,
+                    cache_dir=args.ppi_cache or "~/.bsvae/ppi",
+                )
+                logger.info(f"PPI Graph loaded: {G.number_of_nodes()} nodes, {G.number_of_edges()} edges")
+            else:
+                L = None
+        except Exception as e:
+            logger.warning(f"Could not load PPI Laplacian: {e}")
+            L = None
+
+        # Model
+        model = StructuredFactorVAE(
+            n_genes=n_genes,
+            n_latent=args.latent_dim,
+            hidden_dims=args.hidden_dims,
+            dropout=args.dropout,
+            init_sd=args.init_sd,
+            learn_var=args.learn_var,
+            L=L
+        ).to(device)
+        logger.info(f"Model initialized with {n_genes} genes, {args.latent_dim} latent dims")
+
+        # Loss + optimizer
+        optimizer = optim.Adam(model.parameters(), lr=args.lr)
+        loss_f = BaseLoss(beta=args.beta,
+                          l1_strength=args.l1_strength,
+                          lap_strength=args.lap_strength)
+
+        trainer = Trainer(
+            model, optimizer, loss_f, device=device, logger=logger,
+            save_dir=exp_dir, is_progress_bar=not args.no_cuda,
+        )
+        trainer(train_loader, epochs=int(args.epochs),
+                checkpoint_every=int(args.checkpoint_every))
+        save_model(trainer.model, exp_dir, metadata=vars(args))
+
+    # Evaluation
+    if not args.no_test:
+        model = load_model(exp_dir, is_gpu=not args.no_cuda)
+        metadata = load_metadata(exp_dir)
+        test_loader = get_dataloaders(
+            dataset="genenet",
+            batch_size=args.eval_batchsize,
+            shuffle=False,
+            logger=logger,
+            train=False,
+            drop_last=True,
+            gene_expression_filename=args.gene_expression_filename,
+            gene_expression_dir=args.gene_expression_dir,
+        )
+        loss_f = BaseLoss(beta=args.beta,
+                          l1_strength=args.l1_strength,
+                          lap_strength=args.lap_strength)
+        evaluator = Evaluator(
+            model, loss_f, device=device, logger=logger, save_dir=exp_dir,
+            is_progress_bar=not args.no_cuda,
+        )
+        evaluator(test_loader)
+
+
+def cli():
+    args = parse_arguments(sys.argv[1:])
+    main(args)
+
+
+if __name__ == "__main__":
+    cli()

bsvae-0.1.1/src/bsvae/models/__init__.py

@@ -0,0 +1,4 @@
+from .vae import BaseVAE
+from .encoder import StructuredEncoder
+from .decoder import StructuredDecoder
+from .structured import StructuredFactorVAE