BreakDancerMax - SV detection


Usage: 


perl BreakDancerMax.pl config_file
        for perl version;
breakdancer_max config_file
        for cpp version.

Options: 


         -o STRING operate on a single chromosome [all chromosome]

         -c INT    cutoff in unit of standard deviation [3]

         -t        only detect transchromosomal rearrangement

         -p FLOAT  prior probability of SV [0.001] (cpp cannot do)

         -e        learn parameters from data before applying to SV detection (cpp cannot do)

         -l        analyze Illumina long insert (mate-pair) library

         -f        use Fisher's method to combine P values from multiple library (cpp cannot do)

         -d STRING prefix of fastq files that SV supporting reads will be saved by library

         -g FILE   dump SVs and supporting reads in BED format for GBrowse

         -m INT    maximum SV size [1000000]

         -q INT    minimum alternative mapping quality [35]

         -s INT    minimum length of a region [7]

         -b INT    buffer size for building connection [100]

         -r INT    minimum number of read pairs required to establish a connection

         -x INT    maximum threshold of haploid sequence coverage for regions to be ignored [1000]

	     -a	       print out copy number by bam file rather than library, by default on

	     -h	       print out Allele Frequency column, by default off

	     -y INT    output score filter [30]

Version: BreakDancerMax-1.0

Most of these options are self-explanatory. It is convenient to use the -o option to parallelize SV detection for each chromosome. When -o is used, the detection of inter-chromosomal translocation is disabled. In that case, it may be convenient to use -t in a separate process to detect putative inter-chromosomal translocations without bothering to analyze read pairs that are mapped to the same chromosome.

The beta-test x86_64 Cpp version breakdancermax directly utilizes samtools C library. It is fully compatible with the perl version with identical usage and functions but is over 10 times faster. However, it only supports properly formated bam files and has only been tested using bam files produced by BWA. To obtain the correct result, it is important to have readgroup (@RG) tag in both the header and each alignment in the bam files. If you experience technical difficulty with the Cpp version, please email breakdancer-help@lists.sourceforge.net or consider using the perl version.

The input to BreakDancerMax-1.0 is a set of map files produced by a front-end aligner such as MAQ, BWA, NovoAlign and Bfast, and a tab-delimited configuration file that specifies the locations of the map files, the detection parameters, and the sample information.

If your map files are in the sam/bam format, you can use the bam2cfg.pl in the released package to automatic generate a configuration file (bam2cfg.pl also has dependence on AlnParser.pm in the release package). If you have a single bam file that contains multiple libraries, make sure that the readgroup and library information are properly encoded in the sam/bam header, and in each alignment record, otherwise bam2cfg.pl may fail to produce a correct configuration file. Please follow instructions on http://samtools.sourceforge.net to properly format your bam files.

An example manual configuration file is like this
map:1.map mean:219 std:18 readlen:36.00 sample:tA exe:maq-0.6.8 mapview -b
map:2.map mean:220 std:19 readlen:36.00 sample:tB exe:maq-0.6.8 mapview -b
map:3.map mean:219 std:18 readlen:36.00 sample:nA exe:maq-0.7.1 mapview -b
map:4.map mean:219 std:18 readlen:36.00 sample:nB exe:maq-0.7.1 mapview -b

An example configuration file produced by bam2cfg.pl look like this:
readgroup:2825107881 platform:illumina map:tumor.bam readlen:75.00 lib:H_KA-189941-0921313gsc-lib4
num:10001 lower:86.83 upper:443.91 mean:315.09 std:43.92 exe:samtools view
readgroup:2843249908 platform:illumina map:tumor.bam readlen:75.00 lib:H_KA-189941-0921313gsc-lib4
num:10001 lower:86.83 upper:443.91 mean:315.09 std:43.92 exe:samtools view
readgroup:2843255910 platform:illumina map:normal.bam readlen:75.00 lib:H_KA-189941-0904663-lib4
num:10001 lower:95.36 upper:443.31 mean:311.68 std:42.86 exe:samtools view
readgroup:2843255906 platform:illumina map:normal.bam readlen:75.00 lib:H_KA-189941-0904663-lib4
num:10001 lower:95.36 upper:443.31 mean:311.68 std:42.86 exe:samtools view

Each row must contain at least 6 key:value pairs (separated by colon) that specify: 


1). the location of the map file

2). the mean insert size

3). the standard deviation insert size

4). the average read length

5). a unique identifier assigned to the map file (usually representing a PE library)

6). a command line that can run by perl system calls to produce MAQ mapview alignment

In addition to the above 6 keys: map, mean, std, readlen, sample, and exe, BreakDancerMax allows users to explicitly specify the separation thresholds using the keys: upper and lower. For example: map:1.map upper:300 lower:100 readlen:36.00 sample:tA exe:maq-0.6.8 mapview -b

This will instruct BreakDancerMax to detect deletions using read pairs that are at least 300 bp apart (outer distance) and detect insertions using read pairs that are at most 100 bp apart.

The upper and the lower key:value pairs, when explicitly specified, take precedence over the upper and the lower thresholds computed from the mean, the std, and the user specified threshold in the unit of standard deviation. 


  upper: mean + std * threshold specified by user option -c

  lower: meen - std * threshold specified by user option -c

The -c option by default equals to 3. Therefore, the upper and the lower separation threshold would be: mean + 3 std and mean - 3 std respectively. It is useful to explicitly specify the upper and the lower separation thresholds when the insert size distribution is not symmetric to the mean.

The -o option enables per-chromosome/reference analysis and is much faster when the input files are in the bam format. Please index the bam file using "samtools index" to utilize this option. You need to specify the exact reference names as they are in the bam files.

When -e is on, BreakDancerMax tries to estimate the mean and the standard deviation insert size from the data instead of relying on user's spec in the configuration file. Current implementation of this estimation process is slow. So it is recommended that users can specify the accurate thresholds in the configuration file.

The -l option tell BreakDancerMax that the data is produced from Illumina long insert circularized library

The -f option uses the Fisher's methods to summarize scores from multiple libraries. It is recommended when there are many libraries. It ensures that the scores are independent of the number of libraries (uniform distribution of the P values)

The -q specifies the MAQ mapping quality threshold and can be used to skip reads that are not confidently mapped.

The -s specifies the minimal required size of a SV anchoring region from which the anomalously mapped reads are found. This parameter has some small effects on the SV detection accuracy. Increasing -s improves the specificity but also reduces the sensitivity. The default 7 bp seemed to work well.

The -b parameter specifies the number of anomalous regions resides in the RAM before SV hypotheses begin to form among these regions. The default works well in general. For dataset that is exceptionally large, it may be helpful to reduce it to cut the resident RAM usage.

The -d specifies a fastq file where all SV supporting reads will be saved in the fastq format. These reads can be realigned by other aligners such as novoalign, and then reanalyzed by BreakDancer.

Listing multiple map files in a single configuration file would automatically enable pooled analysis: reads from all the map files are jointly analyzed to find unified SV hypotheses across all the map files.