114 lines
4.0 KiB
Plaintext
114 lines
4.0 KiB
Plaintext
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.
|