Mercurial > repos > portiahollyoak > breakdancer

comparison README @ 0:694cbef83948 draft

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
planemo upload for repository https://github.com/portiahollyoak/Tools commit 9700cff725be112c4a813f914eca946e158fbebd-dirty
author portiahollyoak
date Fri, 13 May 2016 11:47:32 -0400
parents
children
comparison
equal deleted inserted replaced
-1:000000000000 0:694cbef83948
1 BreakDancer-1.3.6, released under GPLv3, is a Cpp package that provides genome-wide detection of structural variants from next generation paired-end sequencing reads. It includes two complementary programs. BreakDancerMax predicts five types of structural variants: insertions, deletions, inversions, inter- and intra-chromosomal translocations from next-generation short paired-end sequencing reads using read pairs that are mapped with unexpected separation distances or orientation. BreakDancerMini focuses on detecting small indels (usually between 10bp and 100bp) using normally mapped read pairs. Please read our paper for detailed algorithmic description. http://www.nature.com/nmeth/journal/v6/n9/abs/nmeth.1363.html
2
3 BreakDancerMax (Update from 1.0 to 1.1 version only applied to cpp now.)
4 ----------------------
5 Usage: breakdancer_max <analysis_config_file>
6 Options:
7 -o STRING operate on a single chromosome [all chromosome]
8 -s INT minimum length of a region [7]
9 -c INT cutoff in unit of standard deviation [3]
10 -m INT maximum SV size [1000000000]
11 -q INT minimum alternative mapping quality [35]
12 -r INT minimum number of read pairs required to establish a connection [2]
13 -x INT maximum threshold of haploid sequence coverage for regions to be ignored [1000]
14 -b INT buffer size for building connection [100]
15 -t only detect transchromosomal rearrangement, by default off
16 -d STRING prefix of fastq files that SV supporting reads will be saved by library
17 -g STRING dump SVs and supporting reads in BED format for GBrowse
18 -l analyze Illumina long insert (mate-pair) library
19 -a print out copy number by bam file rather than library, by default on
20 -h print out Allele Frequency column, by default off
21 -y INT output score filter [40]
22
23 The followings are the new functions of version 1.1 from 1.0:
24
25 1. It computes the copy number based on the normalization of the whole genome or whole chromosome along with the SV detection. By default the copy number is computed by bam file, but it can also compute per library with option "-a".
26 2. The Allele Frequency column is more accurate for DEL type, with the help of the copy number computation. By default it is off. Include option "-h" if you want to look at the DEL type Allele Frequency.
27 3. Since there are numerous false positive SV calls, the output has a cutoff of the PhredQ score, which by default is 40. Make sure to use option "-y yournumber" if you want to change the cutoff.
28
29 The followings are those existing in version 1.0:
30
31 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.
32
33 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.
34
35 The input to BreakDancerMax-1.1 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.
36
37 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.
38
39 An example manual configuration file is like this
40
41 map:1.map mean:219 std:18 readlen:36.00 sample:tA exe:maq-0.6.8 mapview
42 map:2.map mean:220 std:19 readlen:36.00 sample:tB exe:maq-0.6.8 mapview
43 map:3.map mean:219 std:18 readlen:36.00 sample:nA exe:maq-0.7.1 mapview
44 map:4.map mean:219 std:18 readlen:36.00 sample:nB exe:maq-0.7.1 mapview
45
46 An example configuration file produced by bam2cfg.pl look like this:
47
48 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
49 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
50 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
51 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
52
53 Each row must contain at least 6 key:value pairs (separated by colon) that specify:
54
55 1). the location of the map file
56 2). the mean insert size
57 3). the standard deviation insert size
58 4). the average read length
59 5). a unique identifier assigned to the map file (usually representing a PE library)
60 6). a command line that can run by perl system calls to produce MAQ mapview alignment
61
62 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:
63 map:1.map upper:300 lower:100 readlen:36.00 sample:tA exe:maq-0.6.8 mapview -b
64
65 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.
66
67 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.
68 upper: mean + std * threshold specified by user option -c
69 lower: meen - std * threshold specified by user option -c
70
71 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.
72
73 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.
74
75 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.
76
77 The -l option tell BreakDancerMax that the data is produced from Illumina long insert circularized library
78
79 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)
80
81 The -q specifies the MAQ mapping quality threshold and can be used to skip reads that are not confidently mapped.
82
83 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.
84
85 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.
86
87 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.
88
89 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.
90
91
92 The output format
93 ----------------------
94 BreakDancer's output file consists of the following columns:
95
96 1. Chromosome 1
97 2. Position 1
98 3. Orientation 1
99 4. Chromosome 2
100 5. Position 2
101 6. Orientation 2
102 7. Type of a SV
103 8. Size of a SV
104 9. Confidence Score
105 10. Total number of supporting read pairs
106 11. Total number of supporting read pairs from each map file
107 12. Estimated allele frequency
108 13. Software version
109 14. The run parameters
110
111 Columns 1-3 and 4-6 are used to specify the coordinates of the two SV breakpoints. The orientation is a string that records the number of reads mapped to the plus (+) or the minus (-) strand in the anchoring regions.
112
113 Column 7 is the type of SV detected: DEL (deletions), INS (insertion), INV (inversion), ITX (intra-chromosomal translocation), CTX (inter-chromosomal translocation), and Unknown.
114 Column 8 is the size of the SV in bp. It is meaningless for inter-chromosomal translocations.
115 Column 9 is the confidence score associated with the prediction.
116 Column 11 can be used to dissect the origin of the supporting read pairs, which is useful in pooled analysis. For example, one may want to give SVs that are supported by more than one libraries higher confidence than those detected in only one library. It can also be used to distinguish somatic events from the germline, i.e., those detected in only the tumor libraries versus those detected in both the tumor and the normal libraries.
117 Column 12 is currently a placeholder for displaying estimated allele frequency. The allele frequencies estimated in this version are not accurate and should not be trusted.
118 Column 13 and 14 are information useful to reproduce the results.
119
120 Example 1:
121 1 10000 10+0- 2 20000 7+10- CTX -296 99 10 tB|10 1.00 BreakDancerMax-0.0.1 t1
122
123 An inter-chromosomal translocation that starts from chr1:10000 and goes into chr2:20000 with 10 supporting read pairs from the library tB and a confidence score of 99.
124
125 Example 2:
126 1 59257 5+1- 1 60164 0+5- DEL 862 99 5 nA|2:tB|1 0.56 BreakDancerMax-0.0.1 c4
127
128 A deletion between chr1:59257 and chr1:60164 connected by 5 read pairs, among which 2 in library nA and 1 in library tB support the deletion hypothesis. This deletion is detected by BreakDancerMax-0.0.1 with a separation threshold of 4 s.d.
129
130 Example 3:
131 1 62767 10+0- 1 63126 0+10- INS -13 36 10 NA|10 1.00 BreakDancerMini-0.0.1 q10
132
133 An 13 bp insertion detected by BreakDancerMini between chr1:62767 and chr1:63126 with 10 supporting read pairs from a single library 'NA' and a confidence score of 36.
134
135 Notes:
136 Real SV breakpoints are expected to reside within the predicted boundaries with a margin > the read length.
137
138 The BreakDancerMini code will not be included in the coming releases. We recommend using Pindel to detect intermediate size indels (10-80 bp).
139
140 Dependence over other Perl Modules
141 ------------------------------------
142 use Statistics::Descriptive;
143 use Math::CDF;
144
145 These are available at CPAN.
146 http://search.cpan.org/~colink/Statistics-Descriptive-2.6/Descriptive.pm
147 http://search.cpan.org/~callahan/Math-CDF-0.1/CDF.pm
148
149 use Poisson;
150 This is provided. Please make sure the "use lib" at the beginning of the perl scripts contains the correct path.
151
152
153 Acknowledgements
154 -----------------
155 Heng Li at Wellcome Trust Sanger Institute has contributed an early version of this code.
156 Many colleagues at The Genome Center of Washington University have supported this effort.
157
158
159 Ken Chen and Xian Fan
160 Washington University Genome Center
161
162 July 14, 2009