BioInfo/BS-Seq/bwa-meth/README.md

   1 bwa-meth
   2 ========
   3
   4 Fast and accurante alignment of BS-Seq reads.
   5
   6 ## NOTE!!!
   7
   8 As of 2016-08-18, bwa-meth now outputs sam to stdout. It is up to the user to
   9 convert to bam. This means that the --prefix and --calmd flags are gone.
  10
  11 ## Update 2016
  12
  13 `bwa-meth` is still among (if not *the*) best aligners for BS-Seq.
  14 While it is fairly stable, I will continue to support the alignment
  15 part of `bwa-meth`--fixing any bugs or updating as needed.
  16
  17 There are now several (likely better) alternatives for tabulation
  18 and SNP calling than provided here so I will not develop those further.
  19
  20 For tabulation, bias, and plotting, use [PileOMeth](https://github.com/dpryan79/PileOMeth)
  21
  22 For SNP calling (a more modern BisSNP), use [biscuit](https://github.com/zwdzwd/biscuit)
  23
  24
  25 ## Intro
  26
  27 This works for single-end reads and for **paired-end reads from the
  28 directional protocol** (most common).
  29
  30 Uses the method employed by methylcoder and Bismark of *in silico*
  31 conversion of all C's to T's in both reference and reads.
  32
  33 Recovers the original read (needed to tabulate methylation) by attaching it
  34 as a comment which **bwa** appends as a tag to the read.
  35
  36 Performs favorably to existing aligners gauged by number of on and off-target reads for a capture method that targets CpG-rich region. Some off-target regions may be enriched, but all aligners are be subject to the same assumptions.
  37 See manuscript: http://arxiv.org/abs/1401.1129 for details.
  38 Optimal alignment is the upper-left corner. Curves are drawn by varying the
  39 mapping quality cutoff for alingers that use it.
  40
  41 This image is on real reads and represents an attempt to find good parameters
  42 for all aligners tested.
  43
  44 ![Untrimmed reads comparison](https://gist.githubusercontent.com/brentp/bf7d3c3d3f23cc319ed8/raw/d5f1ebcc53b924a05a5980159bfcb97494ec34f2/real.gif)
  45
  46 Note that *bwa-meth* and *Last* perform well without trimming.
  47
  48 run.sh scripts for each method are here: https://github.com/brentp/bwa-meth/tree/master/compare
  49 I have done my best to have each method perform optimally, but no doubt there
  50 could be improvements.
  51
  52 QuickStart
  53 ==========
  54
  55 Without installation, you can use as `python bwameth.py` with install, the
  56 command is `bwameth.py`.
  57
  58 The commands:
  59
  60     bwameth.py index $REF
  61     bwameth.py --reference $REF some_R1.fastq.gz some_R2.fastq.gz > some.output.sam
  62
  63 will create `some.output.bam` and `some.output.bam.bai`.
  64 To align single end-reads, specify only 1 file.
  65
  66 See the **full example** at: https://github.com/brentp/bwa-meth/tree/master/example/
  67
  68 Installation
  69 ============
  70
  71 The following snippet should work for most systems that have samtools and bwa
  72 installed and the ability to install python packages. (Or, you can send this
  73 to your sys-admin). See the dependencies section below for further instructions:
  74
  75 ```Shell
  76
  77     # these 4 lines are only needed if you don't have toolshed installed
  78     wget https://pypi.python.org/packages/source/t/toolshed/toolshed-0.4.0.tar.gz
  79     tar xzvf toolshed-0.4.0.tar.gz
  80     cd toolshed-0.4.0
  81     sudo python setup.py install
  82
  83     wget https://github.com/brentp/bwa-meth/archive/v0.10.tar.gz
  84     tar xzvf v0.10.tar.gz
  85     cd bwa-meth-0.10/
  86     sudo python setup.py install
  87
  88 ```
  89
  90 After this, you should be able to run: `bwameth.py` and see the help.
  91
  92 Dependencies
  93 ------------
  94
  95 `bwa-meth` depends on
  96
  97  + python 2.7+ (including python3)
  98    - `toolshed` library. can be installed with:
  99       * `easy_install toolshed` or
 100       * `pip install toolshed`
 101
 102    - if you don't have root or sudo priviledges, you can run
 103      `python setup.py install --user` from this directory and the bwameth.py
 104      executable will be at: ~/.local/bin/bwameth.py
 105
 106    - if you do have root or sudo run: `[sudo] python setup.py install` from
 107      this directory
 108
 109    - users unaccustomed to installing their own python packages should
 110      download anaconda: https://store.continuum.io/cshop/anaconda/ and
 111      then install the toolshed module with pip as described above.
 112
 113  + samtools command on the `$PATH` (https://github.com/samtools/samtools)
 114
 115  + bwa mem from: https://github.com/lh3/bwa
 116
 117
 118 usage
 119 =====
 120
 121 Index
 122 -----
 123
 124 One time only, you need to index a reference sequence.
 125
 126     bwameth.py index $REFERENCE
 127
 128 If your reference is `some.fasta`, this will create `some.c2t.fasta`
 129 and all of the bwa indexes associated with it.
 130
 131 Align
 132 -----
 133
 134     bwameth.py --threads 16 \
 135          --reference $REFERENCE \
 136          $FQ1 $FQ2 > some.sam
 137
 138 The output will pass will have the reads in the correct location (flipped from G => A reference).
 139
 140 Handles clipped alignments and indels correctly. Fastqs can be gzipped
 141 or not.
 142
 143 The command above will be sent to BWA to do the work as something like:
 144
 145     bwa mem -L 25 -pCM -t 15  $REFERENCE.c2t.fa \
 146             '<python bwameth.py c2t $FQ1 $FQ2'
 147
 148 So the converted reads are streamed directly to bwa and **never written
 149 to disk**. The output from that is modified by `bwa-meth` and streamed
 150 straight to a bam file.