IsoTOP

Isoform Topological Perturbation analysis.

IsoTOP detects and quantifies the topological perturbations that isoform switching introduces into molecular interaction networks. Given an isoform-level expression matrix and a grouping variable, it builds an isoform-resolved network, specializes it to each sample, measures how the geometry of each sample departs from a reference, and reports the isoforms that drive that departure. It does not assume any particular biological hypothesis; the grouping variable and the cohort are supplied by the user.

Approach

The pipeline runs in six steps:

1. io reads the isoform TPM matrix, computes per-gene isoform fractions and detects switch events between the two groups.
2. network builds a multilayer graph whose nodes are transcripts. Splice edges connect transcripts of the same gene; interaction edges are resolved at the isoform level by a domain-gating rule based on DIGGER/NEASE domain-domain interactions.
3. sample reweights the network for each sample according to its isoform usage.
4. geometry computes the augmented Forman-Ricci curvature of every edge and summarizes the curvature shift against a reference network, together with a Laplacian spectral shift.
5. models trains a compact classifier on the resulting perturbation features.
6. interpret ranks the driver isoforms and writes a self-contained HTML report.

Bundled example

The data folder contains a worked example: 30 TCGA-COAD primary tumors and 30 GTEx normal colon samples, harmonized through the UCSC Xena Toil pipeline (transcript-level TPM, GENCODE v23), over a 54-gene panel spanning the MAP17, NUMB, Notch, Wnt, EMT, stemness, TMC and housekeeping axes. Running the pipeline on this example reproduces the report described below.

Installation

IsoTOP needs Python 3.10 or newer. The dependencies, including a CUDA build of PyTorch, are listed in requirements.txt. A graphics processing unit is optional; the pipeline also runs on CPU.

On Windows, run setup_windows.bat once to create a local virtual environment in .venv and install everything, then run run_windows.bat to execute the pipeline.

On Linux or macOS:

python -m venv .venv
.venv/bin/python -m pip install -r requirements.txt
.venv/bin/python run_analysis.py

The isoform-specific interaction layer relies on the domain data shipped with the nease package, which is installed automatically. If nease is absent the pipeline falls back to gene-level interactions.

Output

run_analysis.py writes isotop_report.html, which contains the dataset summary, the detected switch events, the per-sample perturbation distributions, the classifier performance, and the ranked driver isoforms.

Layout

isotop/
  io/         expression handling and switch detection
  network/    multilayer graph and domain-gated interactions
  sample/     per-sample networks
  geometry/   curvature and spectral descriptors
  models/     classifier
  interpret/  driver ranking and report
data/         bundled TCGA-COAD / GTEx example
run_analysis.py

License

MIT. See LICENSE.