Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.


Tip
titleReservations

Use our summer school reservation (core-ngs-class-0605) for today when submitting batch jobs to get higher priority on the ls6 normal queue.

Code Block
languagebash
titleRequest an interactive (idev) node
# 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 -p development


# Using our reservation
Code Block
languagebash
titleSubmit a batch job
using our reservation
sbatch --reseservation=core-ngs-class-0605 <batch_file>.slurm  # Thursday
sbatch --reseservation=core-ngs-class-06050606 <batch_file>.slurm  # Friday

Note that todaythe day's reservation name (core-ngs-class-0605) is different from the TACC allocation/project for this class, which is OTH21164.

...

Code Block
languagebash
titleStart an idev session
idev -m 180120 -N 1 -A OTH21164 -r core-ngs-class-0605

Then stage the sample datasets and references we will use.

Code Block
languagebash
titleGet the alignment exercises files
# Copy the   # 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.

Code Block
languagebash
titleGet the alignment exercises files
# 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

...

ReferenceSpeciesBase LengthContig NumberSourceDownload
hg19Human3.1 Gbp25 (really 93)UCSCUCSC GoldenPath
sacCer3Yeast12.2 Mbp17UCSCUCSC GoldenPath
mirbase v20Human subset160 Kbp1908miRBasemiRBase Downloads
vibCho (O395ASM836960v1)Vibrio cholerae~4 Mbp23GenBankGenBank 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.

...

Tip

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

bash
Code Block
language
/work/projects/BioITeam/ref_genome/
   bowtie2/
   bwa/
   hisat2/
   kallisto/
   star/
   tophat/


...

#
Code Block
languagebash
titlegrep to match contig names in a FASTA file
Stage
the
FASTA
files
cds
mkdir -p core_ngs/references/fasta
cd core_ngs/references/fasta
cp $CORENGS/references/fasta/*.fa .

...

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 typealigner optionspro'scon's
global with bwa 

single end reads:

  • bwa aln <R1>
  • bwa samse

paired end reads:

  • bwa aln <R1>
  • bwa aln <R2>
  • bwa sampe
  • simple to use (take default options)
  • good for basic global alignment
  • multiple steps needed
global with bowtie2bowtie2 
  • extremely configurable
  • can be used for RNAseq alignment (after adapter trimming) because of its many options
  • complex (many options)
local with bwa bwa mem
  • simple to use (take default options)
  • very fast
  • no adapter trimming needed
  • good for simple RNAseq analysis
    • the secondary alignments it reports can provide splice junction information
  • always produces alignments with secondary reads
    • must be filtered if not desired
local with bowtie2bowtie2 --local
  • extremely configurable
  • no adapter trimming needed
  • good for small RNA alignment because of its many options
  • complex – many options


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

...

Code Block
languagebash
titleStart an idev session
idev -m 180120 -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  


Code Block
languagebash
module load biocontainers  # takes a while
module load bwa
bwa

...

Code Block
languagebash
titlePrepare BWA reference directory for sacCer3
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

...

Expand
titleHint

Examine the sub-command's usage:

bwa aln 2>&1 | more

If you just type bwa aln | more, the text will probably scroll off your Terminal. This is because bwa always writes its usage to standard error, not to standard output

The pipe ( | ) only connects standard output from bwa aln to standard input of the more command – but no standard output is generated. And the standard error text that is generated just goes to your Terminal, bypassing more.

...

Tip
titleMake sure your output files are not empty

Double check that output was written by doing ls -lh and making sure the file sizes listed are not 0.

When redirection ( > ) to a file is used, the target file is created whether or not the command produced any output!

...

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.

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

...

Expand
titleAnswer

The bwa aln usage doesn't say anything about the program's diagnostic output, so we can assume it will be written to standard error. So it could be redirected like this:

Code Block
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.

...

Expand
titleSetup (if needed)


Code Block
languagebash
# 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)?
Expand
titleAnswer

wc -l yeast_pe.sam  reports 1,184,378 lines

The alignment SAM file will contain records for both R1 and R2 reads, so we need to count sequences in both files.

zcat ./fastq/Sample_Yeast_L005_R[12]*gz | wc -l | awk '{print $1/4}' reports 1,184,360 reads that were alignedread sequences.

So the SAM file has 18 more lines than the R1+R2 total. These are the header records that appear before any alignment records.

...

Expand
titleAnswers

The SAM file must contain both mapped and un-mapped reads, because there were 1,184,360 R1+R2 reads and the same number of alignment records.

Alignment records occur in the same read-name order as they did in the FASTQ, except that they come in pairs. The R1 read comes 1st, then the corresponding R2. This is called read name ordering.

The command below uses cut to extract the 1st Tabtab-delimited field (-f 1) from the first few alignment records:

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

Next we'll see how to tell which read is the R1 and which is the R2.

...

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.

...

Expand
titleMake sure you're in a idev session


Code Block
languagebash
titleStart an idev session
idev -m 120 -N 1 -A OTH21164 -r core-ngs-class-0605  # orThursday
idev -m 120 -N 1 -A OTH21164 -p development  
Code Block
languagebash
# If not already loaded module load biocontainers # takes a
r core-ngs-class-0606  # Friday

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



Code Block
languagebash
# If not already loaded
module load biocontainers  # takes a while

module load samtools
samtools 2>&1 | more

...

Code Block
titleSAMtools suite usage
Program: samtools (Tools for alignments in the SAM format)
Version: 1.920 (using htslib 1.920)

Usage:   samtools <command> [options]

Commands:
 
-- Indexing
 
   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 depthbedcov      flagstat   read depth per BED simpleregion
stats   coverage   idxstats    alignment depth and BAMpercent indexcoverage
stats   depth   phase       compute the depth
phase heterozygotes  flagstat    stats   simple stats
   idxstats  generate stats (former bamcheck)  BAM index --stats
Viewing   cram-size   flags   list CRAM Content-ID and Data-Series sizes
 explain BAM flagsphase      tview    phase heterozygotes
   stats text alignment viewer      view 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.

Warning
titleKnow your samtools version!

There are two main "eras" of SAMtools development:

  • "original" samtools, controlled by author Heng Li
    • v 0.1.19 is the last stable version
  • "modern" samtools, controlled by a group of programmers
    • 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).

TACC BioContainers also offers the original samtools version: samtools/ctr-0.1.19--3.

...

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:

Code Block
titlesamtools view usage
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]
  -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]
  -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)
  -M       use the multi-region iterator (increases the speed, removes
           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
  -?       print 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]
               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]
      --write-index
               Automatically index the output files [off]
      --verbosity INT
               Set level of verbosity

...

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

ExerciseExercises:

  • What samtools view option will include the header records in its output?
  • Which option would show only the header records?
Expand
titleHint

Note that samtools (like bwa) writes its help to standard error, but less and more only accept input on standard input. So the syntax redirecting standard error to standard input must be used before the pipe to less or more.

samtools view 2>&1 | less -I

then search for "header" ( /header )

...

Code Block
languagebash
titleView BAM records
samtools view yeast_pe.bam | cut -f 1-4 | more

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

Code Block
titlesamtools sort usage
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: 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      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]
      --write-index
               Automatically index the output files [off]
      --verbosity INT
               Set level of 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 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
Code Block
titlesamtools index usage
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                   Interpret all filename arguments as files to be indexed
  -o, --output FILE    Write index to FILE [alternative to <out.index> in args]
  -@, --threads INT    Sets the number of threads [none]

...

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.

...