mil2het 0.1.0

Single-cell biomarker modeling and analysis toolkit.

mil2het

A Python toolkit for single-cell biomarker discovery using multiple instance learning and multi-view gene embeddings.

Overview

mil2het implements a two-phase workflow for identifying biomarkers from single-cell RNA sequencing data:

1. Training Phase: Learns cell-level representations using graph neural networks and aggregates patient-level predictions via multiple instance learning (MIL)
2. Analysis Phase: Identifies candidate biomarkers through network propagation and multi-view prior integration

The module supports multi-view gene embeddings (e.g., protein language model embeddings, PPI-derived embeddings) to incorporate prior biological knowledge into the biomarker discovery process.

Installation

From PyPI (recommended)

pip install mil2het

With encoder support

For GPU-accelerated cell encoding and training:

pip install "mil2het[encoder]"
pip install torch  # install PyTorch for your system
pip install torch-scatter  # install matching your PyTorch version

From source

git clone https://github.com/32127003/scbiomarker.git
cd scbiomarker
pip install -e ".[encoder]"

Requirements

• Python >= 3.10
• PyTorch >= 1.12 (optional, for encoder/training)
• torch-scatter >= 2.1 (optional, for encoder/training)

Quick Start

Command Line Interface

# Basic usage with required columns
mil2het data.h5ad \
  --patient patient_id \
  --celltype cell_type \
  --label condition \
  --ppi pathway_network.tsv

# With multi-view gene embeddings
mil2het data.h5ad \
  --patient patient_id \
  --celltype cell_type \
  --label condition \
  --ppi pathway_network.tsv \
  --gene-embedding esm=./embeddings/esm_embeddings.pt \
  --gene-embedding ppi=./embeddings/ppi_embeddings.pt

# Training only (skip analysis)
mil2het data.h5ad \
  --patient patient_id \
  --celltype cell_type \
  --label condition \
  --train-only

# Analysis only (requires pretrained checkpoint)
mil2het --run-dir ./outputs/training_run --analysis-only

Python API

from mil2het import run_pipeline, PipelineResult

# Run full pipeline
result: PipelineResult = run_pipeline(
    input_h5ad="data.h5ad",
    patient_column="patient_id",
    celltype_column="cell_type",
    label_column="condition",
    ppi_path="pathway_network.tsv",
    embedding_views={
        "esm": "./embeddings/esm_embeddings.pt",
        "ppi": "./embeddings/ppi_embeddings.pt",
    },
    epochs=200,
    lr=0.0003,
)

# Access outputs
print(f"Training run: {result.run_dir}")
print(f"Analysis output: {result.analysis_output_dir}")
print(f"Phases completed: {result.phases_completed}")

Using AnnData directly

import scanpy as sc
from mil2het import run_pipeline

adata = sc.read_h5ad("data.h5ad")

result = run_pipeline(
    adata=adata,
    patient_column="patient_id",
    celltype_column="cell_type",
    label_column="condition",
    ppi_path="pathway_network.tsv",
)

Configuration

Use YAML configuration files for reproducible workflows:

# config.yaml
workflow:
  input_h5ad: "data.h5ad"
  output_root: "./outputs/mil2het"
  num_folds: 5
  seed: 42
  train_only: false

columns:
  patient: "patient_id"
  celltype: "cell_type"
  label: "condition"

labels:
  positive: ["disease", "case"]
  negative: ["control", "healthy"]

resources:
  ppi_path: "pathway_network.tsv"
  embedding_views:
    esm: "./embeddings/esm_embeddings.pt"
    ppi: "./embeddings/ppi_embeddings.pt"

training:
  epochs: 200
  lr: 0.0003
  k: 2000  # number of preselected genes

mil2het --config config.yaml

Key Components

Cell Encoders

Graph neural network encoders for learning cell representations:

from mil2het import GraphCellEncoder, TransformerConvCellEncoder

# Graph attention-based encoder
encoder = GraphCellEncoder(
    input_dim=embedding_dim,
    hidden_dim=256,
    num_layers=3,
)

# Transformer-based encoder
encoder = TransformerConvCellEncoder(
    input_dim=embedding_dim,
    hidden_dim=256,
    heads=4,
)

Multiple Instance Learning

Patient-level aggregation using gated attention MIL:

from mil2het import GatedAttentionMIL, PatientMILAggregator

mil = GatedAttentionMIL(
    input_dim=256,
    hidden_dim=128,
    num_classes=2,
)

Multi-View Prior Integration

from mil2het import MultiViewPriorInterfaceFIND

prior = MultiViewPriorInterfaceFIND(
    embedding_views={"esm": emb_esm, "ppi": emb_ppi},
    hidden_dim=256,
)

Pipeline Outputs

Directory	Contents
splits/	Cross-validation fold splits
preselection/	Preselected gene sets per fold
training/	Model checkpoints and training logs
analysis/	Biomarker candidates and pathway enrichment results

Development

Running Tests

# Install development dependencies
pip install -e ".[encoder]" pytest

# Run CPU-only tests
pytest tests --cpu-only

# Run all tests (requires GPU)
pytest tests

Building

pip install build
python -m build

Documentation

Build the Sphinx documentation locally with the docs dependency group:

uv sync --group docs
env -u VIRTUAL_ENV uv run sphinx-build -E -b html -W --keep-going docs docs/_build/html

The generated HTML is written to docs/_build/html/ and is intentionally not tracked by Git.

Read the Docs

Hosted documentation is configured by .readthedocs.yaml at the repository root. Read the Docs should import this repository, build the branch that contains the config file, install dependencies with uv sync --group docs, and use docs/conf.py as the Sphinx configuration.

The hosted build intentionally does not install the CUDA/PyTorch stack from requirements.txt. docs/conf.py mocks optional Torch imports for autodoc so the API reference can build on Read the Docs' CPU build image. If model autodoc is expanded to require real Torch introspection, update the docs dependency strategy deliberately rather than adding the full training stack by default.

Citation

If you use mil2het in your research, please cite:

@inproceedings{ju2026scbiomarker,
  title={scbiomarker: Multi-View Biomarker Discovery from Single-Cell Data},
  author={Ju, et al.},
  booktitle={ECCB},
  year={2026}
}

License

MIT License. See LICENSE for details.