2020 Alignment workflow
Overview
After raw sequence files are generated (in FASTQ format), quality-checked, and pre-processed in some way, the next step in many NGS pipelines is mapping to a reference genome.
For individual sequences it is common to use a tool like BLAST to identify genes or species of origin. However a normal NGS dataset will have tens to hundreds of millions of sequences, which BLAST and similar tools are not designed to handle. Thus a large set of computational tools have been developed to quickly align each read to its best location (if any) in a reference.
Even though many mapping tools exist, a few individual programs have a dominant "market share" of the NGS world. In this section, we will primarily focus on two of the most versatile general-purpose ones: BWA and Bowtie2 (the latter being part of the Tuxedo suite which includes the transcriptome-aware RNA-seq aligner Tophat2 as well as other downstream quantifiaction tools).
Stage the alignment data
First connect to login5.ls5.tacc.utexas.edu. This should be second nature by now
Then stage the sample datasets and references we will use.
mkdir -p $SCRATCH/core_ngs/alignment/fastq mkdir -p $SCRATCH/core_ngs/references/fasta cp $CORENGS/alignment/*fastq.gz $SCRATCH/core_ngs/alignment/fastq/ cp $CORENGS/references/*.fa $SCRATCH/core_ngs/references/fasta/
These are descriptions of the FASTQ files we copied:
File Name | Description | Sample |
---|---|---|
Sample_Yeast_L005_R1.cat.fastq.gz | Paired-end Illumina, First of pair, FASTQ | Yeast ChIP-seq |
Sample_Yeast_L005_R2.cat.fastq.gz | Paired-end Illumina, Second of pair, FASTQ | Yeast ChIP-seq |
human_rnaseq.fastq.gz | Paired-end Illumina, First of pair only, FASTQ | Human RNA-seq |
human_mirnaseq.fastq.gz | Single-end Illumina, FASTQ | Human microRNA-seq |
cholera_rnaseq.fastq.gz | Single-end Illumina, FASTQ | V. cholerae RNA-seq |
Reference Genomes
Before we get to alignment, we need a reference to align to. This is usually an organism's genome, but can also be any set of names sequences, such as a transcriptome or other set of genes.
Here are the four reference genomes we will be using today, with some information about them. These are not necessarily the most recent versions of these references (e.g. the newest human reference genome is hg38 and the most recent miRBase annotation is v21. (See here for information about many more genomes.)
Reference | Species | Base Length | Contig Number | Source | Download |
---|---|---|---|---|---|
hg19 | Human | 3.1 Gbp | 25 (really 93) | UCSC | UCSC GoldenPath |
sacCer3 | Yeast | 12.2 Mbp | 17 | UCSC | UCSC GoldenPath |
mirbase v20 | Human subset | 160 Kbp | 1908 | miRBase | miRBase Downloads |
vibCho (O395) | Vibrio cholerae | ~4 Mbp | 2 | GenBank | GenBank Downloads |
Searching genomes is computationally hard work and takes a long time if done on linear genomic sequence. So aligners require that references first be indexed to accelerate lookup. The aligners we are using each require a different index, but use the same method (the Burrows-Wheeler Transform) to get the job done.
Building a reference index involves taking a FASTA file as input, with each contig (contiguous string of bases, e.g. a chromosome) as a separate FASTA entry, and producing an aligner-specific set of files as output. Those output index files are then used to perform the sequence alignment, and alignments are reported using coordinates referencing names and offset positions based on the original FASTA file contig entries.
We can quickly index the references for the yeast genome, the human miRNAs, and the V. cholerae genome, because they are all small, so we'll build each index from the appropriate FASTA files right before we use them.
hg19 is way too big for us to index here so we will use an existing set of BWA hg19 index files located at:
/work/projects/BioITeam/ref_genome/bwa/bwtsw/hg19
The BioITeam maintains a set of reference indexes for many common organisms and aligners. They can be found in aligner-specific sub-directories of the /work/projects/BioITeam/ref_genome area. E.g.:
/work/projects/BioITeam/ref_genome/ bowtie2/ bwa/ hisat2/ kallisto/ star/ tophat/
Exploring FASTA with grep
It is often useful to know what chromosomes/contigs are in a FASTA file before you start an alignment so that you're familiar with the contig naming convention – and to verify that it's the one you expect. For example, chromosome 1 is specified differently in different references and organisms: chr1 (USCS human), chrI (UCSC yeast), or just 1 (Ensembl human GRCh37).
A FASTA file consists of a number of contig name entries, each one starting with a right carat ( > ) character, followed by many lines of base characters. E.g.:
>chrI CCACACCACACCCACACACCCACACACCACACCACACACCACACCACACC CACACACACACATCCTAACACTACCCTAACACAGCCCTAATCTAACCCTG GCCAACCTGTCTCTCAACTTACCCTCCATTACCCTGCCTCCACTCGTTAC CCTGTCCCATTCAACCATACCACTCCGAACCACCATCCATCCCTCTACTT
How do we dig out just the lines that have the contig names and ignore all the sequences? Well, the contig name lines all follow the pattern above, and since the > character is not a valid base, it will never appear on a sequence line.
We've discovered a pattern (also known as a regular expression) to use in searching, and the command line tool that does regular expression matching is grep (general regular expression parser). Read more about grep here: Advanced commands: grep.
Regular expressions are so powerful that nearly every modern computer language includes a "regex" module of some sort. There are many online tutorials for regular expressions, and several slightly different "flavors" of them. But the most common is the Perl style (http://perldoc.perl.org/perlretut.html), which was one of the fist and still the most powerful (there's a reason Perl was used extensively when assembling the human genome). We're only going to use the most simple of regular expressions here, but learning more about them will pay handsome dividends for you in the future.
Here's how to execute grep to list contig names in a FASTA file.
grep -P '^>' sacCer3.fa | more
Notes:
- The -P option tells grep to Perl-style regular expression patterns.
- This makes including special characters like Tab ( \t ), Carriage Return ( \r ) or Linefeed ( \n ) much easier that the default POSIX paterns.
- While it is not required here, it generally doesn't hurt to include this option.
'^>' is the regular expression describing the pattern we're looking for (described below)
- sacCer3.fa is the file to search.
- lines with text that match our pattern will be written to standard output
- non matching lines will be omitted
- We pipe to more just in case there are a lot of contig names.
Now down to the nuts and bolts of the pattern: '^>'
First, the single quotes around the pattern – this tells the bash shell to pass the exact string contents to grep.
As part of its friendly command line parsing and evaluation, the shell will often look for special characters on the command line that mean something to it (for example, the $ in front of an environment variable name, like in $SCRATCH). Well, regular expressions treat the $ specially too – but in a completely different way! Those single quotes tell the shell "don't look inside here for special characters – treat this as a literal string and pass it to the program". The shell will obey, will strip the single quotes off the string, and will pass the actual pattern, ^>, to the grep program. (Note that the shell does look inside double quotes ( " ) for certain special signals, such as looking for environment variable names to evaluate. Read more about Quoting in the shell.)
So what does ^> mean to grep? We know that contig name lines always start with a > character, so > is a literal for grep to use in its pattern match.
We might be able to get away with just using this literal alone as our regex, specifying '>' as the command line argument. But for grep, the more specific the pattern, the better. So we constrain where the > can appear on the line. The special carat ( ^ ) character represents "beginning of line". So ^> means "beginning of a line followed by a > character".
Exercise: How many contigs are there in the sacCer3 reference?
Aligner overview
There are many aligners available, but we will concentrate on two of the most popular general-purpose ones: bwa and bowtie2. The table below outlines the available protocols for them.
alignment type | aligner options | pro's | con's |
---|---|---|---|
global with bwa | SE:
PE:
|
|
|
global with bowtie2 | bowtie2 --global |
|
|
local with bwa | bwa mem |
|
|
local with bowtie2 | bowtie2 --local |
|
|
Exercise #1: BWA global alignment – Yeast ChIP-seq
Overview ChIP-seq alignment workflow with BWA
We will perform a global alignment of the paired-end Yeast ChIP-seq sequences using bwa. This workflow has the following steps:
- Trim the FASTQ sequences down to 50 with fastx_clipper
- this removes most of any 5' adapter contamination without the fuss of specific adapter trimming w/cutadapt
- Prepare the sacCer3 reference index for bwa using bwa index
- this is done once, and re-used for later alignments
- Perform a global bwa alignment on the R1 reads (bwa aln) producing a BWA-specific binary .sai intermediate file
- Perform a global bwa alignment on the R2 reads (bwa aln) producing a BWA-specific binary .sai intermediate file
- Perform pairing of the separately aligned reads and report the alignments in SAM format using bwa sampe
- Convert the SAM file to a BAM file (samtools view)
- Sort the BAM file by genomic location (samtools sort)
- Index the BAM file (samtools index)
- Gather simple alignment statistics (samtools flagstat and samtools idxstat)
We're going to skip the trimming step for now and see how it goes. We'll perform steps 2 - 5 now and leave samtools for a later exercise since steps 6 - 10 are common to nearly all post-alignment workflows.
Introducing BWA
Like other tools you've worked with so far, you first need to load bwa. Do that now, and then enter bwa with no arguments to view the top-level help page (many NGS tools will provide some help when called with no arguments). Note that bwa is available both from the standard TACC module system and as BioContainers. module.
module load bwa bwa
Program: bwa (alignment via Burrows-Wheeler transformation) Version: 0.7.16a-r1181 Contact: Heng Li <lh3@sanger.ac.uk> Usage: bwa <command> [options] Command: index index sequences in the FASTA format mem BWA-MEM algorithm fastmap identify super-maximal exact matches pemerge merge overlapping paired ends (EXPERIMENTAL) aln gapped/ungapped alignment samse generate alignment (single ended) sampe generate alignment (paired ended) bwasw BWA-SW for long queries shm manage indices in shared memory fa2pac convert FASTA to PAC format pac2bwt generate BWT from PAC pac2bwtgen alternative algorithm for generating BWT bwtupdate update .bwt to the new format bwt2sa generate SA from BWT and Occ Note: To use BWA, you need to first index the genome with `bwa index'. There are three alignment algorithms in BWA: `mem', `bwasw', and `aln/samse/sampe'. If you are not sure which to use, try `bwa mem' first. Please `man ./bwa.1' for the manual.
As you can see, bwa include many sub-commands that perform the tasks we are interested in.
Building the BWA sacCer3 index
We will index the genome with the bwa index command. Type bwa index with no arguments to see usage for this sub-command.
Usage: bwa index [options] <in.fasta> Options: -a STR BWT construction algorithm: bwtsw, is or rb2 [auto] -p STR prefix of the index [same as fasta name] -b INT block size for the bwtsw algorithm (effective with -a bwtsw) [10000000] -6 index files named as <in.fasta>.64.* instead of <in.fasta>.* Warning: `-a bwtsw' does not work for short genomes, while `-a is' and `-a div' do not work not for long genomes.
Based on the usage description, we only need to specify two things:
- The name of the FASTA file
- Whether to use the bwtsw or is algorithm for indexing
Since sacCer3 is relative large (~12 Mbp) we will specify bwtsw as the indexing option (as indicated by the "Warning" message), and the name of the FASTA file is sacCer3.fa.
The output of this command is a group of files that are all required together as the index. So, within our references directory, we will create another directory called references/bwa/sacCer3 and build the index there. To remind ourselves which FASTA was used to build the index, we create a symbolic link to our references/fasta/sacCer3.fa file (note the use of the ../.. relative path syntax).
mkdir -p $SCRATCH/core_ngs/references/bwa/sacCer3 cd $SCRATCH/core_ngs/references/bwa/sacCer3 ln -s ../../fasta/sacCer3.fa ls -l
Now execute the bwa index command.
bwa index -a bwtsw sacCer3.fa
Since the yeast genome is not large when compared to human, this should not take long to execute (otherwise we would do it as a batch job). When it is complete you should see a set of index files like this:
sacCer3.fa sacCer3.fa.amb sacCer3.fa.ann sacCer3.fa.bwt sacCer3.fa.pac sacCer3.fa.sa
Performing the bwa alignment
Now, we're ready to execute the actual alignment, with the goal of initially producing a SAM file from the input FASTQ files and reference. First prepare a directory for this exercise and link the sacCer3 reference directories there (this will make our commands more readable).
mkdir -p $SCRATCH/core_ngs/alignment/yeast_bwa cd $SCRATCH/core_ngs/alignment/yeast_bwa ln -s -f ../fastq ln -s -f ../../references/bwa/sacCer3
As our workflow indicated, we first use bwa aln on the R1 and R2 FASTQs, producing a BWA-specific .sai intermediate binary files.
What does bwa aln needs in the way of arguments?
There are lots of options, but here is a summary of the most important ones.
Option | Effect |
---|---|
-l | Specifies the length of the seed (default = 32) |
-k | Specifies the number of mismatches allowable in the seed of each alignment (default = 2) |
-n | Specifies the number of mismatches (or fraction of bases in a given alignment that can be mismatches) in the entire alignment (including the seed) (default = 0.04) |
-t | Specifies the number of threads |
Other options control the details of how much a mismatch or gap is penalized, limits on the number of acceptable hits per read, and so on. Much more information can be found on the BWA manual page.
For a basic alignment like this, we can just go with the default alignment parameters.
Note that bwa writes its (binary) output to standard output by default, so we need to redirect that to a .sai file.
We will execute these commands directly (not in a batch job), but since they are fairly large files we will first set up an interactive development (idev) session, which will give us a compute node for 3 hours:
idev -p normal -m 180 -N 1 -n 24 -A UT-2015-05-18 --reservation=intro_NGS
You can tell you're in a idev session because the hostname command will return a compute node name (e.g. nid00438) instead of a login node name (e.g. login5).
For simplicity, we will just execute these commands directly, one at a time. Each command should only take few minutes and you will see bwa's progress messages in your terminal.
module load bwa cd $SCRATCH/core_ngs/alignment/yeast_bwa bwa aln sacCer3/sacCer3.fa fastq/Sample_Yeast_L005_R1.cat.fastq.gz > yeast_R1.sai bwa aln sacCer3/sacCer3.fa fastq/Sample_Yeast_L005_R2.cat.fastq.gz > yeast_R2.sai
When all is done you should have two .sai files: yeast_R1.sai and yeast_R2.sai. Double check that output was written by doing ls -lh and making sure the file sizes listed are not 0.
Exercise: How long did it take to align the R2 file?
Since you have your own private compute node, you can use all its resources. It has 24 cores, so re-run the R2 alignment asking for 20 execution threads.
bwa aln -t 20 sacCer3/sacCer3.fa fastq/Sample_Yeast_L005_R2.cat.fastq.gz > yeast_R2.sai
Exercise: How much of a speedup did you seen when aligning the R2 file with 20 threads?
Next we use the bwa sampe command to pair the reads and output SAM format data. Just type that command in with no arguments to see its usage.
For this command you provide the same reference index prefix as for bwa aln, along with the two .sai files and the two original FASTQ files. Also, bwa writes its output to standard output, so redirect that to a .sam file.
Here is the command line statement you need. Just execute it on the command line.
bwa sampe sacCer3/sacCer3.fa yeast_R1.sai yeast_R2.sai \ fastq/Sample_Yeast_L005_R1.cat.fastq.gz \ fastq/Sample_Yeast_L005_R2.cat.fastq.gz > yeast_pairedend.sam
You should now have a SAM file (yeast_pairedend.sam) that contains the alignments. It's just a text file, so take a look with head, more, less, tail, or whatever you feel like. Later you'll learn additional ways to analyze the data with samtools once you create a BAM file.
Exercise: What kind of information is in the first lines of the SAM file?
Exercise: How many alignment records (not header records) are in the SAM file?
Exercise: How many sequences were in the R1 and R2 FASTQ files combined?
Exercises:
- Do both R1 and R2 reads have separate alignment records?
- Does the SAM file contain both mapped and un-mapped reads?
- What is the order of the alignment records in this SAM file?
Using cut to isolate fields
Recall the format of a SAM alignment record:
Suppose you wanted to look only at field 3 (contig name) values in the SAM file. You can do this with the handy cut command. Below is a simple example where you're asking cut to display the 3rd column value for the last 10 alignment records.
tail yeast_pairedend.sam | cut -f 3
By default cut assumes the field delimiter is Tab, which is the delimiter used in the majority of NGS file formats. You can specify a different delimiter with the -d option.
You can also specify a range of fields, and mix adjacent and non-adjacent fields. This displays fields 2 through 6, field 9:
tail -20 yeast_pairedend.sam | cut -f 2-6,9
You may have noticed that some alignment records contain contig names (e.g. chrV) in field 3 while others contain an asterisk ( * ). The * means the record didn't map. We're going to use this heuristic along with cut to see about how many records represent aligned sequences. (Note this is not the strictly correct method of finding unmapped reads because not all unmapped reads have an asterisk in field 3. Later you'll see how to properly distinguish between mapped and unmapped reads using samtools.)
First we need to make sure that we don't look at fields in the SAM header lines. We're going to end up with a series of pipe operations, and the best way to make sure you're on track is to enter them one at a time piping to head:
# the ^@ pattern matches lines starting with @ (only header lines), # and -v says output lines that don't match grep -v -P '^@' yeast_pairedend.sam | head
Ok, it looks like we're seeing only alignment records. Now let's pull out only field 3 using cut:
grep -v -P '^@' yeast_pairedend.sam | cut -f 3 | head
Cool, we're only seeing the contig name info now. Next we use grep again, piping it our contig info and using the -v (invert) switch to say print lines that don't match the pattern:
grep -v -P '^@' yeast_pairedend.sam | cut -f 3 | grep -v '*' | head
Perfect! We're only seeing real contig names that (usually) represent aligned reads. Let's count them by piping to wc -l (and omitting omit head of course – we want to count everything).
grep -v -P '^@' yeast_pairedend.sam | cut -f 3 | grep -v '*' | wc -l
Exercise: About how many records represent aligned sequences? What alignment rate does this represent?
Exercise: What might we try in order to improve the alignment rate?
Exercise #2: Basic SAMtools Utilities
The SAMtools program is a commonly used set of tools that allow a user to manipulate SAM/BAM files in many different ways, ranging from simple tasks (like SAM/BAM format conversion) to more complex functions (like sorting, indexing and statistics gathering). It is available in the TACC module system (as well as in BioContainers). Load that module and see what samtools has to offer:
module load samtools samtools
Program: samtools (Tools for alignments in the SAM format) Version: 1.6 (using htslib 1.6) Usage: samtools <command> [options] Commands: -- Indexing dict create a sequence dictionary file 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) addreplacerg adds or replaces RG tags markdup mark duplicates -- File operations collate 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 quickcheck quickly check if SAM/BAM/CRAM file appears intact fastq converts a BAM to a FASTQ fasta converts a BAM to a FASTA -- Statistics 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 depad convert padded BAM to unpadded BAM
In this exercise, we will explore five 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 sections tomorrow we will explore samtools in more in depth.
Know your samtools version!
There are two main "eras" of SAMtools development:
- "original" samtools
- v 0.1.19 is the last stable version
- "modern" samtools
- v 1.0, 1.1, 1.2 – avoid these (very buggy!)
- v 1.3+ – finally stable!
Unfortunately, some functions with the same name in both version eras have different options and arguments! So be sure you know which version you're using. (The samtools version is usually reported at the top of its usage listing).
The default version in the ls5 module system is a "modern" version, but the BioITeam has a copy of the version 0.1.19 samtools for programs that might need it: /work/projects/BioITeam/ls5/bin/samtools-0.1.19. That version is also available as a TACC BioContainers module.
samtools view
The samtools view utility provides a way of converting between SAM (text) and BAM (binary, compressed) format. 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] -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 of the FLAGs in INT present [0] -F INT only include reads with none of the FLAGS in INT present [0] -G INT only EXCLUDE reads with all of the FLAGs in INT present [0] -s FLOAT subsample reads (given INT.FRAC option value, 0.FRAC is the fraction of templates/read pairs to keep; INT part sets seed) -x STR read tag to strip (repeatable) [null] -B collapse the backward CIGAR operation -? print long help, including note about region specification -S ignored (input format is auto-detected) --input-fmt-option OPT[=VAL] Specify a single input file format option in the form of OPTION or OPTION=VALUE -O, --output-fmt FORMAT[,OPT[=VAL]]... Specify output format (SAM, BAM, CRAM) --output-fmt-option OPT[=VAL] Specify a single output file format option in the form of OPTION or OPTION=VALUE -T, --reference FILE Reference sequence FASTA FILE [null] -@, --threads INT Number of additional threads to use [0]
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 specify it (although you do in v0.1.19). We just need to tell the tool to output the file in BAM format, and to include the header records.
cd $SCRATCH/core_ngs/alignment/yeast_bwa cat yeast_pairedend.sam | samtools view -b -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
- we pipe the entire SAM file to samtools view so that the header records are included (required for SAM → BAM conversion)
- samtools view reads its input from standard input by default
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
Notice that this does not show us the header record we saw at the start of the SAM file.
Exercise: What samtools view option will include the header records in its output? Which option would show only the header records?
samtools sort
Looking at some of the alignment record information (e.g. samtools view yeast_pairedend.bam | cut -f 1-4 | more), you will notice that read names appear in adjacent pairs (for the R1 and R2), in the same order they appeared in the original FASTQ file. Since that means the corresponding mappings are in no particular order, searching through the file very inefficient. samtools sort re-orders entries in the SAM file either by locus (contig name + 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 -t TAG Sort by value of TAG. Uses position as secondary index (or read name if -n is set) -o FILE Write final output to FILE rather than standard output -T PREFIX Write temporary files to PREFIX.nnnn.bam --input-fmt-option OPT[=VAL] Specify a single input file format option in the form of OPTION or OPTION=VALUE -O, --output-fmt FORMAT[,OPT[=VAL]]... Specify output format (SAM, BAM, CRAM) --output-fmt-option OPT[=VAL] Specify a single output file format option in the form of OPTION or OPTION=VALUE --reference FILE Reference sequence FASTA FILE [null] -@, --threads INT Number of additional threads to use [0]
In most cases you will be sorting a BAM file from name order to locus order. You can use either -o or redirection with > to control the output.
To sort the paired-end yeast BAM file by position, and get a BAM file named yeast_pairedend.sort.bam as output, execute the following command:
cd $SCRATCH/core_ngs/alignment/yeast_bwa samtools sort -O bam -T yeast_pairedend.tmp 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
- sorting large BAMs will produce many temporary files during processing
- By default sort writes its output to standard output, so we use > to redirect to a file named yeast_pairedend.sort.bam
Exercise: Compare the file sizes of the yeast_pariedend .sam, .bam, and .sort.bam files and explain why they are different.
samtools index
Many tools (like IGV, the Integrative Genomics Viewer) only need to use portions of a BAM file at a given point in time. For example, if you are viewing alignments that are within a particular gene, alignment records on other chromosomes do not need to be loaded. In order to speed up access, BAM files are indexed, producing BAI files which allow fast random access. This is especially important when you have many alignment records.
The utility samtools index creates an index that has the same name as the input BAM file, with suffix .bai appended. Here's the samtools index usage:
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] -@ INT Sets the number of threads [none]
The syntax here is way, way easier. We want a BAI-format index which is the default. (CSI-format is used with extremely long contigs, which don't apply here - the most common use case is for polyploid plant genomes).
So all we have to provide is the sorted BAM:
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.
Exercise: Compare the sizes of the sorted BAM file and its BAI index.
samtools flagstat
Since the BAM file contains records for both mapped and unmapped reads, just counting records doesn't provide information about the mapping rate of our alignment. The samtools flagstat tool provides a simple analysis of mapping rate based on the the SAM flag fields.
Here's how to run samtools flagstat and both see the output in the terminal and save it in a file – the samtools flagstat standard output is piped to tee, which both writes it to the specified file and sends it to its standard output:
samtools flagstat yeast_pairedend.sort.bam | tee yeast_pariedend.flagstat.txt
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% : N/A) 1184360 + 0 paired in sequencing 592180 + 0 read1 592180 + 0 read2 473114 + 0 properly paired (39.95% : N/A) 482360 + 0 with itself and mate mapped 65304 + 0 singletons (5.51% : N/A) 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 relevant.
The most important statistic is the mapping rate (here 46%) but this readout also 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: What proportion of mapped reads were properly paired?
samtools idxstats
More information about the alignment is provided by the samtools idxstats report, which shows how many reads aligned to each contig in your reference. Note that samtools idxstats must be run on a sorted, indexed BAM file.
samtools idxstats yeast_pairedend.sort.bam | tee yeast_pairedend.idxstats.txt
chrI 230218 8820 1640 chrII 813184 36616 4026 chrIII 316620 13973 1530 chrIV 1531933 72675 8039 chrV 576874 27466 2806 chrVI 270161 10866 1222 chrVII 1090940 50893 5786 chrVIII 562643 24672 3273 chrIX 439888 16246 1739 chrX 745751 31748 3611 chrXI 666816 28017 2776 chrXII 1078177 54783 10124 chrXIII 924431 40921 4556 chrXIV 784333 33070 3703 chrXV 1091291 48714 5150 chrXVI 948066 44916 5032 chrM 85779 3268 291 * 0 0 571392
The output has four tab-delimited columns:
- contig name
- contig length
- number of mapped reads
- number of unmapped reads
The reason that the "unmapped reads" field for named chromosomes is not zero is that the aligner may initially assign a potential mapping (contig name and start coordinate) to a read, but then mark it later as unampped if it does meet various quality thresholds.
If you're mapping to a non-genomic reference such as miRBase miRNAs or another set of genes (a transcriptome), samtools idxstats gives you a quick look at quantitative alignment results.
Exercise #3: BWA PE alignment with BioITeam script
Now that you've done everything the hard way, let's see how to do run an alignment pipeline using a BWA alignment script maintained by the BioITeam, /work/projects/BioITeam/common/script/align_bwa_illumina.sh. Type in the script name to see its usage.
align_bwa_illumina.sh 2020_06_14 Align Illumina SE or PE data with bwa. Produces a sorted, indexed, duplicate-marked BAM file and various statistics files. Usage: align_bwa_illumina.sh <aln_mode> <in_file> <out_pfx> <assembly> [ paired trim_sz trim_sz2 seq_fmt qual_fmt ] Required arguments: aln_mode Alignment mode, either global (bwa aln) or local (bwa mem). in_file For single-end alignments, path to input sequence file. For paired-end alignments using fastq, path to the the R1 fastq file which must contain the string 'R1' in its name. The corresponding 'R2' must have the same path except for 'R1'. out_pfx Desired prefix of output files in the current directory. assembly One of hg38, hg19, hg38, mm10, mm9, sacCer3, sacCer1, ce11, ce10, danRer7, hs_mirbase, mm_mirbase, or reference index prefix. Optional arguments: paired 0 = single end alignment (default); 1 = paired end. trim_sz Size to trim reads to. Default 0 (no trimming) trim_sz2 Size to trim R2 reads to for paired end alignments. Defaults to trim_sz seq_fmt Format of sequence file (fastq, bam or scarf). Default is fastq if the input file has a '.fastq' extension; scarf if it has a '.sequence.txt' extension. qual_type Type of read quality scores (sanger, illumina or solexa). Default is sanger for fastq, illumina for scarf. Environment variables: show_only 1 = only show what would be done (default not set) aln_args other bowtie2 options (e.g. '-T 20' for mem, '-l 20' for aln) no_markdup 1 = don't mark duplicates (default 0, mark duplicates) run_fastqc 1 = run fastqc (default 0, don't run). Note that output will be in the directory containing the fastq files. keep 1 = keep unsorted BAM (default 0, don't keep) bwa_bin BWA binary to use. Default bwa 0.7.x. Note that bwa 0.6.2 or earlier should be used for scarf and other short reads. also: NUM_THREADS, BAM_SORT_MEM, SORT_THREADS, JAVA_MEM_ARG Examples: align_bwa_illumina.sh local ABC_L001_R1.fastq.gz my_abc hg38 1 align_bwa_illumina.sh global ABC_L001_R1.fastq.gz my_abc hg38 1 50 align_bwa_illumina.sh global sequence.txt old sacCer3 0 '' '' scarf solexa
There are lots of bells and whistles in the arguments, but the most important are the first few:
- aln_mode – whether to perform a global or local alignment (the 1st argument must be one of those words)
- global mode uses the bwa aln workflow as we did above
- local mode uses the bwa mem command
- in_file – full or relative path to the FASTQ file (just the R1 fastq if paired end). Can be compressed (.gz)
- out_pfx – prefix for all the output files produced by the script. Should relate back to what the data is.
- assembly – genome assembly to use.
- there are pre-built indexes for some common eukaryotes (hg38, hg19, mm10, mm9, danRer7, sacCer3) that you can use
- or provide a full path for a bwa reference index you have built somewhere
- paired flag – 0 means single end (the default); 1 means paired end
- trim_sz – if you want the FASTQ hard trimmed down to a specific length before alignment, supply that number here
We're going to run this script and a similar Bowtie2 alignment script, on the yeast data using the TACC batch system. In a new directory, copy over the commands and submit the batch job. We ask for 1 hour (-t 01:00:00) with 4 tasks/node (-w 4); since we have 4 commands, this will run on 1 compute node.
# Make sure you're not in an idev session by looking at the hostname hostname # If the hostname starts with "nid", exit the idev session # Make a new alignment directory for running these scripts mkdir -p $SCRATCH/core_ngs/alignment/bwa_script cd $SCRATCH/core_ngs/alignment/bwa_script ln -s -f ../fastq # Copy the alignment commands file and submit the batch job cp $CORENGS/tacc/aln_script.cmds . launcher_creator.py -j aln_script.cmds -n aln_script -t 01:00:00 -w 4 -a UT-2015-05-18 -q normal sbatch --reservation=intro_NGS aln_script.slurm showq -u
While we're waiting for the job to complete, lets look at the aln_script.cmds file.
/work/projects/BioITeam/common/script/align_bwa_illumina.sh global ./fastq/Sample_Yeast_L005_R1.cat.fastq.gz bwa_global sacCer3 1 50 /work/projects/BioITeam/common/script/align_bwa_illumina.sh local ./fastq/Sample_Yeast_L005_R1.cat.fastq.gz bwa_local sacCer3 1 /work/projects/BioITeam/common/script/align_bowtie2_illumina.sh global ./fastq/Sample_Yeast_L005_R1.cat.fastq.gz bt2_global sacCer3 1 50 /work/projects/BioITeam/common/script/align_bowtie2_illumina.sh local ./fastq/Sample_Yeast_L005_R1.cat.fastq.gz bt2_local sacCer3 1
Notes:
- The 1st command performs a paired-end BWA global alignment (similar to above), but asks that the 100 bp reads be trimmed to 50 first.
- we refer to the pre-built index for yeast by name: sacCer3
- this index is located in the /work/projects/BioITeam/ref_genome/bwa/bwtsw/sacCer3/ directory
- we provide the name of the R1 FASTQ file
- because we request a PE alignment (the 1 argument) the script will look for a similarly-named R2 file.
- all output files associated with this command will be named with the prefix bwa_global.
- we refer to the pre-built index for yeast by name: sacCer3
- The 2nd command performs a paired-end BWA local alignment.
- all output files associated with this command will be named with the prefix bwa_local.
- no trimming is requested because the local alignment should ignore 5' and 3' bases that don't match the reference genome
- The 3rd command performs a paired-end Bowtie2 global alignment.
- the Bowtie2 alignment script has the same first arguments as the BWA alignment script.
- all output files associated with this command will be named with the prefix bt2_global.
- again, we specify that reads should first be trimmed to 50 bp.
- The 4th command performs a paired-end Bowtie2 local alignment.
- all output files associated with this command will be named with the prefix bt2_local.
- again, no trimming is requested for the local alignment.
Output files
This alignment pipeline script performs the following steps:
- Hard trims FASTQ, if optionally specified (fastx_trimmer)
- Performs the global or local alignment (here, a PE alignment)
- BWA global: bwa aln the R1 and R2 separately, then bwa sampe to produce a SAM file
- BWA local: call bwa mem with both R1 and R2 to produce a SAM file
- Bowtie2 global: call bowtie2 --global with both R1 and R2 to produce a SAM file
- Bowtie2 local: call bowtie2 --local with both R1 and R2 to produce a SAM file
- BWA global: bwa aln the R1 and R2 separately, then bwa sampe to produce a SAM file
- 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.
- <prefix>.align.log – Log file of the entire alignment process.
- check the tail of this file to make sure the alignment was successful
- <prefix>.sort.dup.bam – Sorted, duplicate-marked alignment file.
- <prefix>.sort.dup.bam.bai – Index for the sorted, duplicate-marked alignment file
- <prefix>.flagstat.txt – samtools flagstat output
- <prefix>.idxstats.txt – samtools idxstats output
- <prefix>.samstats.txt – Summary alignment statistics from Anna's stats script
- <prefix>.iszinfo.txt – Insert size statistics (for paired-end alignments) 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 bwa_global.align.log
This will show something like:
..Done alignmentUtils.pl bamstats - 2020-06-14 23:19:38 .. samstats file 'bwa_global.samstats.txt' exists and is not empty - 2020-06-14 23:19:38 =============================================================================== ## Cleaning up files (keep 0) - 2020-06-14 23:19:38 =============================================================================== ckRes 0 cleanup =============================================================================== ## All bwa alignment tasks completed successfully! - 2020-06-14 23:19:38 ===============================================================================
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:
grep 'completed successfully!' *align.log | wc -l
If this command returns 4 (the number of alignment tasks we performed), all went well, and we're done.
But what if something went wrong? How can we tell which alignment task was not successful? 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' *.align.log
The -L option tells grep to only print the filenames that don't contain the pattern. Perfect! To see happens in the case of failure, try it on a file that doesn't contain that message:
grep -L 'completed successfully' aln_script.cmds
Checking alignment statistics
The <prefix>.samstats.txt statistics files produced by the alignment pipeline has a lot of good information in one place. If you look at bwa_global.samstats.txt you'll see something like this:
----------------------------------------------- Aligner: bwa Total sequences: 1184360 Total mapped: 539079 (45.5 %) Total unmapped: 645281 (54.5 %) Primary: 539079 (100.0 %) Secondary: Duplicates: 249655 (46.3 %) Fwd strand: 267978 (49.7 %) Rev strand: 271101 (50.3 %) Unique hit: 503629 (93.4 %) Multi hit: 35450 (6.6 %) Soft clip: All match: 531746 (98.6 %) Indels: 7333 (1.4 %) Spliced: ----------------------------------------------- Total PE seqs: 1184360 PE seqs mapped: 539079 (45.5 %) Num PE pairs: 592180 F5 1st end mapped: 372121 (62.8 %) F3 2nd end mapped: 166958 (28.2 %) PE pairs mapped: 80975 (13.7 %) PE proper pairs: 16817 (2.8 %) -----------------------------------------------
Since this was a paired end alignment there is paired-end specific information reported.
You can also view statistics on insert sizes for properly paired reads in the bwa_global.iszinfo.txt file. This tells you the average (mean) insert size, standard deviation, mode (most common value), and fivenum values (minimum, 1st quartile, median, 3rd quartile, maximum).
Insert size stats for: bwa_global Number of pairs: 16807 (proper) Number of insert sizes: 406 Mean [-/+ 1 SD]: 296 [176 416] (sd 120) Mode [Fivenum]: 228 [51 224 232 241 500]
A quick way to check alignment stats if you have run multiple alignments is again to use grep. For example:
grep 'Total mapped' *samstats.txt
will produce output like this:
bt2_global.samstats.txt: Total mapped: 602893 (50.9 %) bt2_local.samstats.txt: Total mapped: 788069 (66.5 %) bwa_global.samstats.txt: Total mapped: 539079 (45.5 %) bwa_local.samstats.txt: Total mapped: 1008000 (76.5 %
Exercise: How would you list the median insert size for all the alignments?
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, and they are written to take advantage of having multiple cores on TACC nodes where possible.
On the Lonestar5, with its 24 physical cores per node, they are designed to run best with no more than 4 tasks per node.
Always specify wayness 4 for alignment pipeline scripts
These alignment scripts should always be run with a wayness of 4 (-w 4) in the Lonestar5 batch system, meaning at most 4 commands per node.
Welcome to the University Wiki Service! Please use your IID (yourEID@eid.utexas.edu) when prompted for your email address during login or click here to enter your EID. If you are experiencing any issues loading content on pages, please try these steps to clear your browser cache.