Content Comparison

...

Use our summer school reservation (CoreNGS-Thu) when submitting batch jobs to get higher priority on the ls6 normal queue.

# Request a 180 minute interactive node on the normal queue using our reservation
idev -m 120 -N 1 -A OTH21164 -r CoreNGS-Thu

# Request a 120 minute idev node on the development queue 
idev -m 120 -N 1 -A OTH21164 -p development

# Using our reservation
sbatch --reseservation=CoreNGS-Thu <batch_file>.slurm

Note that the reservation name (CoreNGS) is different from the TACC allocation/project for this class, which is OTH21164.

Overview

Image Removed

After raw sequence files are generated (in FASTQ format), quality-checked, and preprocessed 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 quantification tools).

Stage the alignment data

First connect to ls6.tacc.utexas.edu and start an idev session. This should be second nature by now

...

...

# Request a 180 minute interactive node on the normal queue using our reservation
idev -m 120 -N 1 -A OTH21164 -r core-ngs-class-0605  # Thursday
idev -m 120 -N 1 -A OTH21164 -r core-ngs-class-0606  # Friday

# Request a 120 minute idev node on the development queue 
idev -m 120 -N 1 -A OTH21164 -

Then stage the sample datasets and references we will use.

p development

# Copy the FASTA files for building references
mkdir -p $SCRATCH/core_ngs/references/fasta
cp $CORENGS/references/fasta/*.fa   $SCRATCH/core_ngs/references/fasta/

# Copy the FASTQ files that will be used for alignment
mkdir -p $SCRATCH/core_ngs/alignment/fastq
cp $CORENGS/alignment/*fastq.gz $SCRATCH/core_ngs/alignment/fastq/
cd $SCRATCH/core_ngs/alignment/fastq

These are descriptions of the FASTQ files we copied:

...

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 version is v21. (See here for information about many more genomes.)

...

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 and regular expressions)

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 simple regular expressions here, but learning more about them will pay handsome dividends for you in the future.

First stage the FASTA files we'll need:

# Stage the FASTA files
cds
mkdir -p core_ngs/references/fasta
cd core_ngs/references/fasta
cp $CORENGS/references/fasta/*.fa .

Here's how to execute grep to list contig names in a FASTA file.

cd $SCRATCH/core_ngs/references/fasta
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 FASTA 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 we have seen, during command line parsing and evaluation the shell will often look for special metacharacters 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. (Read more about Literal characters and metacharacters and 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 pattern argument. But for grep, the more specific the pattern, the better. So we constrain where the > can appear on the line. The special carat ( ^ )  metacharacter represents "beginning of line". So ^> means "beginning of a line followed by a > character".

...

# Copy the FASTA files for building references
mkdir -p $SCRATCH/core_ngs/references/fasta
cp $CORENGS/references/fasta/*.fa $SCRATCH/core_ngs/references/fasta/

Exercise: How many lines does the sacCer3 reference have, and how many contigs are there?

...

cd $SCRATCH/core_ngs/references/fasta
grep -P '^>' sacCer3.fa | wc -l

# and to count the lines:
wc -l sacCer3.fa

Or use grep's -c option that says "just count the line matches"

grep -P -c '^>' sacCer3.fa

Aligner overview

...

sbatch --reseservation=core-ngs-class-0605 <batch_file>.slurm  # Thursday
sbatch --reseservation=core-ngs-class-0606 <batch_file>.slurm  # Friday

Overview

Image Added

After raw sequence files are generated (in FASTQ format), quality-checked, and preprocessed 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 quantification tools).

Stage the alignment data

First connect to ls6.tacc.utexas.edu and start an idev session. This should be second nature by now

idev -m 120 -N 1 -A OTH21164 -r core-ngs-class-0605  # Thursday
idev -m 120 -N 1 -A OTH21164 -r core-ngs-class-0606  # Friday

# or, without the reservation:
idev -m 120 -N 1 -A OTH21164 -p development

Then stage the sample datasets and references we will use.

# Copy the FASTA files for building references
mkdir -p $SCRATCH/core_ngs/references/fasta
cp $CORENGS/references/fasta/*.fa   $SCRATCH/core_ngs/references/fasta/

# Copy the FASTQ files that will be used for alignment
mkdir -p $SCRATCH/core_ngs/alignment/fastq
cp $CORENGS/alignment/*fastq.gz $SCRATCH/core_ngs/alignment/fastq/
cd $SCRATCH/core_ngs/alignment/fastq

These are descriptions of the FASTQ files we copied:

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 version is v21. (See here for information about many more genomes.)

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

/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 and regular expressions)

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 simple regular expressions here, but learning more about them will pay handsome dividends for you in the future.

First stage the FASTA files we'll need:

cds
mkdir -p core_ngs/references/fasta
cd core_ngs/references/fasta
cp $CORENGS/references/fasta/*.fa .

Here's how to execute grep to list contig names in a FASTA file.

cd $SCRATCH/core_ngs/references/fasta
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 FASTA 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 we have seen, during command line parsing and evaluation the shell will often look for special metacharacters 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. (Read more about Literal characters and metacharacters and 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 pattern argument. But for grep, the more specific the pattern, the better. So we constrain where the > can appear on the line. The special carat ( ^ )  metacharacter represents "beginning of line". So ^> means "beginning of a line followed by a > character".

# Copy the FASTA files for building references
mkdir -p $SCRATCH/core_ngs/references/fasta
cp $CORENGS/references/fasta/*.fa $SCRATCH/core_ngs/references/fasta/

Exercise: How many lines does the sacCer3 reference have, and how many contigs are there?

cd $SCRATCH/core_ngs/references/fasta
grep -P '^>' sacCer3.fa | wc -l

# and to count the lines:
wc -l sacCer3.fa

grep -P -c '^>' sacCer3.fa

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.

Exercise #1: BWA global alignment – Yeast ChIP-seq

...

idev -m 180120 -N 1 -A OTH21164 -r CoreNGS    core-ngs-class-0605  # Thursday
idev -m 120 -N 1 -A OTH21164 -r core-ngs-class-0606  # Friday

# or, -Awithout TRA23004the reservation
idev -m 120 -N 1 -A OTH21164 -p development  # or -A TRA23004

module load biocontainers  # takes a while
module load bwa
bwa

...

mkdir -p $SCRATCH/core_ngs/references/bwa/sacCer3
cd $SCRATCH/core_ngs/references/bwa/sacCer3

# Create a symbolic link to the sacCer3 FASTA file
# so it can be accessed directly from this directory
ln -sf ../../fasta/sacCer3.fa
ls -l

...

mkdir -p $SCRATCH/core_ngs/alignment/yeast_bwa
cd $SCRATCH/core_ngs/alignment/yeast_bwa
ln -sf ../fastq
ln -sf .

# Create symbolic links to the fastq and sacCer3 reference directories
# so we can access them directly from this alignment directory
ln -sf ../fastq
ln -sf ../../references/bwa/sacCer3
ls -l

As our workflow indicated, we first use bwa aln on the R1 and R2 FASTQs, producing a BWA-specific .sai intermediate binary files.

Exercise: What does does bwa aln needs in the way of arguments? And where does it write its binary output?

Examine the sub-command's usage:

bwa

aln

Required arguments are a <prefix> of the bwa index files, and the input FASTQ file. There are lots of options, but here is a summary of the most important ones.

...

There are lots of options, but here is a summary of the most important ones.

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  For a basic alignment like this, we can just go with the default alignment parameters.

Note that Since bwa writes its (binary) output to standard output by default, so we need to redirect that to a .sai file.

...

...

Exercise: How long did it take to align the R2 file?

[bwa_aln] 17bp reads: max_diff = 2
[bwa_aln] 38bp reads: max_diff = 3
[bwa_aln] 64bp reads: max_diff = 4
[bwa_aln] 93bp reads: max_diff = 5
[bwa_aln] 124bp reads: max_diff = 6
[bwa_aln] 157bp reads: max_diff = 7
[bwa_aln] 190bp reads: max_diff = 8
[bwa_aln] 225bp reads: max_diff = 9
[bwa_aln_core] calculate SA coordinate... 50.76 sec
[bwa_aln_core] write to the disk... 0.07 sec
[bwa_aln_core] 262144 sequences have been processed.
[bwa_aln_core] calculate SA coordinate... 50.35 sec
[bwa_aln_core] write to the disk... 0.07 sec
[bwa_aln_core] 524288 sequences have been processed.
[bwa_aln_core] calculate SA coordinate... 13.64 sec
[bwa_aln_core] write to the disk... 0.01 sec
[bwa_aln_core] 592180 sequences have been processed.
[main] Version: 0.7.17-r1188
[main] CMD: /usr/local/bin/bwa aln sacCer3/sacCer3.fa fastq/Sample_Yeast_L005_R1.cat.fastq.gz
[main] Real time: 8578.584186 sec; CPU: 8377.825597 sec

Since you have your own private compute node, you can use all its resources. It has 128 cores, so re-run the R2 alignment asking for 60 execution threads.

bwa aln -t 60 sacCer3/sacCer3.fa \
  fastq/Sample_Yeast_L005_R2.cat.fastq.gz > yeast_pe_R2.sai

...

[bwa_aln] 17bp reads: max_diff = 2
[bwa_aln] 38bp reads: max_diff = 3
[bwa_aln] 64bp reads: max_diff = 4
[bwa_aln] 93bp reads: max_diff = 5
[bwa_aln] 124bp reads: max_diff = 6
[bwa_aln] 157bp reads: max_diff = 7
[bwa_aln] 190bp reads: max_diff = 8
[bwa_aln] 225bp reads: max_diff = 9
[bwa_aln_core] calculate SA coordinate... 266.70 sec
[bwa_aln_core] write to the disk... 0.04 sec
[bwa_aln_core] 262144 sequences have been processed.
[bwa_aln_core] calculate SA coordinate... 268.94 sec
[bwa_aln_core] write to the disk... 0.03 sec
[bwa_aln_core] 524288 sequences have been processed.
[bwa_aln_core] calculate SA coordinate... 72.26 sec
[bwa_aln_core] write to the disk... 0.01 sec
[bwa_aln_core] 592180 sequences have been processed.
[main] Version: 0.7.17-r1188
[main] CMD: /usr/local/bin/bwa aln -t 60 sacCer3/sacCer3.fa fastq/Sample_Yeast_L005_R2.cat.fastq.gz
[main] Real time: 75.931612 sec; CPU: 179166.153315 sec

Next we use the bwa sampe command to pair the reads and output SAM format data. Just type that command in with no arguments Exercise: How would you capture the diagnostic output from bwa aln?

bwa aln -t 60 sacCer3/sacCer3.fa \
  fastq/Sample_Yeast_L005_R2.cat.fastq.gz \
  > yeast_pe_R2.sai 2> yeast_pe_R2.log

Next we use the bwa sampe command to pair the reads and output SAM format data. Just type bwa sampe 2>&1 | more 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 by default, so redirect that to a .sam file.

...

# Copy the FASTA files for building references
mkdir -p $SCRATCH/core_ngs/references
cp $CORENGS/references/fasta/*.fa $SCRATCH/core_ngs/references/fasta/

# Copy a pre-built bwa index for sacCer3
mkdir -p $SCRATCH/core_ngs/references/bwa/sacCer3
cp $CORENGS/references/bwa/sacCer3/*.* \
  $SCRATCH/core_ngs/references/bwa/sacCer3/

# Get the FASTQ to align
mkdir -p $SCRATCH/core_ngs/alignment/fastq
cp $CORENGS/alignment/*fastq.gz $SCRATCH/core_ngs/alignment/fastq/

# Stage the BWA .sai files
mkdir -p $SCRATCH/core_ngs/alignment/yeast_bwa
cd $SCRATCH/core_ngs/alignment/yeast_bwa
ln -sf ../fastq
ln -sf ../../references/bwa/sacCer3
cp $CORENGS/catchup/yeast_bwa/*.sai .

...

You should now have a SAM file (yeast_pe.sam) that contains the alignments.

ExerciseExercises:

• How many lines does the SAM file have?
• How does this compare to the number of input sequences (R1+R2)?

It's yeast_pe.sam is 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: How many alignment records (not header records) are in the SAM file?

grep -P -c '^HWI' yeast_pe.sam

grep -P -v -c '^@' yeast_pe.sam

...

grep -Pv '^@' yeast_pe.sam | head | cut -f 1

Using cut to isolate fields

...

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.

...

You can also specify a range of fields, and mix adjacent and non-adjacent fields. This displays fields 2 through 6 , and field 9:

tail -20 yeast_pe.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.)

...

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

Read more at Some Linux commands: Advanced commands

...

# or
grep -v -P '^@' yeast_pe.sam | cut -f 3 | grep -c -v '*'

Read more at Some Linux commands: Advanced commands

Exercise: About how many records represent aligned sequences? What alignment rate does this represent?

...

idev -m 120 -N 1 -A OTH21164 -r CoreNGS   core-ngs-class-0605  # Thursday
idev -m 120 -N 1 -A OTH21164 -r core-ngs-class-0606  # Friday

# or, -Awithout TRA23004the reservation:
idev -m 90120 -N 1 -A OTH21164 -p development  # or -A TRA23004

# If not already loaded
module load biocontainers  # takes a while

module load samtools
samtools 2>&1 | more

Program: samtools (Tools for alignments in the SAM format)
Version: 1.920 (using htslib 1.920)

Usage:   samtools <command> [options]

Commands:
  -- Indexing
   dict  dict           create a sequence dictionary file
 
   faidx          index/extract FASTA
 
   fqidx          index/extract FASTQ
 
   index          index alignment



-- Editing
 
   calmd          recalculate MD/NM tags and '=' bases
 
   fixmate        fix mate information
     reheader       replace BAM header
 
   targetcut      cut fosmid regions (for fosmid pool only)
 
   addreplacerg   adds or replaces RG tags
 
   markdup        mark duplicates
   ampliconclip   clip oligos from the end of reads

-- File operations
 
   collate        shuffle and group alignments by name
 
   cat            concatenate BAMs
   consensus      produce a consensus Pileup/FASTA/FASTQ
   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
   --import Statistics      bedcov  Converts FASTA or FASTQ files to SAM/BAM/CRAM
read depth per BEDreference region     Generates coveragea reference from aligned data
  alignment depthreset and percent coverage      depth Reverts aligner changes in reads

-- Statistics
 compute the depth  bedcov         read depth per BED region
   coverage       alignment depth and percent coverage
   depth          compute the depth
   flagstat       simple stats
     idxstats       BAM index stats
   cram-size      list CRAM Content-ID and Data-Series sizes
   phase          phase heterozygotes
     stats          generate stats (former bamcheck)

  -- Viewing
     flags          explain BAM flags
     tview          text alignment viewer
     view           SAM<->BAM<->CRAM conversion
     depadphase heterozygotes
   stats          generate stats (former bamcheck)
   ampliconstats  generate amplicon specific stats

-- Viewing
   flags explain  BAM flags
   head           header viewer
   tview text     alignment viewer
   view           SAM<->BAM<->CRAM conversion
   depad          convert padded BAM to unpadded BAM
   samples        list the samples in a set of SAM/BAM/CRAM files

-- Misc
   help [cmd]     display this help message or help for [cmd]
   version        detailed version information

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 capabilities more in depth.

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 2>&1 | more. You should see:

Usage: samtools view [options] <in.bam>|<in.sam>|<in.cram> [region ...]

Options:
  -b       output BAM
 convert padded-C 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 capabilities more in depth.

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    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]
  -X       include customized index file
  -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]
  -d STR:STR
           only include reads with tag STR and associated value STR [null]
  -D STR:FILE
           only include reads with tag STR and associated values listed in
           FILE [null]
  -tq FILEINT  FILE listingonly referenceinclude namesreads andwith lengthsmapping (seequality long>= help)INT [null0]
  -Xl STR   only include reads includein customizedlibrary indexSTR file[null]
  -Lm INT FILE  only include reads overlapping this BED FILE [null] with number of CIGAR operations consuming
    -r STR   only include reads inquery readsequence group>= STRINT [null0]
  -Rf INT FILE  only include reads with read group listed in FILE [null]
  -d STR:STR
         all  of the FLAGs in INT present [0]
  -F INT   only include reads with none tagof STRthe andFLAGS associatedin valueINT STRpresent [null0]
  -DG STR:FILEINT   only EXCLUDE reads with all  of the FLAGs onlyin includeINT readspresent with[0]
tag STR and-s associatedFLOAT valuessubsample listedreads in(given INT.FRAC option value, 0.FRAC is the
     FILE [null]   -q INT fraction of onlytemplates/read includepairs readsto withkeep; mappingINT qualitypart >=sets INTseed)
[0]   -l STR   only include reads in library STR [null]
  -m INT   only include reads with number of CIGAR operations consuming-M       use the multi-region iterator (increases the speed, removes
           duplicates and outputs the reads as they queryare sequenceordered >=in INT [0]the file)
  -fx STR INT  read onlytag includeto readsstrip with all(repeatable) [null]
 of the-B FLAGs in INT present [0]  collapse -Fthe INTbackward CIGAR operation
only include reads-? with none of the FLAGS in INTprint 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
   long help, including note about region specification
  -S       ignored (input format is auto-detected)
  --no-PG  do not add a PG line
      --input-fmt-option OPT[=VAL]
       fraction of templates/read pairs to keep; INT part setsSpecify seed)a single input -Mfile format option in the form
 use the multi-region iterator (increases the speed, removes       of OPTION or OPTION=VALUE
 duplicates and outputs the reads as they are ordered in the file)
  -x STR   read tag to strip (repeatable) [null]
  -B       collapse the backward CIGAR operation
  -?-O, --output-fmt FORMAT[,OPT[=VAL]]...
               Specify output format (SAM, BAM, CRAM)
      --output-fmt-option OPT[=VAL]
              print longSpecify help,a includingsingle noteoutput aboutfile regionformat specificationoption in the -Sform
      ignored (input format is auto-detected)   --no-PG  doof notOPTION addor aOPTION=VALUE
PG line
      -T, --input-fmt-option OPT[=VAL]reference FILE
               Reference Specifysequence aFASTA singleFILE input[null]
file format option in the form-@, --threads INT
               Number of OPTION or OPTION=VALUE additional threads to use [0]
     -O, --outputwrite-fmt FORMAT[,OPT[=VAL]]...index
               Automatically index Specifythe output format (SAM, BAM, CRAM)files [off]
      --verbosity INT
--output-fmt-option OPT[=VAL]              Set level 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]
      --write-index
               Automatically index the output files [off]
      --verbosity INT
               Set level of verbosity

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.

...

mkdir -p $SCRATCH/core_ngs/alignment/yeast_bwa
cd $SCRATCH/core_ngs/alignment/yeast_bwa
cp $CORENGS/catchup/yeast_bwa/yeast_pe.sam .

cd $SCRATCH/core_ngs/alignment/yeast_bwa
samtools view -b yeast_pe.sam > yeast_pe.bam 

• the -b option tells the tool to output BAM format

The BAM file is a binary file, not a text file, so how do you look at its contents now? Just use samtools view without the -b option. Remember to pipe output to a pager!

samtools view yeast_pe.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_pe.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.bamof verbosity

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.

mkdir -p $SCRATCH/core_ngs/alignment/yeast_bwa
cd $SCRATCH/core_ngs/alignment/yeast_bwa
cp $CORENGS/catchup/yeast_bwa/yeast_pe.sam .

cd $SCRATCH/core_ngs/alignment/yeast_bwa
samtools view -b yeast_pe.sam > yeast_pe.bam 

• the -b option tells the tool to output BAM format

The BAM file is a binary file, not a text file, so how do you look at its contents now? Just use samtools view without the -b option. Remember to pipe output to a pager!

samtools view yeast_pe.bam | more

Notice that this does not show us the header record we saw at the start of the SAM file.

Exercises:

• 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:

samtools view yeast_pe.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. This means the records are in name order and, searching through the file is 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 2>&1 | more, you see its help page:

Usage: samtools sort [options...] [in.bam]
Options:
  -l INT     Set compression level, from 0 (uncompressed) to 9 (best)
  -u         Output uncompressed data (equivalent to -l 0)
  -m INT     Set maximum memory per thread; suffix K/M/G recognized [768M]
  -M         Use minimiser for clustering unaligned/unplaced reads
  -R         Do not use reverse strand (only compatible with -M)
  -K INT     Kmer size to use for minimiser [20]
  -I FILE    Order minimisers by their position in FILE FASTA
  -w INT     Window size for minimiser indexing via -I ref.fa [100]
  -H         Squash homopolymers when computing minimiser
  -n         Sort by read name (natural): cannot be used with samtools index
  -N         Sort by read name (ASCII): cannot be used with samtools index
  -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
      --no-PG
               Do not add a PG line
      --template-coordinate
               Sort by template-coordinate
      --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 Specifysequence aFASTA singleFILE output[null]
file format option in the form-@, --threads INT
               Number of additional threads OPTIONto or OPTION=VALUEuse [0]
      --write-referenceindex
FILE               Automatically Referenceindex sequencethe FASTAoutput FILEfiles [nulloff]
   -@,   --threadsverbosity INT
               Set Numberlevel of additional threads to use [0]verbosity

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.

...

• 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
  • make sure the temporary file prefix is different from the input BAM file prefix!
• By default sort writes its output to standard output, so we use > to redirect to a file named yeast_pairedendpe.sort.bam

Exercise: Compare the file sizes of the yeast_pe .sam, .bam, and .sort.bam files and explain why they are different.

...

...

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 -M [-bc] [-m INT] <in1.bam> <in2.bam>...
   or: samtools index [-bc] [-m INT] <in.bam> [out.index]
Options:
  -b, --bai            Generate BAI-format index for BAM files [default]
  -c, --csi            Generate CSI-format index for BAM files
  -m, --min-shift INT  Set minimum interval size for CSI indices to 2^INT [14]
  -M       Generate BAI-format index for BAM files [default]   -c   Interpret all filename arguments Generateas CSI-formatfiles indexto forbe BAMindexed
files  -o, --moutput INTFILE   Set minimumWrite intervalindex sizeto forFILE CSI[alternative indicesto to<out.index> 2^INTin [14args]
  -@, --threads INT    Sets the number of threads [none]

...

...

1184360 + 0 in total (QC-passed reads + QC-failed reads)
1184360 + 0 primary
0 + 0 secondary
0 + 0 supplementary
0 + 0 duplicates
0 + 0 primary duplicates
547664 + 0 mapped (46.24% : N/A)
547664 + 0 primary 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)

...

The most important statistic is the mapping rate ( – here 46%) but , which is low. 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.

...

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.

...

The output has four tab-delimited columns:

1. contig name
2. contig length
3. number of mapped reads
4. 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.

...