SVGram

SVGram reconstructs clone-resolved complex structural variant (CSV) paths from clone copy-number profiles and structural-variant junction calls.

The repository contains the Python implementation used for:

1. converting SV and clone copy-number tables into an SVGram graph,
2. adding reference-adjacency support from BAM files when available,
3. solving clone-specific junction multiplicities with an ILP, and
4. reconstructing copy-number-consistent derivative chromosome paths.

Availability

• Code: https://github.com/deepomicslab/SVGram
• Data and processed analysis artifacts: https://doi.org/10.5281/zenodo.20391483
• License: MIT

Installation

Python 3.9 or later is recommended.

The recommended setup creates a conda environment and builds the optional Ambigram C++ component:

bash scripts/install_svgram.sh
conda activate svgram

For a Python-only installation, skip the optional C++ build:

bash scripts/install_svgram.sh --skip-ambigram
conda activate svgram

To install only the Python dependencies in an existing environment:

pip install -r requirements.txt

The core Python workflow depends on pandas, pulp, and pysam. PuLP uses CBC by default when available. The optional Ambigram/ C++ component requires CMake, a C++ compiler, htslib, zlib, and Coin-OR/Cbc development headers and libraries.

Build the optional C++ solver after activating the conda environment:

mamba env create -f environment.yml
conda activate svgram
scripts/build_ambigram.sh

If dependencies are installed in a different prefix, pass it explicitly:

scripts/build_ambigram.sh --prefix /path/to/dependency/prefix

Quick start

Run the end-to-end wrapper on tab-delimited SV and copy-number tables:

bash scripts/run_svgram_pipeline.sh \
  --sv examples/sv_resolved.tsv \
  --cn examples/cn_profile.tsv \
  --fractions examples/fractions.tsv \
  --mean-depth 30 \
  --out-dir results/example

If a coordinate-sorted and indexed BAM is available, add --bam sample.bam to compute reference-adjacency support before ILP solving.

The wrapper performs:

1. generate_graph.py to build the graph,
2. extract_ref_junc.py to add reference-adjacency support when --bam is supplied,
3. solve_graph.py to infer clone-specific balanced graphs, and
4. reconstruct_graph.py to output clone-resolved CSV paths.

Main scripts

Script	Purpose
generate_graph.py	Build an SVGram graph from SV calls and clone copy-number profiles.
extract_ref_junc.py	Count spanning reads for reference adjacencies and add them to the graph.
solve_graph.py	Assign SV junctions to clones through copy-number-aware ILP balancing.
reconstruct_graph.py	Reconstruct derivative chromosome paths from each balanced clone graph.
cpp_bfb_bridge.py	Optional bridge to the Ambigram C++ BFB solver.

Use python <script>.py --help for command-line options.

Input formats

SV table

generate_graph.py expects a tab-delimited file with at least:

chrom1  pos1  strand1  chrom2  pos2  strand2  avg_dp

avg_dp may be a single integer or a comma-separated pair.

Clone copy-number table

generate_graph.py expects a tab-delimited file with chromosome coordinates and clone columns:

chr  start  end  clone0  clone1  clone2

Clone values can be total copy numbers (2) or major/minor values (1|1). clone0 is treated as the normal clone by solve_graph.py.

Clone fractions

solve_graph.py expects:

subclone  fraction
clone0    0.20
clone1    0.55
clone2    0.25

Optional Ambigram bridge

cpp_bfb_bridge.py no longer contains machine-specific paths. Configure it with environment variables or pass explicit paths from your own wrapper:

export SVGRAM_AMBIGRAM_BINARY=/path/to/Ambigram
export SVGRAM_HTSLIB_DIR=/path/to/conda/env/lib
export SVGRAM_CBC_DIR=/path/to/conda/env/bin

If these variables are not set, the bridge searches for Ambigram on PATH and uses the current environment.