SVVS: a grammar-based complex SV signature visualizer and solver

Table of Contents

Overview
  Key Functionality
  Terminology
Installation
Quick Start
Documentation
Authors

Overview

svvs is a lightweight tool for the analysis of complex structural variant (SV) signatures, which links grammar-based rearrangement expressions and their corresponding alignment-based genomic signals.

Key Functionality

• Visualization (GUI/CLI): generates the split-read alignment signature, copy number (CN) profile, an adjacency graph for a grammatically-defined SV (e.g., ABC → abCa)

• SV signature resolution (CLI): identifies all grammatical expressions consistent with a specific SV signature (novel adjacencies and CN profile), with support for adjacency and CN uncertainty.

• Equivalence search (CLI): identifies all distinct grammatical expressions that produce identical SV signatures.

Terminology

• SV Grammar: defines a set of operations on reference intervals (REF), which can be used to represent their sequence and orientation in the ALT allele as induced by a specific SV (e.g., ABC (REF) → AcbaC (ALT); note: lowercase symbols are used to represent inversions).

• Split Reads: reads that align non-contiguously to the reference, indicating structural junctions/breakpoints.

• Copy Number (CN) Profile: the count of each reference interval present in the ALT sequence.

• Adjacency/Breakpoint Graph: a graph-based SV representation where nodes are reference intervals and edges represent either reference adjacencies or novel sample-specific adjacencies.

Installation

1. Clone the repository: git clone git@github.com:PopicLab/svvs.git
2. Navigate into the top-level folder: cd svvs
3. Set up a Conda environment:
   • Create the environment from the provided .yml file: conda env create --file svvs_env.yml
   • Activate the environment: conda activate svvs_env
4. Install the framework: pip install .
5. Set the PYTHONPATH: export PYTHONPATH=${PYTHONPATH}:/path/to/svvs

Quick Start

Execution

1. Visualization
   You can visualize SV signatures either interactively or via the command line.

• Interactive App: iteratively generate and inspect SV signatures.

    svvs app

• CLI: generate a single plot for a specific rearrangement expression.

  svvs plot --ref <str> --alt <str> --output </path/to/output.svg>

2. SV signature resolution
   Find all the ALT sequences that are consistent with a given SV signature.

   svvs solve --config <config_file.yml>

3. Equivalence search
   Find all the ALT sequences that would produce the same SV signature as the given expression.

   svvs equiv --ref <str> --alt <str> --output_dir <path>

Documentation

For detailed information about how to use svvs, please consult the following documentation:

• User Guide
• Example Solver Config

Authors

Patrick Schlaeger - pschlaeg@broadinstitute.org

Victoria Popic - vpopic@broadinstitute.org