More Alignment exercises

Exercise #4: Bowtie2 global alignment - Vibrio cholerae RNA-seq

While we have focused on aligning eukaryotic data, the same tools can be used with prokaryotic data. The major differences are less about the underlying data and much more about the external/public databases that store and distribute reference data. If we want to study a prokaryote, the reference data is usually downloaded from a resource like GenBank.  

While the alignment procedure for prokaryotes is broadly analogous, the reference preparation process is somewhat different, and will involve use of a biologically-oriented scripting library called BioPerl.  In this exercise, we will use some RNA-seq data from Vibrio cholerae, published last year on GEO here, and align it to a reference genome.

Overview of Vibrio cholerae alignment workflow with Bowtie2

Alignment of this prokaryotic data follows the workflow below. Here we will concentrate on steps 1 and 2.

1. Prepare the vibCho reference index for bowtie2 from a GenBank record using BioPerl
2. Align reads using bowtie2, producing a SAM file
3. Convert the SAM file to a BAM file (samtools view) 
4. Sort the BAM file by genomic location (samtools sort)
5. Index the BAM file (samtools index)
6. Gather simple alignment statistics (samtools flagstat and samtools idxstat)

Obtaining the GenBank record(s)

First prepare a directory to work in, and change to it:

mkdir -p $SCRATCH/core_ngs/alignment/vibrio/tmp
cd $SCRATCH/core_ngs/alignment/vibrio/tmp

V. cholerae has two chromosomes. We download each separately.

1. Navigate to http://www.ncbi.nlm.nih.gov/nuccore/NC_012582
   • click on the Send to down arrow (top right of page)
   • select Complete Record
   • select Clipboard as Destination
   • click Add to Clipboard
2. Perform these steps in your Terminal window
   
   • cd $SCRATCH/core_ngs/alignment/vibrio/tmp
   • type wget then paste the URL from the clipboard
     • should be http://www.ncbi.nlm.nih.gov/nuccore/NC_012582
3. Repeat steps 1 and 2 fot the 2nd chromosome
   • NCBI URL is http://www.ncbi.nlm.nih.gov/nuccore/NC_012583
   • you should now have 2 files, NC_012582  and NC_012583
4. Combine the 2 files into one using cat
   
   • cat NC_012582  NC_012583 > vibCho.gbk

Converting GenBank records into sequence (FASTA) and annotation (GFF) files

As noted earlier, many microbial genomes are available through repositories like GenBank that use specific file format conventions for storage and distribution of genome sequence and annotations. The GenBank file format is a text file that can be parsed to yield other files that are compatible with the pipelines we have been implementing.

Go ahead and look at some of the contents of a GenBank file with the following commands (execute these one at a time):

cd $WORK/core_ngs/references
less vibCho.O395.gbk # use q to quit less
grep -A 5 ORIGIN vibCho.O395.gbk

As the less command shows, the file begins with a description of the organism and some source information, and the contains annotations for each bacterial gene. The grep command shows that, indeed, there is sequence information here (flagged by the word ORIGIN) that could be exported into a FASTA file. There are a couple ways of extracting the information we want, namely the reference genome and the gene annotation information, but a convenient one (that is available through the module system at TACC) is BioPerl.

We load BioPerl like we have loaded other modules, with the caveat that we must load regular Perl before loading BioPerl:

module load perl
module load bioperl

These commands make several scripts directly available to you. The one we will use is called bp_seqconvert.pl, and it is a BioPerl script used to inter-convert file formats like FASTA, GBK, and others. This script produces two output files:

• a FASTA format file for indexing and alignment
• a GFF file (standing for General Feature Format) contains information about all genes (or, more generally, features) in the genome
  • remember, annotations such as GFFs must always match the reference you are using

To see how to use the script, just execute:

bp_seqconvert.pl

Clearly, there are many file formats that we can use this script to convert.  In our case, we are moving from genbank to fasta, so the commands we would execute to produce and view the FASTA files would look like this:

cd $WORK/core_ngs/references
bp_seqconvert.pl --from genbank --to fasta < vibCho.O395.gbk > vibCho.O395.fa
mv vibCho.O395.fa fasta/
grep ">" fasta/vibCho.O395.fa
less fasta/vibCho.O395.fa

Now we have a reference sequence file that we can use with the bowtie2 reference builder, and ultimately align sequence data against.

Recall from when we viewed the GenBank file that there are genome annotations available as well that we would like to extract into GFF format.  However, the bp_seqconvert.pl script is designed to be used to convert sequence formats, not annotation formats. Fortunately, there is another script called bp_genbank2gff3.pl that can take a GenBank file and produce a GFF3 (the most recent format convention for GFF files) file. To run it and see the output, run these commands:

bp_genbank2gff3.pl --format Genbank vibCho.O395.gbk
mv vibCho.O395.gbk.gff vibCho.O395.gff
less vibCho.O395.gff

After the header lines, each feature in the genome is represented by a line that gives chromosome, start, stop, strand, and other information.  Features are things like "mRNA," "CDS," and "EXON."  As you would expect in a prokaryotic genome it is frequently the case that the gene, mRNA, CDS, and exon annotations are identical, meaning they share coordinate information. You could parse these files further using commands like grep  and awk  to extract, say, all exons from the full file or to remove the header lines that begin with #.

Introducing bowtie2

Go ahead and load the bowtie2 module so we can examine some help pages and options. To do that, you must first load the perl module, and then the a specific version of bowtie2. 

module load perl
module load bowtie/2.2.0

 Now that it's loaded, check out the options. There are a lot of them! In fact for the full range of options and their meaning, Google "Bowtie2 manual" and bring up that page. The Table of Contents is several pages long! Ouch!

This is the key to using bowtie2 - it allows you to control almost everything about its behavior, but that also makes it is much more challenging to use than bwa – and it's easier to screw things up too!

Building the bowtie2 vibCho index

Before the alignment, of course, we've got to build a mirbase index using bowtie2-build (go ahead and check out its options). Unlike for the aligner itself, we only need to worry about a few things here:

• reference_in file is just the FASTA file containing mirbase v20 sequences
• bt2_index_base is the prefix of where we want the files to go

To build the reference index for alignment, we actually only need the FASTA file, since annotations are often not necessary for alignment. (This is not always true - extensively spliced transcriptomes requires splice junction annotations to align RNA-seq data properly, but for now we will only use the FASTA file.)

mkdir -p $WORK/core_ngs/references/bt2/vibCho
mv $WORK/core_ngs/references/vibCho.O395.fa $WORK/core_ngs/references/fasta
cd $WORK/core_ngs/references/bt2/vibCho
ln -s -f ../../fasta/vibCho.O395.fa
ls -la

Now build the index using bowtie2-build:

bowtie2-build vibCho.O395.fa vibCho.O395

This should also go pretty fast. You can see the resulting files using ls like before.

Performing the bowtie2 alignment

Now we will go back to our scratch area to do the alignment, and set up symbolic links to the index in the work area to simplify the alignment command:

cd $SCRATCH/core_ngs/alignment
ln -s -f $WORK/core_ngs/references/bt2/vibCho vibCho

Note that here the data is from standard mRNA sequencing, meaning that the DNA fragments are typically longer than the reads. There is likely to be very little contamination that would require using a local rather than global alignment, or many other pre-processing steps (e.g. adapter trimming). Thus, we will run bowtie2 with default parameters, omitting options other than the input, output, and reference index.

As you can tell from looking at the bowtie2 help message, the general syntax looks like this:

bowtie2 [options]* -x <bt2-idx> {-1 <m1> -2 <m2> | -U <r>} [-S <sam>]

So our command would look like this:

bowtie2 -x vibCho/vibCho.O395 -U fastq/cholera_rnaseq.fastq.gz -S cholera_rnaseq.sam

Create a commands file called bt2_vibCho.cmds with this task definition then generate and submit a batch job for it (time 1 hour, development queue).

launcher_creator.py -n bt2_vibCho -j bt2_vibCho.cmds -t 01:00:00 -A UT-2015-05-18
sbatch bt2_vibCho.slurm; showq -u

When the job is complete you should have a cholera_rnaseq.sam file that you can examine using whatever commands you like.

Exercise #3: Bowtie2 local alignment - Human microRNA-seq

Now we're going to switch over to a different aligner that was originally designed for very short reads and is frequently used for RNA-seq data. Accordingly, we have prepared another test microRNA-seq dataset for you to experiment with (not the same one you used cutadapt on). This data is derived from a human H1 embryonic stem cell (H1-hESC) small RNA dataset generated by the ENCODE Consortium – its about a half million reads.

However, there is a problem!  We don't know (or, well, you don't know) what the adapter structure or sequences were. So, you have a bunch of 36 base pair reads, but many of those reads will include extra sequence that can impede alignment – and we don't know where! We need an aligner that can find subsections of the read that do align, and discard (or "soft-clip") the rest away – an aligner with a local alignment mode. Bowtie2 is just such an aligner.

Overview miRNA alignment workflow with bowtie2

If the adapter structure were known, the normal workflow would be to first remove the adapter sequences with cutadapt. Since we can't do that, we will instead perform a local alignment of the single-end miRNA sequences using bowtie2. This workflow has the following steps:

1. Prepare the mirbase v20 reference index for bowtie2 (one time) using bowtie2-build 
2. Perform local alignment of the R1 reads with bowtie2, producing a SAM file directly
3. Convert the SAM file to a BAM file (samtools view)
4. Sort the BAM file by genomic location (samtools sort)
5. Index the BAM file (samtools index)
6. Gather simple alignment statistics (samtools flagstat and samtools idxstat)

This looks so much simpler than bwa – only one alignment step instead of three! We'll see the price for this "simplicity" in a moment...

As before, we will just do the alignment steps leave samtools for the next section.

Mirbase is a collection of all known microRNAs in all species (and many speculative miRNAs). We will use the human subset of that database as our alignment reference.  This has the advantage of being significantly smaller than the human genome, while likely containing almost all sequences likely to be detected in a miRNA sequencing run.

These are the four reference genomes we will be using today, with some information about them (and here is information about many more genomes):

Building the bowtie2 mirbase index

Before the alignment, of course, we've got to build a mirbase index using bowtie2-build (go ahead and check out its options). Unlike for the aligner itself, we only need to worry about a few things here:

bowtie2-build <reference_in> <bt2_index_base>

• reference_in file is just the FASTA file containing mirbase v20 sequences
• bt2_index_base is the prefix of where we want the files to go

 Following what we did earlier for BWA indexing, namely move our FASTA into place, create the index directory, and establish our symbolic links.

mkdir -p $WORK/core_ngs/references/bt2/mirbase.v20
mv $WORK/core_ngs/references/hairpin_cDNA_hsa.fa $WORK/core_ngs/references/fasta
cd $WORK/core_ngs/references/bt2/mirbase.v20
ln -s -f ../../fasta/hairpin_cDNA_hsa.fa
ls -la 
module load perl
module load bowtie/2.2.0

Now build the mirbase index with bowtie2-build like we did for the V. cholerae index:

bowtie2-build hairpin_cDNA_hsa.fa hairpin_cDNA_hsa.fa

That was very fast!  It's because the mirbase reference genome is so small compared to what programs like this are used to dealing with, which is the human genome (or bigger).  You should see the following files:

hairpin_cDNA_hsa.fa
hairpin_cDNA_hsa.fa.1.bt2
hairpin_cDNA_hsa.fa.2.bt2
hairpin_cDNA_hsa.fa.3.bt2
hairpin_cDNA_hsa.fa.4.bt2
hairpin_cDNA_hsa.fa.rev.1.bt2
hairpin_cDNA_hsa.fa.rev.2.bt2

Performing the bowtie2 local alignment

Now, we're ready to actually try to do the alignment.  Remember, unlike BWA, we actually need to set some options depending on what we're after. Some of the important options for bowtie2 are:

To decide how we want to go about doing our alignment, check out the file we're aligning with less:

cd $SCRATCH/core_ngs/alignment
less fastq/human_mirnaseq.fastq.gz

Lots of reads have long strings of A's, which must be an adapter or protocol artifact.  Even though we see how we might be able to fix it using some tools we've talked about, what if we had no idea what the adapter sequence was, or couldn't use cutadapt or other programs to prepare the reads?

 In that case, we need a local alignment where the seed length smaller than the expected insert size. Here, we are interested in finding any sections of any reads that align well to a microRNA, which are between 16 and 24 bases long, with most 20-22. So an acceptable alignment should have at least 16 matching bases, but could have more.

If we're also interested in detecting miRNA SNPs, we might want to allow a mismatch in the seed. So, a good set of options might look something like this:

-N 1 -L 16 --local

Let's make a link to the mirbase index directory to make our command line simpler:

cd $SCRATCH/core_ngs/alignment
ln -s -f $WORK/core_ngs/references/bt2/mirbase.v20 mb20

Putting this all together we have a command line that looks like this.

bowtie2 --local -N 1 -L 16 -x mb20/hairpin_cDNA_hsa.fa -U fastq/human_mirnaseq.fastq.gz -S human_mirnaseq.sam

Create a commands file called bt2.cmds with this task definition then generate and submit a batch job for it (time 1 hour, development queue).

Use nano to create the bt2.cmds file. Then:

launcher_creator.py -n bt2 -j bt2.cmds -t 01:00:00 -A UT-2015-05-18
sbatch bt2.slurm; showq -u

#copy from Amelia's scratch:
cp /scratch/01786/awh394/core_ngs.test/alignment/human_mirnaseq.sam .

When the job is complete you should have a human_mirnaseq.sam file that you can examine using whatever commands you like. An example alignment looks like this.

TUPAC_0037_FC62EE7AAXX:2:1:2607:1430#0/1  0  hsa-mir-302b  50  22 3S20M13S * 0 0
    TACGTGCTTCCATGTTTTANTAGAAAAAAAAAAAAG  ZZFQV]Z[\IacaWc]RZIBVGSHL_b[XQQcXQcc
    AS:i:37 XN:i:0  XM:i:1  XO:i:0  XG:i:0  NM:i:1  MD:Z:16G3       YT:Z:UU

Notes:

• This is one alignment record, although it has been broken up below for readability.
• This read mapped to the mature microRNA sequence hsa-mir-302b, starting at base 50 in that contig.
• Notice the CIGAR string is 3S20M13S, meaning that 3 bases were soft clipped from one end (3S), and 13 from the other (13S).
  
  • If we did the same alignment using either bowtie2 --end-to-end mode, or using bwa aln as in Exercise #1, very little of this file would have aligned.
• The 20M part of the CIGAR string says there was a block of 20 read bases that mapped to the reference.
  • If we had not lowered the seed parameter of bowtie2 from its default of 22, we would not have found many of the alignments like this one that only matched for 20 bases.

Such is the nature of bowtie2 – it it can be a powerful tool to sift out the alignments you want from a messy dataset with limited information, but doing so requires careful tuning of the parameters, which can take quite a few trials to figure out.

Exercise: About how many records in human_mirnaseq.sam represent aligned reads?

grep -P -v '^@' human_mirnaseq.sam | cut -f 3 | grep -v '*' | wc -l

Use sort and uniq to create a histogram of mapping qualities

The mapping quality score is in field 5 of the human_mirnaseq.sam file. We can do this to pull out only that field:

grep -P -v '^@' human_mirnaseq.sam | cut -f 5 | head

We will use the uniq create a histogram of these values. The first part of the --help for uniq says:

Usage: uniq [OPTION]... [INPUT [OUTPUT]]
Filter adjacent matching lines from INPUT (or standard input),
writing to OUTPUT (or standard output).

With no options, matching lines are merged to the first occurrence.
Mandatory arguments to long options are mandatory for short options too.
  -c, --count           prefix lines by the number of occurrences

To create a histogram, we want to organize all equal mapping quality score lines into an adjacent block, then use uniq -c option to count them. The sort -n command does the sorting into blocks (-n means numerical sort). So putting it all together, and piping the output to a pager just in case, we get:

grep -P -v '^@' human_mirnaseq.sam | cut -f 5 | sort -n | uniq -c | more

Exercise: What is the flaw in this "program"?

Exercise #4: BWA-MEM - Human mRNA-seq

After bowtie2 came out with a local alignment option, it wasn't long before bwa developed its own local alignment algorithm called BWA-MEM (for Maximal Exact Matches), implemented by the bwa mem command. bwa mem has the following advantages:

• It incorporates a lot of the simplicity of using bwa with the complexities of local alignment, enabling straightforward alignment of datasets like the mirbase data we just examined
• It can align different portions of a read to different locations on the genome
  • In a long RNA-seq experiment, reads will (at some frequency) span a splice junction themselves, or a pair of reads in a paired-end library will fall on either side of a splice junction. We want to be able to align reads that do this for many reasons, from accurate transcript quantification to novel fusion transcript discovery.

Thus, our last exercise will be the alignment of a human long RNA-seq dataset composed (by design) almost exclusively of reads that cross splice junctions.

bwa mem was made available when we loaded the bwa module, so take a look at its usage information. The most important parameters, similar to those we've manipulated in the past two sections, are the following:

There are many more parameters to control the scoring scheme and other details, but these are the most essential ones to use to get anything of value at all.

The test file we will be working with is just the R1 file from a paired-end total RNA-seq experiment, meaning it is (for our purposes) single-end. Go ahead and take a look at it, and find out how many reads are in the file.

cd $SCRATCH/core_ngs/alignment
ls fastq
gunzip -c fastq/human_rnaseq.fastq.gz | echo $((`wc -l`/4))

A word about real splice-aware aligners

Using BWA mem for RNA-seq alignment is sort of a "poor man's" RNA-seq alignment method. Real splice-aware aligners like tophat2 or star have more complex algorithms (as shown below) – and take a lot more time!

RNA-seq alignment with bwa aln

Now, try aligning it with bwa aln like we did in Example #1, but first link to the hg19 bwa index directory.  In this case, due to the size of the hg19 index, we are linking to Anna's scratch area INSTEAD of our own work area containing indexes that we built ourselves.

cd $SCRATCH/core_ngs/alignment
ln -s -f /scratch/01063/abattenh/ref_genome/bwa/bwtsw/hg19
ls hg19

You should see a set of files analogous to the yeast files we created earlier, except that their universal prefix is hg19.fa.  

Go ahead and try to do a single-end alignment of the file to the human genome using bwa aln like we did in Exercise #1, saving intermediate files with the prefix human_rnaseq_bwa. Go ahead and just execute on the command line.

bwa aln hg19/hg19.fa fastq/human_rnaseq.fastq.gz > human_rnaseq_bwa.sai
bwa samse hg19/hg19.fa human_rnaseq_bwa.sai fastq/human_rnaseq.fastq.gz > human_rnaseq_bwa.sam

Once this is complete use less to take a look at the contents of the SAM file, using the space bar to leaf through them. You'll notice a lot of alignments look basically like this:

HWI-ST1097:228:C21WMACXX:8:1316:10989:88190     4       *       0       0       *       *       0       0
  AAATTGCTTCCTGTCCTCATCCTTCCTGTCAGCCATCTTCCTTCGTTTGATCTCAGGGAAGTTCAGGTCTTCCAGCCGCTCTTTGCCACTGATCTCCAGCT
  CCCFFFFFHHHHHIJJJJIJJJJIJJJJHJJJJJJJJJJJJJJIIIJJJIGHHIJIJIJIJHBHIJJIIHIEGHIIHGFFDDEEEDDCDDD@CDEDDDCDD

Notice that the contig name (field 3) is just an asterisk ( * ) and the alignment flags value is a 4 (field 2), meaning the read did not align (decimal 4 = hex 0x4 = read did not map).

Essentially, nothing (with a few exceptions) aligned. Why?

RNA-seq alignment with bwa mem

Exercise: use bwa mem to align the same data

Based on the following syntax and the above reference path, use bwa mem to align the same file, saving output files with the prefix human_rnaseq_mem. Go ahead and just execute on the command line.

bwa mem <ref.fa> <reads.fq> > outfile.sam

bwa mem hg19/hg19.fa fastq/human_rnaseq.fastq.gz > human_rnaseq_mem.sam

Check the length of the SAM file you generated with wc -l. Since there is one alignment per line, there must be 586266 alignments (minus no more than 100 header lines), which is more than the number of sequences in the FASTQ file. This is bwa mem can report multiple alignment records for the same read, hopefully on either side of a splice junction. These alignments can still be tied together because they have the same read ID.

# This gives you a view where each read is listed next to the number of entries it has in the SAM file
cut -f 1 human_rnaseq_mem.sam | sort | uniq -c | less

#This gives essentially a histogram of the number of times each read aligned - a plurality of reads aligned twice, which seems reasonable since these are all reads crossing a junction, but plenty aligned more or less
cut -f 1 human_rnaseq_mem.sam | sort | uniq -c | awk '{print $1}' | sort | uniq -c | less	

#This gives a better idea of the alignment rate, which is how many reads aligned at least once to the genome.  Divided by the number of reads in the original file, the real alignment rate is much higher.
cut -f 1 human_rnaseq_mem.sam | sort | uniq | wc -l	

# NOTE: Some of these one-liners are only reasonably fast if the files are relatively small (around a million reads or less). For bigger files, there are better ways to get this information, mostly using samtools.

BWA-MEM vs Tophat

Another approach to aligning long RNA-seq data is to use an aligner that is more explicitly concerned with sensitivity to splice sites, namely a program like Tophat. Tophat uses either bowtie (tophat) or bowtie2 (tophat2) as the actual aligner, but performs the following steps:

• aligns reads to the genome
• reads that do not align to the genome are aligned against a transcriptome, if provided
  • if they align, the transcriptome coordinates are converted back to genomic coordinates, with gaps represented in the CIGAR string, for example as 196N
• reads that do not align to the transcriptome are split into smaller pieces, each of which Tophat attempts to map to the genome

Note that Tophat also reports secondary alignments, but they have a different meaning. Tophat always reports spliced alignments as one alignment records with the N CIGAR string operator indicating the gaps. Secondary alignments for Tophat (marked with the 0x100 BAM flag) represent alternate places in the genome where a  read (spliced or not) may have mapped.

As you can imagine from this series of steps, Tophat is very computationally intensive and takes much longer than bwa mem – very large alignments (hundreds of millions of reads) may not complete in stampede's 48 hour maximum job time!

Exercise #5: Simple SAMtools Utilities

We have used several alignment methods that all generate results in the form of the near-universal SAM/BAM file format.  The SAMtools program is a ubiquitously used set of tools that allow a user to manipulate SAM/BAM files in many different ways, ranging from simple tasks (like SAM/BAM interconversion) to more complex functions (like removal of PCR duplicates).  It is available in the TACC module system in the typical fashion.

In this exercise, we will use five very simple utilities provided by samtools: view, sort, index, flagstat, and idxstats. Each of these is executed in one line for a given SAM/BAM file. In the SAMtools/BEDtools section tomorrow we will explore samtools in more in depth.

For the sake of time and simplicity, here we are only going to run these commands on the yeast paired-end alignment file. The same commands can be run on the other files by changing the names, so feel free to try them on other SAM files. Indeed, it is very common in practice to use bash loops to generate many commands for a large set of alignments and deposit those commands into a batch job cmds file for submission.

To start, we will move to the directory containing our SAM files, among other things, and load up samtools using the module system. After loading it, just run the samtools command to see what the available tools are (and to see what the syntax of an actual command is).

cd $SCRATCH/core_ngs/alignment
ls -la
module load samtools
samtools

You will see the following screen after running samtools with no other options:

Program: samtools (Tools for alignments in the SAM format)
Version: 1.2 (using htslib 1.2.1)
Usage:   samtools <command> [options]
Commands:
  -- indexing
         faidx       index/extract FASTA
         index       index alignment
  -- editing
         calmd       recalculate MD/NM tags and '=' bases
         fixmate     fix mate information
         reheader    replace BAM header
         rmdup       remove PCR duplicates
         targetcut   cut fosmid regions (for fosmid pool only)
  -- file operations
         bamshuf     shuffle and group alignments by name
         cat         concatenate BAMs
         merge       merge sorted alignments
         mpileup     multi-way pileup
         sort        sort alignment file
         split       splits a file by read group
         bam2fq      converts a BAM to a FASTQ
  -- stats
         bedcov      read depth per BED region
         depth       compute the depth
         flagstat    simple stats
         idxstats    BAM index stats
         phase       phase heterozygotes
         stats       generate stats (former bamcheck)
  -- viewing
         flags       explain BAM flags
         tview       text alignment viewer
         view        SAM<->BAM<->CRAM conversion

Samtools view

The utility samtools view provides a way of converting SAM (text format) files to BAM (binary, compressed) files directly. It also provides many, many other functions which we will discuss lster. To get a preview, execute samtools view without any other arguments. You should see:

Usage:   samtools view [options] <in.bam>|<in.sam>|<in.cram> [region ...]
Options: -b       output BAM
         -C       output CRAM (requires -T)
         -1       use fast BAM compression (implies -b)
         -u       uncompressed BAM output (implies -b)
         -h       include header in SAM output
         -H       print SAM header only (no alignments)
         -c       print only the count of matching records
         -o FILE  output file name [stdout]
         -U FILE  output reads not selected by filters to FILE [null]
         -t FILE  FILE listing reference names and lengths (see long help) [null]
         -T FILE  reference sequence FASTA FILE [null]
         -L FILE  only include reads overlapping this BED FILE [null]
         -r STR   only include reads in read group STR [null]
         -R FILE  only include reads with read group listed in FILE [null]
         -q INT   only include reads with mapping quality >= INT [0]
         -l STR   only include reads in library STR [null]
         -m INT   only include reads with number of CIGAR operations
                  consuming query sequence >= INT [0]
         -f INT   only include reads with all bits set in INT set in FLAG [0]
         -F INT   only include reads with none of the bits set in INT
                  set in FLAG [0]
         -x STR   read tag to strip (repeatable) [null]
         -B       collapse the backward CIGAR operation
         -s FLOAT integer part sets seed of random number generator [0];
                  rest sets fraction of templates to subsample [no subsampling]
         -@ INT   number of BAM compression threads [0]
         -?       print long help, including note about region specification
         -S       ignored (input format is auto-detected)

That is a lot to process! For now, we just want to read in a SAM file and output a BAM file. The input format is auto-detected, so we don't need to say that we're inputing a SAM instead of a BAM. We just need to tell the tool to output the file in BAM format, and provide the name of the destination BAM file. This command is as follows:

samtools view -b yeast_pairedend.sam -o yeast_pairedend.bam

• the -b option tells the tool to output BAM format
• the -o option specifies the name of the output BAM file that will be created

How do you look at the BAM file contents now? That's simple. Just use samtools view. without the -b option. Remember to pipe output to a pager!

samtools view yeast_pairedend.bam | more

Samtools sort

Look at the SAM file briefly using less. You will notice, if you scroll down, that the alignments are in no particular order, with chromosomes and start positions all mixed up. This makes searching through the file very inefficient. samtools sort is a piece of samtools that provides the ability to re-order entries in the SAM file either by coordinate position or by read name.

If you execute samtools sort without any options, you see its help page:

Usage: samtools sort [options...] [in.bam]
Options:
  -l INT     Set compression level, from 0 (uncompressed) to 9 (best)
  -m INT     Set maximum memory per thread; suffix K/M/G recognized [768M]
  -n         Sort by read name
  -o FILE    Write final output to FILE rather than standard output
  -O FORMAT  Write output as FORMAT ('sam'/'bam'/'cram')   (either -O or
  -T PREFIX  Write temporary files to PREFIX.nnnn.bam       -T is required)
  -@ INT     Set number of sorting and compression threads [1]
Legacy usage: samtools sort [options...] <in.bam> <out.prefix>
Options:
  -f         Use <out.prefix> as full final filename rather than prefix
  -o         Write final output to stdout rather than <out.prefix>.bam
  -l,m,n,@   Similar to corresponding options above

In most cases you will be sorting a BAM file by position rather than by name. You can use either -o or reidrection with > to control the output.

To sort the paired-end yeast BAM file by coordinate, and get a BAM file named yeast_pairedend.sort.bam as output, execute the following command:

samtools sort -O bam -T yeast_pairedend.sort yeast_pairedend.bam > yeast_pairedend.sort.bam

• The -O options says the output format should be BAM
• The -T options gives a prefix for temporary files produced during sorting
• By default sort writes its output to standard output, so we use > to redirect to a file named yeast_pairedend.sort.bam

Samtools index

Many tools (like the UCSC Genome Browser) only need to use sub-sections of the BAM file at a given point in time. For example, if you are viewing alignments that are within a particular gene alignments on other chromosomes generally do not need to be loaded. In order to speed up access, BAM files are indexed, producing BAI files which allow other programs to navigate directly to the alignments of interest. This is especially important when you have many alignments.

The utility samtools index creates an index that has the exact name as the input BAM file, with suffix .bai appended. The help page, if you execute samtools index with no arguments, is as follows:

Usage: samtools index [-bc] [-m INT] <in.bam> [out.index]
Options:
  -b       Generate BAI-format index for BAM files [default]
  -c       Generate CSI-format index for BAM files
  -m INT   Set minimum interval size for CSI indices to 2^INT [14]

Here, the syntax is way, way easier. We want a BAI-format index which is the default. (CSI-format is used with extremely long contigs, which we aren't considering here - the most common use case are highly polyploid plant genomes).

So all we have to type is:

samtools index yeast_pairedend.sort.bam

This will produce a file named yeast_pairedend.bam.bai.

Most of the time when an index is required, it will be automatically located as long as it is in the same directory as its BAM file and shares the same name up until the .bai extension.

Samtools idxstats

Now that we have a sorted, indexed BAM file, we might like to get some simple statistics about the alignment run. For example, we might like to know how many reads aligned to each chromosome/contig. The samtools idxstats is a very simple tool that provides this information. If you type the command without any arguments, you will see that it could not be simpler - just type the following command:

samtools idxstats yeast_pairedend.sort.bam

The output is a text file with four tab-delimited columns with the following meanings:

1. chromosome name
2. chromosome length
3. number of mapped reads
4. number of unmapped reads

The reason that the "unmapped reads" field for the named chromosomes is not zero is that, if one half of a pair of reads aligns while the other half does not, the unmapped read is still assigned to the chromosome its mate mapped to, but is flagged as unmapped.

Samtools flagstat

Finally, we might like to obtain some other statistics, such as the percent of all reads that aligned to the genome. The samtools flagstat tool provides very simple analysis of the SAM flag fields, which includes information like whether reads are properly paired, aligned or not, and a few other things. Its syntax is identical to that of samtools idxstats:

samtools flagstat yeast_pairedend.sort.bam

You should see something like this:

1184360 + 0 in total (QC-passed reads + QC-failed reads)
0 + 0 secondary
0 + 0 supplementary
0 + 0 duplicates
547664 + 0 mapped (46.24%:-nan%)
1184360 + 0 paired in sequencing
592180 + 0 read1
592180 + 0 read2
473114 + 0 properly paired (39.95%:-nan%)
482360 + 0 with itself and mate mapped
65304 + 0 singletons (5.51%:-nan%)
534 + 0 with mate mapped to a different chr
227 + 0 with mate mapped to a different chr (mapQ>=5)

Ignore the "+ 0" addition to each line - that is a carry-over convention for counting QA-failed reads that is no longer necessary.

The most important statistic is the mapping rate, but this readout allows you to verify that some common expectations (e.g. that about the same number of R1 and R2 reads aligned, and that most mapped reads are proper pairs) are met.

Exercise #6: Yeast BWA PE alignment with Anna's script

Now that you've done everything the hard way, let's see how to do run an alignment pipeline using Anna's script.

First the setup:

mkdir -p $SCRATCH/core_ngs/align2/fastq
cd $SCRATCH/core_ngs/align2/fastq
cp /corral-repl/utexas/BioITeam/core_ngs_tools/alignment/*fastq.gz .

Before executing the script you need to have one environment variable set. We'll do it at the command line here, but you could put it in your .bashrc file.

export path_code=/work/01063/abattenh/code

Now change into the directory and call the script with no arguments to see usage

cd $SCRATCH/core_ngs/align2
$path_code/script/align/align_bwa_illumina.sh

There are lots of bells and whistles in the arguments, but the most important are the first few:

1. FASTQ file – full or relative path to the FASTQ file (just the R1 fastq if paired end). Can be compressed (.gz)
2. output prefix – prefix for all the output files produced by the script. Should relate back to what the data is.
3. assembly – genome assembly to use.
   • there are pre-built indexes for some common eukaryotes (hg19, hg18, mm10, mm9, danRer7, sacCer3) that you can use
   • or provide a full path for a bwa reference index you have built somewhere
4. paired flag – 0 means single end (the default); 1 means paired end
5. hard trim length – if you want the FASTQ hard trimmed down to a specific length, supply that number here
   

Now run the pipeline. By piping the output to tee <filename> we can see the script's progress at the terminal, and it also is written to <filename>.

$path_code/script/align/align_bwa_illumina.sh ./fastq/Sample_Yeast_L005_R1.cat.fastq.gz yeast_chip sacCer3 1 2>&1 | tee aln.yeast_chip.log

Output files

This alignment pipeline script performs the following steps:

• Hard trims FASTQ, if optionally specified (fastx_trimmer)
  
• Aligns the R1 FASTQ (bwa aln)
  
• Aligns the R2 FASTQ, if paired end alignment specified (bwa aln)
• Reports the alignments as SAM (bwa samse for single end, or bwa sampe for paired end)
  
• Converts SAM to BAM (samtools view)
• Sorts the BAM (samtools sort)
• Marks duplicates (Picard MarkDuplicates)
• Indexes the sorted, duplicate-marked BAM (samtools index)
• Gathers statistics (samtools idxstats, samtools flagstat, plus a custom statistics script of Anna's)
• Removes intermediate files
  

There are a number of output files, with the most important being those desribed below.

1. aln.<prefix>.log – Log file of the entire alignment process.
   • check the tail of this file to make sure the alignment was successful
2. <prefix>.sort.dup.bam – Sorted, duplicate-marked alignment file.
3. <prefix>.sort.dup.bam.bai – Index for the sorted, duplicate-marked alignment file
4. <prefix>.samstats.txt – Summary alignment statistics from Anna's stats script
   

Verifying alignment success

The alignment log will have a  "I ran successfully" message at the end if all went well, and if there was an error, the important information should also be at the end of the log file. So you can use tail to check the status of an alignment; for example:

tail aln.yeast_chip.log

This will show something like:

..samstats file 'yeast_chip.samstats.txt' exists Thu May 28 16:36:01 CDT 2015
..samstats file file 'yeast_chip.samstats.txt' size ok Thu May 28 16:36:01 CDT 2015
---------------------------------------------------------
Cleaning up files...
---------------------------------------------------------
ckRes 0 cleanup
---------------------------------------------------------
All bwa alignment tasks completed successfully!
Thu May 28 16:36:01 CDT 2015
---------------------------------------------------------

Notice that success message: "All bwa alignment tasks completed successfully!". It should only appear once in any successful alignment log.

When multiple alignment commands are run in parallel it is important to check them all, and you can use grep looking for part of the unique success message to do this.

For example, suppose I have run 6 alignments and have these 6 log files:

aln.delswr1_htz1_tap1t0.log   aln.delswr1_htz1_tap1t30.log  aln.wt_htz1_tap1t15.log
aln.delswr1_htz1_tap1t15.log  aln.wt_htz1_tap1t0.log        aln.wt_htz1_tap1t30.log

I can check that all 6 completed with this command:

grep 'completed successfully' aln.*.log | wc -l

If this command returns 6, I'm done. But what if it doesn't? If you grep -v (lines that don't contain the pattern), you'll get every line in every log file except the success message line, which is not what you want at all.

You could tail the log files one by one to see which one(s) don't have the message, but you can also use a special grep option to do this work:

grep -L 'completed successfully' aln.*.log

The -L option tells grep to only print the filenames that don't contain the pattern. Perfect!

Checking alignment statistics

The <prefix>.samstats.txt statistics file produced by the alignment pipeline has a lot of good information in one place. If you use cat or more to view it you'll see this:

-----------------------------------------------
             Aligner:       bwa
     Total sequences:   1184360
        Total mapped:    547664 (46.2 %)
      Total unmapped:    636696 (53.8 %)
             Primary:    547664 (100.0 %)
           Secondary:
          Duplicates:    324280 (59.2 %)
          Fwd strand:    272898 (49.8 %)
          Rev strand:    274766 (50.2 %)
           Multi hit:     18688 (3.4 %)
           Soft clip:    222451 (40.6 %)
           All match:    319429 (58.3 %)
              Indels:      6697 (1.2 %)
             Spliced:
-----------------------------------------------
       Total PE seqs:   1184360
      PE seqs mapped:    547664 (46.2 %)
        Num PE pairs:    592180
   F5 1st end mapped:    300477 (50.7 %)
   F3 2nd end mapped:    247187 (41.7 %)
     PE pairs mapped:    241180 (40.7 %)
     PE proper pairs:    236557 (39.9 %)
-----------------------------------------------
  Insert size stats for: yeast_chip
        Number of pairs: 236557 (proper)
 Number of insert sizes: 212
        Mean [-/+ 1 SD]: 215 [153 277]  (sd 62)
         Mode [Fivenum]: 223  [105 210 220 229 321]
-----------------------------------------------

Since this was a paired end alignment there is paired-end specific information reported, including insert size statistics: mean/standard deviation, mode (most common insert size value) and fivenum (min, q1, median, q3 max insert sizes).

A quick way to check alignment stats if you have run multiple alignments is again to use grep. For example, for the 6 alignment files shown earlier, running this:

grep 'Total map' *samstats.txt

will produce output like this:

delswr1_htz1_tap1t0.samstats.txt:        Total mapped:  32761761 (86.8 %)
delswr1_htz1_tap1t15.samstats.txt:        Total mapped:  33699464 (89.2 %)
delswr1_htz1_tap1t30.samstats.txt:        Total mapped:  28441655 (87.6 %)
wt_htz1_tap1t0.samstats.txt:        Total mapped:  28454847 (89.5 %)
wt_htz1_tap1t15.samstats.txt:        Total mapped:  33245627 (90.9 %)
wt_htz1_tap1t30.samstats.txt:        Total mapped:  32567026 (90.7 %)

 TACC batch system considerations

The great thing about pipeline scripts like this is that you can perform alignments on many datasets in parallel at TACC.

Anna's alignment pipeline scripts are written to take advantage of having multiple cores on TACC nodes, and are thus designed to run with at most two pipeline commands per TACC node.

Assuming you have your alignment commands in a file called aln.cmds, here's how to create and submit a batch job for the commands.

launcher_creator.py -n aln -j aln.cmds -t 12:00:00 -q normal -w 2
sbatch aln.slurm
showq -u

Note the maximum run time specified here is 12 hours (-t 12:00:00). This is a reasonable value for a higher eukaryote with 20-40 M reads, and is way more than a yeast alignment would need (~ 4 hours). For very deeply sequenced eukaryotes (e.g. human genome re-sequencing with hundresd of millions of reads), you may want to specify the maximum job time of 48 hours.

Exercise: What would alignment commands look like if you were putting it in a batch system .cmds file?

$path_code/script/align/align_bwa_illumina.sh ./fastq/Sample_Yeast_L005_R1.cat.fastq.gz yeast1 sacCer3 1 2>&1 > aln.yeast1.log
$path_code/script/align/align_bwa_illumina.sh ./fastq/Sample_ABCDE_L005_R1.cat.fastq.gz yeast2 sacCer3 1 2>&1 > aln.yeast2.log