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

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


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

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

...

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. The And the standard error text that is generated just goes to your Terminal, bypassing more.

...

Expand
titleAnswer

The bwa aln usage says:

     Usage: bwa aln [options] <prefix> <in.fq>

Required arguments are a <prefix> of the bwa index files, and the input FASTQ file.

There are no arguments specified for the program's output results, but later in the Options section it says

                   -f FILE file to write output to instead of stdout

so So we know output results are written to standard output by default (unless the -f option is specified).

...

Exercise: How would you capture the diagnostic output from bwa aln?

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.

The standard error text that is generated just goes to your Terminal, bypassing more.

Expand
titleAnswer

The bwa aln usage says:

     Usage: bwa aln [options] <prefix> <in.fq>

There are no arguments specified for the program's output results, but later in the Options section it says

                   -f FILE file to write output to instead of stdout

so we know output results are written to standard output by default (unless the -f option is specified).

N

Answer

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 that command in with no arguments 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
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 aligned

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

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?

Expand
titleHint

This The grep command below looks for the pattern  '^HWI' which is the start of every read name (which starts every alignment record).
Remember -c says just count the records, don't display them.

Code Block
languagebash
grep -P -c '^HWI' yeast_pe.sam

Or use the -v (invert) option to tell grep to print all lines that don't match a particular pattern; here, all header lines, which start with @.

Code Block
languagebash
grep -P -v -c '^@' yeast_pe.sam


...

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

Using cut to isolate fields

...

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

Code Block
languagebash
titleCut syntax for multiple fields
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.)

...

Code Block
languagebash
titleCount aligned SAM records
grep -v -P '^@' yeast_pe.sam | cut -f 3 | grep -v '*' | wc -l
# or
grep -v -P '^@' yeast_pe.sam | cut -f 3 | grep -c -v '*'

Read more at Some Linux commands: Advanced commands

...

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
# or
idev -m 90120 -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.9 (using htslib 1.9)

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

  -- 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
     coverage       alignment depth and percent coverage
     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

...

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 arguments2>&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

...

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 )

...

Expand
titleAnswer

samtools view -h shows both header records along with and alignment records.

samtools view -H shows header records only.

...

Looking at some of the alignment record information:

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 same order they appeared in the original FASTQ file. Since that This means the corresponding mappings records are in no particular 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 without any options2>&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
  -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.

...

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

...

Expand
titleAnswer

The yeast_pe.sam text file is the largest at ~348 MB because it is an uncompressed text file.

The name-ordered binary yeast_pe.bam text file only about 1/3 that size, ~111 ~109 MB. They contain exactly the same records, in the same order, but conversion from text to binary results in a much smaller file.

The coordinate-ordered binary yeast_pe.sort.bam file is even slightly smaller, ~92 ~90 MB. This is because BAM files are actually customized gzip-format files. The customization allows blocks of data (e.g. all alignment records for a contig) to be represented in an even more compact form. You can read more about this in section 4 of the SAM format specification.

...

Expand
titleAnswer

While the yeast_pe.sort.bam file is ~92 ~90 MB, its index (yeast_pe.sort.bai) is only 20 KB.

...

Code Block
titlesamtools flagstat output
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.

...

Expand
titleAnswer

About 86% of mapped read were properly paired. This is actually a bit on the low side for ChIP-seq alignments which are typically over 90% 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.

...

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.

...