CNView

Visualization, quantitation, and annotation of CNVs from population-scale whole-genome sequencing data.

Contact: Ryan Collins ([email protected])

All content copyright (c) 2016 Ryan Collins and is distributed under terms of the MIT license.

---

---

Table of Contents

General Information

• CNView Summary
• Accessing Reference Libraries
• Citing CNView

Code documentation

• CNView.R

Example Usage

• Getting Started
• Example A: Canonical Deletion, Single Sample
• Example B: Multiple Samples on the Same x-Axis
• Example C: Multiple Highlighted Intervals
• Example D: Disabled UCSC Annotations

---

General Information

CNView Summary

CNView is a low-profile visualization tool for read depth in batches of next-generation sequencing libraries and, more specifically, for visually inspecting sites of copy-number variation (CNV). It also implements a framework for estimating CNV probabilities and annotating CNV intervals.

We are open to tailoring applciations of CNView for specific needs or to customize plots. CNView is also under active development. Contact us at [email protected] if you have any questions or requests. Please post any issues to GitHub.

Accessing Reference Libraries

Like many depth-based CNV tools, CNView does not work on individual libraries. Instead, CNView jointly models multiple libraries simultaneously, normalizing both within and across libraries to reduce systematic coverage biases. Thus, while technically CNView will run successfully from just two libraries, generally CNVs become clearly resolvable with at least 20 total samples jointly modelled.

If you do not have access to an appropriate cohort of normative reference samples, thousands of standard Illumina WGS libraries are available from the 1,000 Genomes Project and many hundreds of other libraries are available through other public repositories like the European Nucleotide Archive (ENA) or the Sequence Read Archive (SRA).

Citing CNView

If you use CNView, please cite our preprint ( Collins et al., 2016 ).

---

Code Documentation

CNView.R

Performs joint normalization of binned coverage values across a batch of WGS libraries and facilitates visualization. Also interfaces with UCSC Genome Browser to underlay several annotation tracks.

Usage: CNView.R [options] chr start end samples.list covmatrix.bed outfile


Options:
	-c INTEGER, --compression=INTEGER
		compression scalar for rebinning, if desired [default 'NULL']

	-i CHARACTER, --highlight=CHARACTER
		tab-delimited list of coordinate pairs for intervals to highlight and color as third column; NULL disables highlighting [default NA]

	-w INTEGER, --window=INTEGER
		distance to append to both sides of input interval for viewing [default 61.8% of plot interval]

	--ymin=INTEGER
		minimum value for y axis [default NULL]

	--ymax=INTEGER
		maximum value for y axis [default NULL]

	-n INTEGER, --normDist=INTEGER
		distance outside region to use for normalization (both sides) [default 5000000]

	-s INTEGER, --subsample=INTEGER
		truncate coverage matrix to [s] samples; useful for very large cohorts [default 200]

	--gcex=INTEGER
		scalar applied to all fonts and legend [default 1]

	--names=CHARACTER
		list of custom names to be applied to each plot panel (e.g. 'mother', 'father', 'child', rather than actual sample IDs) [default NA]

	-t CHARACTER, --title=CHARACTER
		custom title for plot [default NULL]

	-p, --probs
		add CNV probabilities below each higlighted interval [default FALSE]

	-u, --noUCSC
		disable UCSC track plotting [default FALSE]

	-G, --nogenesymbols
		disable gene symbol printing below gene bodies in UCSC tracks [default FALSE]

	--tabix
		use tabix to index into coverage matrix [default FALSE]

	--noUnix
		disable use of unix coreutils [default FALSE]

	-q, --quiet
		disable verbose output [default FALSE]

	-l, --nolegend
		disable legend on plot [default TRUE]

	-h, --help
		Show this help message and exit

Usage Notes:

1. Several base-level options (such as returnData or plot) are not wrapped by the Rscript implementation. To access those features, import the R function directly and run from the R command prompt.
2. By default, CNView will randomly subsample an input matrix to include only 200 libraries (including those specified to plot). This is a useful parameter to reduce computational requirements (both memory and runtime) for large cohorts, but can be modulated with the -s/--subsample option.
3. Use the --tabix option to improve speed when reading from very large coverage matrices. However, your input matrix must be bgzipped and tabix-indexed; see the Samtools documentation for details.

---

Example Usage

Getting Started

Required Input Data
The input data for CNView is a tab-delimited bed-style matrix of binned coverage values, which can be generated by bedtools coverage followed by bedtools unionbedg (bedtools documentation). Alternatively, you can use binCov.py from the CNView sister repository, WGD. Generally, 100bp-1kb sequential bins provide a reasonable tradeoff between resolution and modeling speed on a standard 8GB two-core laptop.

An example coverage matrix at 100bp binsize for human libraries aligned to reference genome hg19 would look something like this:

Chr  Start     End       SampleA  SampleB  SampleC  ...  SampleZ
1    0         100       89       56       217      ...  141
1    100       200       98       60       230      ...  132
1    200       300       102      59       202      ...  142
...  ...       ...       ...      ...      ...      ...  ...
Y    59373200  59373300  79       48       207      ...  133
Y    59373300  59373400  89       51       196      ...  138
Y    59373400  59373500  93       68       198      ...  129

CNView has been tested on libraries ranging from 1X to >300X coverage simultaneously and appears to perform relatively consistently irrespective of the ranges of coverage between individual libraries in the same batch.

Example A

Canonical Deletion Plotted in a Single Sample
The basic use-case for CNView is to visualize a predefined CNV locus, which can be predicted from whole-genome sequencing data with many different algorithms, such as cn.MOPS, CNVnator, or GenomeSTRiP. Once a putative CNV locus is defined, visualization can be performed right out of the box with CNView by invoking CNView.R with all default parameters.

Example code to generate the above plot:

bash$ ./CNView.R 2 178714141 178760307 SFARI_d12529p1 \
                 ~/cov_matrix.bed \
                 ./ExamplePlots/CNView.ExamplePlotA.pdf \
                 --title "Example Plot A: Canonical Deletion, Single Sample \
                 --probs"

This example is visualizing a 46kb deletion of two exons from PDE11A. The first three positional arguments were the coordinates of the deletion (the highlighted region), while the other positional arguments were as follows:

• SFARI_d12529p1 is the ID of the sample being plotted, which has to exactly match one of the names of the columns in the coverage matrix.
• ~/cov_matrix.bed is the path to the input coverage matrix, like the example provided above.
• ./ExamplePlots/CNView.ExamplePlotA.pdf is the path to the desired output file (always will be pdf).
• --title overrides the default title with the subsequently supplied string in quotes.
• --probs prints the FDR-corrected probability of the highlighted window being deleted or duplicated. The q-value is calculated by evaluating the t-score at each bin overlapping the highlighted window, combining those p-values with Fisher's Method, then correcting for false discovery rate (FDR) with the Benjamini-Hochberg procedure.

Running the above code will also print some runtime diagnostics to stdout, which can alternatively be silenced with -q/--quiet:

+-------------------+
| CNView Visualizer |
|     (c) 2016      |
+-------------------+
Sample ID file 'SFARI_d12529p1' not found, assuming single sample ID provided
Attempting to connect to UCSC Genome Browser... Complete
Filtering & loading coverage matrix... Complete
Compressing coverage matrix [1,000 bp bins]...  Complete
Performing intra-sample normalization... Complete
Performing inter-sample normalization... Complete
Plotting samples to ./ExamplePlots/CNView.ExamplePlotA.pdf... Complete
Appending UCSC tracks... Complete

** FINISHED ON Thu Mar 31 14:12:43 2016 **

---

Example B

Multiple Samples on the Same x-Axis
CNView can plot up to 300 samples stacked atop the same shared x-axis. This is accomplished by passing a text file with the IDs of all samples to be plotted in place of the sample ID.

Example code to generate the above plot:

bash$ ./CNView.R 19 47636953 47687179 \
                 ~/sampleIDs.txt
                 ~/cov_matrix.bed \
                 ./ExamplePlots/CNView.ExamplePlotB.pdf \
                 --title "Example Plot B: Multiple Samples on the Same x-Axis" \
                 -w 50000 \
                 --ymin -6 \
                 --ymax 10 \
                 --probs

In this example, we're visualizing a 51kb duplication of SAE1 that occurred de novo in the child (top panel, sample SFARI_d13874p1) and is present in neither the father (middle panel, SFARI_d13874fa) nor the mother (bottom panel, SFARI_d13874mo). We're also using a few more options to illustrate how to control the plot parameters:

• ~/sampleIDs.tx is the path to the text file containing all sample IDs to be plotted (max of 300 samples/plot, which is an R system default, although this can be overwritten if needed). The contents of the file for this plot were:

bash$ cat ~/sampleIDs.txt
SFARI_d13874p1
SFARI_d13874fa
SFARI_d13874mo

• -w 50000 tells CNView to pad 50kb of additional space to the plotting window on both sides of the specified interval. By default, the plotting window will be padded with 61.8% of the size of the interval.
• --ymim and --ymax override the default y axes, which is most useful when plotting multiple samples simultaneously to get a relative.

And here's the expected stdout text:

+-------------------+
| CNView Visualizer |
|     (c) 2016      |
+-------------------+
Sample ID file 'SFARI_d12529p1' not found, assuming single sample ID provided
Attempting to connect to UCSC Genome Browser... Complete
Filtering & loading coverage matrix... Complete
Compressing coverage matrix [1,000 bp bins]...  Complete
Performing intra-sample normalization... Complete
Performing inter-sample normalization... Complete
Plotting samples to ./ExamplePlots/CNView.ExamplePlotA.pdf... Complete
Appending UCSC tracks... Complete

** FINISHED ON Thu Mar 31 14:12:43 2016 **

---

Example C

Multiple Highlighted Intervals
CNView also allows for customization of the highlighted interval(s), which can be useful if you have multiple regions of interest being visualized in the same plot.

Example code to generate the above plot:

bash$ ./CNView.R 3 8820980 8860556 \
                 ~/sampleIDs_2.txt \
                 ~/cov_matrix.bed \
                 ./ExamplePlots/CNView.ExamplePlotC.pdf \
                 --highlight ~/highlights.txt \
                 --title "Example Plot C: Multiple Highlighted Intervals" \
                 --ymin -3 \
                 --ymax 7  \
                 --probs  

Here, we're visualizing a 39.6kb paired-duplication inversion, a.k.a. "dupINVdup", wherein two duplications flank the ends of an underlying inversion. The distal (left-most) duplication is very small (611bp; highlighted in orange), so is only marginally visible at our 1kb bin resolution, while the proximal (right-most) duplication is quite clear (36.9kb; highlighted in blue). The custom highlighting is achieved by passing CNView the --highlight option with a corresponding three-column, tab-delimited file. Here, the contents of that file, ~/highlights.txt, were:

bash$ cat ~/highlights.txt 
8820980	8821591	darkorange
8823650	8860556	blue

The first two columns correspond to the intervals to highlight, and the third column corresponds to the R color to shade the interval. Also note that, if -p/--probs is specified in conjunction with -h/--highlight, separate probabilites are computed for each interval in the highlight parameters file.

Also, like before we've plotted a full family trio (child/father/mother), but unlike Example B this variant is evidently inherited from the mother (child is top panel and mother is bottom). The contents of the sample file, ~/sampleIDs_2.txt, were:

bash$ cat ~/sampleIDs_2.txt
SFARI_d14637p1
SFARI_d14637fa
SFARI_d14637mo

The output to stdout for this call should be:

+-------------------+
| CNView Visualizer |
|     (c) 2016      |
+-------------------+
Reading sample IDs from /Users/collins/sampleIDs_2.txt
Attempting to connect to UCSC Genome Browser... Complete
Filtering & loading coverage matrix... Complete
Compressing coverage matrix [10,000 bp bins]...  Complete
Performing intra-sample normalization... Complete
Performing inter-sample normalization... Complete
Plotting samples to ./ExamplePlots/CNView.ExamplePlotC.pdf... Complete
Appending UCSC tracks... Complete

** FINISHED ON Thu Mar 31 14:13:22 2016 **

---

Example D

Disabled UCSC Annotations
If you like to keep things low-profile or don't have an active internet conenction, you can disable the UCSC annotations with -u/-noUCSC and tell the verbose output to shut up with -q/-quiet.

Example code to generate the above plot:

bash$ ./CNView.R 2 178714141 178760307 SFARI_d12529p1 \
                 ~/cov_matrix.bed \
                 ./ExamplePlots/CNView.ExamplePlotD.pdf \
                 --title "Example Plot D: Disabled UCSC Annotations" \
                 --noUCSC \
                 --quiet

This example is an identical repeat of example A, just slimmed down to save on UCSC connections and stdout spam.