Read Quality Recalibrator
-------------------------
The tools in this package recalibrate quality scores of
Illumina reads in an aligned BAM file. After recalibration,
the quality scores in the QUAL field in each Illumina read
in the output BAM are accurate in that the reported quality
score is equal to its actual probability of mismatching.
This is process is accomplished by analyzing the covariation
between machine reported quality scores and
1) the position within the read, and
2) the preceding nucleotide (sequencing chemistry effect).
The aligned reads have their dbSNP sites masked out, and the
mismatched bases are used as a metric for the true error rate
of the system. The error rate at different dinucleotides and
positions in the read is then fed into a logistic regression
system which outputs a correction factor for each of those
combinations which are then use to output a recalibrated BAM
file.
Software Dependencies
---------------------
The recalibrator currently depends on the following
applications. Please install these before proceeding.
- Java Runtime Environment 1.6.0_12 or later
- Python 2.4.2 or later
- R 2.6.0 or later
- samtools 0.1.4 or later.
Please update the file paths at the top of
RecalQual.py to point to the local installations of the
software listed above.
Running
-------
Before running the tool, please update the file paths
listed at the top of RecalQual.py to point to the
local installations of the tools listed above.
The recalibrator has two modes: recalibration and
evaluation, which can be run separately or jointly.
By default, the recalibrator will recalibrate only.
To calibrate a given bam file, run the following
command:
python RecalQual.py <source bam> <recalibrated bam>
After recalibration, performing evaluation will walk
through the source BAM file again, remeasuring the
differences between empirical vs. reported quality.
The results of evaluation are comma-delimited text
files (.csv) and graphs (.png) which can be found
in the output directory (see below) for the given run.
A successful recalibration should produce a plot of
empirical vs. observed qualities that shows little
difference between the two values.
To both recalibrate and evaluate, execute:
python RecalQual.py --recalibrate --evaluate <source bam> <recalibrated bam>
To (only) evaluate a given bam file after calibrating:
python RecalQual.py --evaluate <source bam> <recalibrated bam>
Platforms
---------
By default, the recalibrator processes only read groups
originating from Illumina sequencers. To enable calibration
for other platforms, edit the 'platforms' array at the
top of RecalQual.py. Platforms specified here should
case-insensitive match the "PL" attribute of the read
group in the BAM file.
Output
------
The recalibration process keeps many incremental
files around for future analysis. By default, all
of these files will be grouped into the directory
'output.<source bam>/'. By default, this directory
will be created within the working directory. This
location can be changed by editing the output_root
variable at the top of RecalQual.py.
It is safe to delete this supplemental output
directory at any time.
Known Issues
------------
- The recalibrator places severe memory demands on
files with large numbers of read groups.
- If running in 'evaluation' mode (see the 'Running'
section above), X11 is required to generate the
graphs. If running on a machine via ssh, be certain
to enable X tunnelling.
Troubleshooting
---------------
- The memory requirements of the recalibrator will
vary based on the type of JVM running the application
and the number of read groups in the input bam file.
If the application reports 'java.lang.OutOfMemoryError:
Java heap space', increase the max heap size provided
to the JVM by adding ' -Xmx????m' to the jvm_args
variable in RecalQual.py, where '????' is the maximum
available memory on the processing computer.
Support
-------
For support, please email gsadevelopers@broad.mit.edu.
5440dd13df