Skip to content

user_guide.md

Latest commit

 

History

History
169 lines (127 loc) · 5.94 KB

user_guide.md

File metadata and controls

169 lines (127 loc) · 5.94 KB

User Guide

Table of Contents

Inputs
Outputs
  Visualization
  Solver
Examples
  GUI
  Solver
Interpreting plots
  Colors
  Examples

Inputs

The input parameters for each svvs command are listed below.

  • app Launches the interactive GUI to visualize SV signatures (split-read alignments, copy number (CN) profile, an adjacency graph) for any grammar-defined SV.

  • plot Generates a single SV signature plot for a specific grammatical expression.
    --ref [required]: REF string (e.g. 'ABC')
    --alt [required]: ALT string (e.g. 'AABc')
    --output [required]: Output file path
    --ploidy [optional]: Ploidy: haploid, het, or hom (default: haploid)

  • solve Finds all the possible ALT sequences that are consistent with an SV signature (adjacency and CN profile).
    --config [required]: YAML config file specifying the SV signals (see Solver Config File).

  • equiv Determines all the ALT sequences that are equivalent to a given query:
    --ref [required]: Reference grammar string (e.g. 'ABC')
    --alt [required]: Alternate grammar string (e.g. 'AABc')
    --output_dir [required]: Output directory
    --cpus [optional]: Number of CPUs to use for parallel processing (default: 1)

Outputs

Visualization

svvs plots can be saved to .svg and .pdf format from the GUI or the plot command.

Solver

The svvs solve command will generate a solutions.csv file containing all possible solutions for a given query in the following format.

REF ALT Ploidy CN Conflict Set
ABCD ADdcccbAB het 3,3,4,3 1
CSV Fields
  1. REF: reference sequence
  2. ALT: ALT sequence
  3. Ploidy: Ploidy
  4. CN: sequence of numbers corresponding to the CN of each REF segment (i.e., A: 3, B: 3, C: 4, D: 3)
  5. Conflict: optional adjacencies that are not satisfied by this solution
  6. Set: ID of the solution set; solutions with the same ploidy, CNs, and adjacencies are grouped into the same solution set

If plot is set to True in the config file, svvs will also generate a plot (PDF format) for each solution set (one ALT sequence per set will be randomly selected for plotting).

Examples

Visualizing SV signatures with the GUI

The svvs GUI can be used to interactively visualize complex SV signatures. The snapshots below capture several examples of custom complex SVs signatures with varying ploidy (which alters the CN profile), REF, and ALT sequences.

Resolving SV signatures with the solver

The svvs solver can search for all possible rearrangements (ALT sequences) that fit a user-provided SV signature, defined in a YAML file. The following example shows the solutions found by svvs for the configuration below.

# Configuration

output_dir: 'example'
ploidy: het
cn:
  A: 3 
  B: 3
  C: [3, 4] # allow for 3 or 4 (uncertain CN estimate)
  D: 3  

adj:
  - start: [B,T]
    end: [2,H]
  - start: [C,H]
    end: [C,T]
  - start: [D,T]
    end: [D,T]
  - start: [B,H]
    end: [A,H]
  - start: [A,T]
    end: [D,H]
Solutions:
REF ALT Ploidy CN Set
ABCD ABCCDdaB het 3,3,3,3 1
ABCD ADdccbaB het 3,3,3,3 1
ABCD ADdccbAB het 3,3,3,3 1
ABCD ABCCCDdaB het 3,3,4,3 2
ABCD ADdcccbaB het 3,3,4,3 2
ABCD ADdcccbAB het 3,3,4,3 2
Plots

The solver can also be used to find all equivalent ALT sequences. The solutions for svvs equiv --ref ABC --alt AcABC are shown below.

REF ALT Ploidy CN Set
ABC ABCaC haploid 2,1,2 1
ABC AcABC haploid 2,1,2 1
ABC AcbaC haploid 2,1,2 1

Interpreting svvs plots

Read alignment and graph edge color encoding

Read alignments and graph edges are colored according to the adjacency orientation, with the four colors corresponding to the LR (red), RL (green), LL (cyan), and RR (blue) orientations, respectively (using the same color scheme as IGV).

Examples

DEL Simple deletion: A->

The plot depicts a simple deletion of reference segment A, which results in a novel adjacency between the tail of the segment to the left and the head of the segment to the right of the deletion, respectively. svvs shows the corresponding (1) split read alignments in the LR orientation (red), (2) CN profile showing a full drop in coverage for the A segment (assuming a haploid genome), and (3) the adjacency graph depicting the new LR adjacency formed between the two segments flanking the deletion.

dDUP Dispersed duplication: AB->ABA

The plot illustrates a dispersed duplication of segment A, resulting in two novel adjacency between the segments flanking the insertion point of the new copy of A and the source segment.