fjdceph/acnviewer repository overview

⁠aCNViewer

comprehensive genome-wide visualization of absolute copy number and copy neutral variations

Contact: Victor Renault / Alexandre How-Kit ([email protected]⁠)

aCNViewer (Absolute CNV Viewer) is a tool which allows the visualization of absolute CNVs and cn-LOH across a group of cancer samples. aCNViewer proposes three graphical representations : dendrograms, bidimensional heatmaps allowing the visualization of chromosomal regions sharing similar abnormality patterns and quantitative stacked histograms facilitating the identification of recurrent absolute CNVs and cn-LOH. aCNViewer include a complete pipeline allowing the processing of raw data from SNP array (in tumor-only or paired tumor / normal mode) and whole exome/genome sequencing experiments (in paired tumor / normal mode only) using respectively ASCAT and Sequenza algorithms to generate absolute CNV and cn-LOH data used for the graphical outputs.

⁠Table of contents

• Installation⁠
  • from Docker⁠
  • from source⁠
  • installation validation⁠
• Overview⁠
• Tutorial⁠:
  • Glossary⁠
  • Processing SNP array data:
    • Affymetrix⁠
      • Test using Ascat results⁠ (start here if you want an overview of all the plotting options and different usage scenarios):
        • all plots⁠
        • use custom colors for plots⁠
        • GISTIC example⁠
        • heatmap using relative copy number values⁠
        • heatmap with CNVs ordered by genomic position⁠
        • heatmap using copy number values⁠
        • dendrogram example⁠
        • custom graphical output formats⁠
      • Test using Affymetrix Cel files⁠
    • Illumina⁠
  • Processing NGS data⁠
    • from paired (tumor / normal) bams⁠
    • from Sequenza segment files⁠
  • Processing CNV file⁠
    • from ASCAT⁠
    • from PennCNV⁠
    • from Sequenza⁠
    • from other tools⁠
• Output files⁠
  • ASCAT⁠
  • GISTIC⁠
  • Sequenza⁠
  • Histogram⁠
  • Dendrograms and heatmaps⁠
• Limitations⁠
• Citation⁠

---

⁠Installation

⁠Docker installation

The easiest way to install aCNViewer is to install the Docker application⁠ (supports multi-threading but not computer clusters which are better suited for processing NGS bams): docker pull fjdceph/acnviewer

aCNViewer docker image requires about 20GB of space to install so if you run into an error while pulling the image locally, you probably need to change the location of docker images from /var/lib/docker/ to a location with more space⁠ and try again.

⁠Installation from source

aCNViewer can also be installed from its source by:

1. downloading aCNViewer's data (includes test data sets and most of the third-party softwares listed in the dependencies⁠ section)
2. installing the dependencies listed below⁠.
3. downloading the github source code from this page: git clone https://github.com/FJD-CEPH/aCNViewer

⁠Installation validation

Once aCNViewer is installed, you can run unit tests⁠ in order to check that everything is fine.

⁠Dependencies:

Most of the dependencies (except R and python), along with test data sets, are packaged in the archive aCNViewer_DATA.tar.gz⁠ in aCNViewer_DATA/bin. You can find more details below:

• APT (Affymetrix Power Tools⁠) if you plan to process raw Affymetrix SNP arrays (to uncompress into BIN_DIR)

• a recent version of R (version ≥ 3.2) with ggplot2⁠ installed for generating the different graphical outputs:

  • ASCAT⁠ (will be automatically installed if not already installed) if you are analyzing raw SNP array data
  • Sequenza⁠ (will be automatically installed if not already installed) if you are analyzing paired (tumor / normal) bams
  • plotrix⁠ for plotting dendrograms (will be automatically installed if not already installed)
  • gplots⁠
  • RColorBrewer⁠

• samtools if you are analyzing paired (tumor / normal) bams. As Sequenza does not support newer mpileup file formats produced by more recent versions of samtools, use a version prior to Sequenza release date (2015-10-10): samtools version 0.1.19⁠ for example is compatible.

• tQN⁠ if you plan to process raw Illumina SNP arrays (to uncompress into BIN_DIR⁠) and run tQN normalisation. If the cluster file for the Illumina SNP array you plan to analyze is not in the tQN lib folder, you can download additional cluster files from here⁠

• GISTIC⁠ if you want to have an advanced statistical way to prioritize regions of interest. Create a folder named GISTIC_VERSION in BIN_DIR and uncompress the GISTIC archive into it. Follow the instructions listed in INSTALL.txt at the root of the GISTIC folder in order to install MATLAB Component Runtime required by GISTIC and set the associated environment variables (LD_LIBRARY_PATH and XAPPLRESDIR).

• Python with version ≥ 2.7

⁠Overview:

---

⁠Tutorial

The results of all the examples below can be found in aCNViewer_DATA/allTests in their respective target folder. All examples of this tutorial are implemented as unit tests and can be run at once using: DOCKER_OR_PYTHON⁠ -P testAll -t TARGET_DIR [--fastTest 0 --smallMem 0 --runGISTIC 0].

If --fastTest is set to 1, only tests which run in a reasonable amount of time will be run (all tests except Illumina SNP array⁠, paired bams with Sequenza⁠, GISTIC⁠ and Affymetrix SNP arrays from CEL files⁠). If --runGistic is 1, GISTIC will be tested and if --smallMem is set 1, GISTIC will run in small memory mode and will only require about 10GB of RAM vs 50GB of RAM at the expense of a longer running time.

⁠Glossary:

Let's call:

• aCNViewer_DATA the location where the test data set aCNViewer_DATA.tar.gz⁠ has been uncompressed into

• BIN_DIR⁠ the folder containing all third-party softwares located in aCNViewer_DATA/bin. Here is the list of files and folders that should be in BIN_DIR:

  • apt-*: Affymetrix Power Tools⁠ binaries
  • ascat: contains ASCAT file for GC correction (this folder is automatically created by aCNViewer and GC files are automatically downloaded)
    • GC_Affy250k.txt
    • GC_AffySNP6_102015.txt
    • gc_done
    • GC_Illumina660k.txt
    • GC_IlluminaOmniexpress.txt
  • GISTIC*: installation folder of GISTIC⁠
  • PennCNV: contains PennCNV-Affy protocols and helper scripts (will be automatically created by aCNViewer from gw6.tar.gz⁠)
  • samtools*: installation folder of samtools⁠
  • tQN*: installation folder of tQN⁠
  • ../genomes: folder located in the parent folder of BIN_DIR with one folder per genomic build. Each genomic build folder BUILD should contain at least:
    • one file named BUILD.centro.txt with centromere positions for each chromosome of the genomic build (can be generated using curl -s "http://hgdownload.cse.ucsc\ .edu/goldenPath/BUILD/database/cytoBand.txt.gz" | gunzip -c | grep acen > BUILD.centro.txt)
    • a tab-delimited file named BUILD.chrom.sizes with 2 columns respectively chromosome name and chromosome length (can be downloaded from UCSC Genome browser)
    • optionnaly, a reference fasta file (with one of the extension .fa, .fa.gz, .fasta or .fasta.gz) if you plan to use Sequenza

• DOCKER_OR_PYTHON⁠ refers to the fact that docker run fjdceph/acnviewer or python aCNViewer/code/aCNViewer.py can be used as a prefix to run aCNViewer depending on the chosen installation method.

⁠Requirements:

Download the test data set aCNViewer_DATA.tar.gz (~5GB and ~20GB uncompressed)⁠. In terms of computing resources: if you plan to:

• run Sequenza on paired bam files, an access to a computer cluster is highly recommended as even though aCNViewer will be able to process your data in multi-threading mode, it may take quite a long time depending on the number of sample pairs to analyze
• run GISTIC in order to have a robust statistical way to prioritize recurrent regions of interest, a machine with at least 50GB of RAM is necessary with --smallMem 0 and 10GB with --smallMem 1 (this option will make GISTIC run substantially longer)

⁠Processing SNP array data

⁠Affymetrix

⁠TestAffyAscat

Generate all available plots from ASCAT segment files using base resolution for the quantitative histograms and using a window size of 2Mbp for the other plots:

DOCKER_OR_PYTHON⁠ -f aCNViewer_DATA/snpArrays250k_sty/GSE9845_lrr_baf.segments.txt -t TEST_AFFY --refBuild hg18 -w 2000000 -b aCNViewer_DATA/bin --sampleFile aCNViewer_DATA/snpArrays250k_sty/GSE9845_clinical_info2.txt

Here are other typical plots you may be interested in:

Customize colors:

DOCKER_OR_PYTHON⁠ -f aCNViewer_DATA/snpArrays250k_sty/GSE9845_lrr_baf.segments.txt -t TEST_AFFY_RCOLOR --refBuild hg18 -w 2000000 -b aCNViewer_DATA/bin --sampleFile aCNViewer_DATA/snpArrays250k_sty/GSE9845_clinical_info2.txt --rColorFile aCNViewer_DATA/rColor.txt

Quantitative histogram with GISTIC results:

DOCKER_OR_PYTHON⁠ -f aCNViewer_DATA/snpArrays250k_sty/GSE9845_lrr_baf.segments.txt -t TEST_AFFY_GISTIC --refBuild hg18 -w 2000000 -b aCNViewer_DATA/bin --runGISTIC 1

If you have trouble running this example (in particular if your machine freezes or you get the message "Killed" in the "_gistic.txt.err" file), it may be due to a lack of resources in the machine you are using. In that case, please add the following option to the command above --smallMem 1 so that GISTIC runs in compressed memory mode. You can view the GISTIC results with significant broad events⁠ and significant focal events⁠.

Heatmap of relative copy number values only for the clinical feature BCLC stage with the chromosome legend position set at 0,.55 i.e. at the left-most of the graph and at 55% on the y axis and the group legend position set at .9,1.05 (basically at the top right corner):

DOCKER_OR_PYTHON⁠ -f aCNViewer_DATA/snpArrays250k_sty/GSE9845_lrr_baf.segments.txt -t TEST_AFFY_HEATMAP1 --refBuild hg18 -w 2000000 -b aCNViewer_DATA/bin --sampleFile aCNViewer_DATA/snpArrays250k_sty/GSE9845_clinical_info2.txt --plotAll 0 --heatmap 1 --dendrogram 0 -G "BCLC stage" --chrLegendPos 0,.55 --groupLegendPos .9,1.05 --useRelativeCopyNbForClustering 1

Heatmap with regions ordered by genomic positions (only clustering on samples):

DOCKER_OR_PYTHON⁠ -f aCNViewer_DATA/snpArrays250k_sty/GSE9845_lrr_baf.segments.txt -t TEST_AFFY_HEATMAP_GENPOS --refBuild hg18 -w 2000000 -b aCNViewer_DATA/bin --sampleFile aCNViewer_DATA/snpArrays250k_sty/GSE9845_clinical_info2.txt --plotAll 0 --heatmap 1 --dendrogram 0 -G "BCLC stage" --chrLegendPos 0,.55 --groupLegendPos .9,1.05 --useRelativeCopyNbForClustering 1 --keepGenomicPosForHistogram 1

Heatmap with copy number values:

DOCKER_OR_PYTHON⁠ -f aCNViewer_DATA/snpArrays250k_sty/GSE9845_lrr_baf.segments.txt -t TEST_AFFY_HEATMAP2 --refBuild hg18 -w 2000000 -b aCNViewer_DATA/bin --sampleFile aCNViewer_DATA/snpArrays250k_sty/GSE9845_clinical_info2.txt --plotAll 0 --heatmap 1 --dendrogram 0 -G "BCLC stage" --chrLegendPos 0,.55 --groupLegendPos .9,1.05

Dendrogram with copy number values:

DOCKER_OR_PYTHON⁠ -f aCNViewer_DATA/snpArrays250k_sty/GSE9845_lrr_baf.segments.txt -t TEST_AFFY_DENDRO --refBuild hg18 -w 2000000 -b aCNViewer_DATA/bin --sampleFile aCNViewer_DATA/snpArrays250k_sty/GSE9845_clinical_info2.txt --plotAll 0 --heatmap 0 --dendrogram 1 -G "BCLC stage" -u 1

Customize output formats:

• all outputs set to pdf: DOCKER_OR_PYTHON⁠ -f aCNViewer_DATA/snpArrays250k_sty/GSE9845_lrr_baf.segments.txt -t TEST_AFFY_PDF --refBuild hg18 -w 2000000 -b aCNViewer_DATA/bin --sampleFile aCNViewer_DATA/snpArrays250k_sty/GSE9845_clinical_info2.txt --outputFormat pdf

• all output set to jpg: DOCKER_OR_PYTHON⁠ -f aCNViewer_DATA/snpArrays250k_sty/GSE9845_lrr_baf.segments.txt -t TEST_AFFY_PDF --refBuild hg18 -w 2000000 -b aCNViewer_DATA/bin --sampleFile aCNViewer_DATA/snpArrays250k_sty/GSE9845_clinical_info2.txt --outputFormat jpg

• heatmaps set to bmp, histograms to tiff and dendrograms to pdf with the R plot parameters width=10,height=8: -f aCNViewer_DATA/snpArrays250k_sty/GSE9845_lrr_baf.segments.txt -t TEST_AFFY_OTHER_OUT --refBuild hg18 -w 2000000 -b aCNViewer_DATA/bin --sampleFile aCNViewer_DATA/snpArrays250k_sty/GSE9845_clinical_info2.txt --outputFormat "heat:bmp;hist:tiff;dend:pdf(width=10,height=8)"

==Here is the full command:==

DOCKER_OR_PYTHON⁠ -f ASCAT_SEGMENT_FILE --refBuild REF_BUILD -b BIN_DIR⁠ [--histogram HISTOGRAM --lohToPlot LOH_TO_PLOT --useFullResolutionForHist USE_FULL_RESOLUTION_FOR_HIST] [-c CHR_SIZE_FILE -t OUTPUT_DIR -C CENTROMERE_FILE -w WINDOW_SIZE --sampleFile SAMPLE_FILE -G PHENOTYPIC_COLUMN_NAME --rColorFile RCOLOR_FILE --plotAll PLOT_ALL --outputFormat OUTPUT_FORMAT --ploidyFile PLOIDY_FILE --sampleToProcessList SAMPLE_TO_PROCESS_LIST --sampleToExcludeList SAMPLE_TO_EXCLUDE_LIST --sampleAliasFile SAMPLE_ALIAS_FILE] [--heatmap HEATMAP --labRow LAB_ROW --labCol LAB_COL --cexCol CEX_COL --cexRow CEX_ROW --height HEIGHT --width WIDTH --margins MARGINS --hclust HCLUST --groupLegendPos GROUP_LEGEND_POS --chrLegendPos CHR_LEGEND_POS --useRelativeCopyNbForClustering USE_RELATIVE_COPY_NB_FOR_CLUSTERING --keepGenomicPosForHistogram KEEP_GENOMIC_POS] [--dendrogram DENDROGRAM --useShape USE_SHAPE] [--runGISTIC RUN_GISTIC --geneGistic GENE_GISTIC --smallMem SMALL_MEM --broad BROAD --brLen BR_LEN --conf CONF --armPeel ARM_PEEL --saveGene SAVE_GENE --gcm GCM]
where:

• ASCAT_SEGMENT_FILE: ASCAT segment file (ascat.output$segments obtained by running ascat.runAscat) with the following columns:
  • sample
  • chr
  • startpos
  • endpos
  • nMajor
  • nMinor
• REF_BUILD: the genome build used to generate the CNV segments (hg18 and hg19 are currently supported. If you want to add another build BUILD, please add a folder in BUILD in aCNViewer_DATA/genomes containing at least a tab-delimited file named BUILD.chrom.sizes with each chromosome name and length and a tab-delimited file named BUILD.centro.txt with the centromere positions by chr [this file can be generated using curl -s "http://hgdownload.cse.ucsc.edu/goldenPath/BUILD/database/cytoBand.txt.gz" | gunzip -c | grep acen > centro_build.txt])

The following options are general plotting options:

• CHR_SIZE_FILE: a tab-delimited file with 2 columns respectively chromosome name and chromosome length. When REF_BUILD is set, CHR_SIZE_FILE is automatically set to aCNViewer_DATA/genomes/REF_BUILD.chrom.sizes.
• CENTROMERE_FILE: file giving the centromere bounds. Can be generated using curl -s "http://hgdownload.cse.ucsc.edu/goldenPath/BUILD/database/cytoBand.txt.gz" | gunzip -c | grep acen > centro_build.txt. When REF_BUILD is set, CENTROMERE_FILE is automatically set to aCNViewer_DATA/genomes/REF_BUILD.centro.txt.
• WINDOW_SIZE: segment size in bp. Please note that alternatively, -p PERCENTAGE can be used instead of -w WINDOW_SIZE in order to set the segment size in percentage of chromosome length where PERCENTAGE is a floating number between 0 and 100. If WINDOW_SIZE and PERCENTAGE are null then WINDOW_SIZE is set to 2Mb by default.
• SAMPLE_FILE: a tab-delimited file that should contain a column named Sample with the name of each sample and at least another column with the phenotypic / clinical feature. This file can contain a sampleAlias which will be used as the official sample id if provided.
• PHENOTYPIC_COLUMN_NAME is optional and refers to the name of the column of the phenotypic / clinical feature of interest in SAMPLE_FILE. If you omit this parameter, one plot per feature defined in SAMPLE_FILE will be generated.
• RCOLOR_FILE: file allowing to customize graph colors: colors for histograms can be overriden using a section named "[histogram]" which should contain exactly 10 colors [one per line] corresponding to CNV values in the following order: "≤ -4", "-3", "-2", "-1", "1", "2", "3", "4", "5", "≥ 6"). Histogram colors for heterozygous / homozygous CNVs can be changed using the section "[heteroHomo]" which should contain 6 colors corresponding to the values "-Hom", "-Het", "=Hom", "=Het", "+Hom", "+Het". Colors for dendrograms can be redefined using the section "[group]" which should contain at least the same number of colors than the number of distinct values for the phenotypic / clinical feature of interest. Colors for heatmaps are customizable using the section "[chr]" and should contain 22 colors corresponding to chromosomes 1 to 22], the section "[group]" (the same as previously seen for dendrograms) and the section "[heatmap]" which should contain 10 colors (one per line) corresponding to CNV values in the following order: "0", "1", "2", "3", "4", "5", "6", "7", "8", "≥ 9". An example can be found here⁠.
• PLOT_ALL: specify whether all available plots should be generated. The default value is 1.
• OUTPUT_FORMAT: allow to customize output formats for the different types of available plots (histograms, heatmaps and dendrograms). Examples of use can be found above⁠. The default value is hist:png(width=4000,height=1800,res=300);hetHom:png(width=4000,height=1800,res=300);dend:png(width=4000,height=2200,res=300);heat:pdf(width=10,height=12).
• PLOIDY_FILE: custom ploidy values for each sample. Can either be a tab-delimited file with at least 2 columns: "sample" and "ploidy" or an integer which will set the same ploidy to all samples. By default, the ploidy is calculated using the CNV file segmented in fragments of 10% of chromosomal length and its value will be the most represented CNV value for each sample.
• SAMPLE_TO_PROCESS_LIST: comma-separated string or file with one sample per line used to restrict the list of samples to process by aCNViewer.
• SAMPLE_TO_EXCLUDE_LIST: comma-separated string or file with one sample per line used to exclude a list of samples from analyses.
• SAMPLE_ALIAS_FILE: optional parameter used to change the sample name to a preferred sample name. It is a tab-delimited file with 2 columns: one for the sample name and a second one with the preferred sample name.

The following options are histogram specific:

• HISTOGRAM: specify whether an histogram should be generated. The default value is 0 but its value is overriden to 1 when option --plotAll 1 is set.
• LOH_TO_PLOT: histogram option for LOH plotting. Values should be one of "cn-LOH" for plotting cn-LOH only, "LOH" for LOH only, "both" for cn-LOH and LOH or "none" to disable this feature. The default value is "cn-LOH".
• USE_FULL_RESOLUTION_FOR_HIST: tell whether to plot histogram using full resolution i.e. CNVs are not segmented according to a user-defined length through windowing approach. The default value is 1. If 0, the resolution of the plot will be given by either WINDOW_SIZE⁠ or PERCENTAGE⁠.

The following options are GISTIC options (more details can be found here⁠):

• RUN_GISTIC: specify whether to run GISTIC in order to have a statistical way to prioritize regions of interest. The default value is 0.
• GENE_GISTIC: tell whether gene GISTIC algorithm should be used to calculate the significance of deletions at a gene level instead of a marker level. The default value is 1.
• SMALL_MEM: tell GISTIC whether to use memory compression at the cost of a longer runtime. The default value is 0.
• BROAD: tell GISTIC to run the broad-level analysis as well. The default value is 1.
• BR_LEN: set GISTIC's broad_len_cutoff. The default value is 0.5.
• CONF: set the confidence level used to calculate the region containing a driver. The default value is 0.9.
• ARM_PEEL: set GISTIC's arm_peeloff. The default value is 1.
• SAVE_GENE: tell GISTIC whether to save gene tables. The default value is 1.
• GCM: set GISTIC's gene_collapse_method. The default value is extreme.

The following options are mainly specific to heatmaps while a few are related to dendrograms:

• HEATMAP is an optional parameter used only if PLOT_ALL is set to 0 to tell whether to plot heatmaps or not. The default value is 1
• LAB_ROW is an optional parameter telling whether heatmap's row names (chromosomal regions) should be shown. The default value is 0
• LAB_COL is an optional parameter telling whether heatmap's column names (sample names) should be shown. The default value is 1
• CEX_COL is an opti