BBNorm官方指導文件翻譯

BBNorm Guide

Written by Brian Bushnell

Last updated December 16, 2015

BBNorm是用來對高覆蓋率的reads進行抽樣的工具，這個過程可以極大的==加速組裝==，==讓無法組裝的資料變得"可以組裝"==，==同時一般也可以極大提高組裝的質量==。此外還有：基於深度的-binning，kmer頻度直方圖，錯誤矯正，錯誤標記，基因組大小估計

BBNorm有四個顯著的特點：

1. BBNorm絕對不會run out of memory，但是如果kmers太多了會使得精度稍稍下降
2. Multipass模式可以減少normalized的輸出中的平均錯誤率，standard normalization可以富集包含錯誤的reads
3. 速度超快，並且很易用
4. 支援任何長度的kmer值

資料結構：

A Count-Min Sketch (CMS) is also called a "counting Bloom filter". 這是一種只儲存值，不存keys並且忽略衝突（collisions）的hash table。為了避免collisions帶來的負面影響，值被儲存在多個位置，儘可能保障至少有一個不會和其他的衝突。在讀取kmer數目時，所有位置都被讀取，最小值被使用

• BBNorm 可以使用1, 2, 4, 8, 16, or 32 位每cell的CMSs結構. 當位元組越大，最大計數值也可以更(up to 2^bits-1), 但是可供使用的cells更少; 例如，for example, 1GB RAM will accommodate （提供空間）4 billion 2-bit cells, 最大計數值可以為3, or 500 million 16-bit cells, 最大計數值為65535. 在我們資料預期覆蓋度是200x時，設定32-bit的單個cell大小是完全沒道理的。同時，儲存一個kmer的計數值的位置可以被設定，從1到無限大都可以（預設值為3），越多儲存位置會越準確（直到hash table變滿），但是會更慢. 確定最佳hash數，請參考Bloom filters.

Memory and Capacity:

• BBNorm預設情況下會使用所有的執行記憶體，使用越多的執行記憶體結果越準確
• 當處理很大的資料集，卻只有很小的執行記憶體可用時，會得到警告資訊：
  "Made hash table: hashes = 1 mem = 581.26 MB cells = 152.38M used = 93.540%
  Warning: This table is extremely full, which may reduce accuracy. Ideal load is under 60% used.
• 因此，可以看出，要獲得最好的精度，load儘量小於60%
• 為了更加準確：
  • 使用'prefilter'
  • 在一個節點上使用更多的執行記憶體執行
  • 質控資料或者對資料進行錯誤矯正
  • 加大minprob的值，以減少虛假的kmers
• ==在實際執行中，即便是loads超過了90%，你還是可以得到比較好的normalization結果，但是histogram和statistics會被關閉==

請不要忽略上面的資訊，在使用prefilter會把較少的kmers計數值儲存在小的cells上（預設為2-bit），把大的計數值儲存在大的cells上 (預設32-bit)，這時候memory可以被更加高效的使用。 Prefilter在預設情況下是關閉的，但是當我們很需要==準確性==的時候，或者==tables實在是有點滿了==（比如normalization時超過了50%，在error correction時我們希望loads更低），請務必開啟這個引數。

• 也可以把primary cells 的值變小些， e.g. "bits=16"
• 或者先執行一次2-bit或4-bit的過濾，把那些非常低覆蓋度的reads給去除掉，從而減少總的獨特kmers數目。
• 我們也可以調整minprob引數，which ignores kmers with a probability of being error-free (based on quality scores) of below X。
• normalization在tables很滿時問題也不大，但是錯誤矯正和histogram generation會變得沒那麼可靠

Shellscripts:

BBNorm有三個指令碼（bbnorm.sh, ecc.sh, and khist.sh），他們都使用KmerNormalize，但配合不同的引數，在錯誤矯正和normalization的時候我們還是可以make kmer frequency histogram的。通過調整引數，這三個指令碼的功能可以變得一樣。

丟棄kmers，精確計數，錯誤矯正--Dumping Kmers, Exact Counts, and Error Correction:

BBNorm不能丟棄具體的kmers，因為BBNorm只儲存了計數值。為了丟棄具體的kmer，可以使用kmercountexact，它可以生成具體kmer的頻度分佈直方圖但，是這個時候不能再分析很大的資料了。由==由於Tadpole使用和kemrcountexact相同的資料結構，在錯誤矯正方面，tadpole優於BBNorm，因此如果我們有足夠的記憶體，最好使用tadpole進行錯誤矯正。==

什麼時候不要用BBNorm--When Not To Use BBNorm:

1. 首先BBNorm不能把低丰度的資料丰度變高，它主要針對資料覆蓋度太高或者分佈抬不均勻（amplified single-cell, RNA-seq, viruses, metagenomes, etc），主要服務於組裝。
2. 在需要對樣品進行定量的時候，用於mapping的資料是沒有進行過矯正的。
3. 同時如果資料的錯誤率太高了，也是不合適的，BBNorm主要用於Illumina和Ion Torrent資料。
4. 如果要進行rare variants calling，也最好不要使用這個工具

臨時檔案管理和管道--Temp Files and Piping:

不可以使用管道
BBNorm needs to read input files multiple times (twice per pass), which means it is unable to accept piped input. In multipass mode, it also needs to generate temp files. The location of temp files can be specified with the "tmpdir" flag; it defaults to the environment variable $TMPDIR, which on Genepool points to local disk when available. Temp files will be cleaned up once BBNorm finishes.

核心數設定--Threads:

可以使用t引數設定核心數
BBNorm is fully multithreaded both when counting kmers and when doing other operations such as normalization. The counting is lock-free, using atomic counters. As a result, it will default to using all available hardware threads; this can be adjusted with the "t" flag.

==Usage Examples==

1. 估計記憶體需求：loglog.sh in=reads.fq
   這個命令可以估計資料集中的獨特kmers，從而估計kmer-counting programs such as BBNorm需要的記憶體量。這個過程是很快的，並且幾乎不耗記憶體。如果loglog報告10億kmers，那麼有3hashes（每個計數值儲存到三個地方）16bits（每個cell的大小）/kmer/8bits（每個位元組有8位）/byte1,000,000,000kmers/0.5（佔用50%的table）load=12 GB的記憶體便可以使得table消耗小於50%

2. 對reads數目進行normalization：
   bbnorm.sh in=reads.fq out=normalized.fq target=100 min=5
   這條命令會將覆蓋度超過100的reads都下調到100，同時蓋度低於5的reads都會被當做是錯誤從而丟棄

3. To error-correct reads:
   ecc.sh in=reads.fq out=corrected.fq
   或者
   bbnorm.sh in=reads.fq out=corrected.fq ecc=t keepall passes=1 bits=16 prefilter
   這個可以進行錯誤矯正但是不丟棄任何reads
   bits=16 prefilter 並不是必須的，但是可以通過儲存kmer更加高效從而使得矯正更加準確

4. 生成kmer分佈直方圖
   khist.sh in=reads.fq khist=khist.txt peaks=peaks.txt
   or equivalently
   bbnorm.sh in=reads.fq khist=khist.txt peaks=peaks.txt passes=1 prefilter minprob=0 minqual=0 mindepth=0
   • 直方圖可以表示出在指定深度時，獨特kmers的數目。比如，a point at "Depth=10, UniqueKmers=248028"指明248028個kmers的測序深度為10。這個直方圖要在對數座標上畫，peak檔案包含直方圖中peak的位置，以及對基因組大小和幾倍體的估計。==這個估計只有在資料是隨機斷裂DNA，倍型數在4以下（1或者2的時候最準確），並且汙染很少時才可靠。如果在kmer直方圖中沒有明顯的peaks，那麼peaks檔案中的結果是不可靠的。==
     bbnorm.sh在這的其他引數 (minprob=0 minqual=0 mindepth=0) 用於避免低丰度的kmers被丟掉

5. Normalization測序資料，並且進行錯誤矯正，在矯正前後都生成kmer直方圖圖
   bbnorm.sh in=reads.fq out=normalized.fq target=100 min=5 prefilter ecc khist=khist_before.txt khistout=khist_after.txt

6. To make a high-pass or low-pass filter:
   bbnorm.sh in=reads.fq out=highpass.fq outt=lowpass.fq passes=1 target=999999999 min=10
   這個命令可以把coverage大於10的輸出到out中，小於10的輸出到outt中

7. 按照depth把資料分到3個區間中To split by depth into 3 bins:
   bbnorm.sh in=reads.fq outlow=low.fq outmid=mid.fq outhigh=high.fq passes=1 lowbindepth=10 highbindepth=80

10x 以下放到 low.fq; 80x 以上放到 high.fq; 其他的放到 mid.fq。 ==特別的, 對於承兌資料，如果一端的depth低於低閾值，另一端depth高於高閾值，那麼它們都去mid資料集==

8. 用額外的序列資訊輔助對kmer的統計:
   bbnorm.sh in=reads.fq out=corrected.fq passes=1 ecc extra=genome.fa,more_reads.fq
   這個指令會利用genome.fa和more_reads.fa中的kmer計數資訊指導對in=資料中reads的矯正。這個操作也可以在其他功能中使用，例如normalization。Extra只會被用於提供kmer丰度資訊，不會再輸出中明顯出現

額外補充一點資訊

1. BBTools has another program functionally related to BBNorm, "kmercountexact.sh". It does NOT use probabilistic data structures, and uses locking rather than atomic counters, and as a result may not scale as well, and will run out of memory on large datasets. However, it is still extremely fast and memory-efficient - using ~15 bytes per kmer (with an optional count-min-sketch prefilter to remove low-count error kmers). It cannot normalize or error-correct, but it can generate the exact kmer count of a dataset as well as the exact kmer frequency histogram (and do rudimentary peak calling for genome size estimation). In practice, when I am interested in kmer frequency histograms, I use KmerCountExact for isolates, and BBNorm for metagenomes.