AlignmentMismatches¶
The "alignmentMismatches" transform expands a read alignment into sparse rows
for mismatching aligned bases. It is intended for BAM pileup views where
non-reference read bases need separate marks on top of read bodies.
The transform uses the read sequence, CIGAR string, and MD tag. The MD tag is
required because ordinary M CIGAR operations do not distinguish matches from
mismatches. Insertions, deletions, skipped regions, and clipped bases are not
emitted as mismatch rows; use flattenCigar to render
those operations.
The transform preserves the input fields, or only the fields listed in
copyFields when it is defined, and adds:
| field | description |
|---|---|
mismatchStart |
Reference start coordinate for the mismatching base |
mismatchEnd |
Reference end coordinate for the mismatching base |
readOffset |
Query/read offset for the mismatching base |
base |
Read base from the sequence field |
refBase |
Reference base from the MD tag |
baseQuality |
Base quality from the quality array, when available |
Reference coordinates are 0-based and half-open. Unavailable CIGAR values
(*) produce no rows.
The copyFields parameter limits which top-level input fields are copied to
the emitted mismatch rows after they have been used by the transform. For
example, seq, qual, and md can be read as inputs without being copied to
every mismatch row.
Parameters¶
cigar- Type: string (field name)
The CIGAR string.
Default value:
"cigar" copyFields- Type: array
Top-level input fields copied to the emitted mismatch rows.
If omitted, all input fields are copied. This can be used to avoid copying bulky fields such as read sequence or base quality arrays while still allowing the transform to read its input fields.
description- Type: string
A description of the transform step. Can be used for documentation and agent context.
md- Type: string (field name)
MD tag field.
Default value:
"md" quality- Type: string (field name)
Base quality field.
Default value:
"qual" sequence- Type: string (field name)
Read sequence field.
Default value:
"seq" start- Type: string (field name)
The read's reference start coordinate.
Default value:
"start"
Example¶
Given the following data:
| chrom | start | name | cigar | seq | qual | md |
|---|---|---|---|---|---|---|
| chr1 | 100 | read1 | 10M | AAAATAAAAA | [30, 30, 30, 30, 17, 30, 30, 30, 30, 30] | 4A5 |
... and configuration:
{
"type": "alignmentMismatches"
}
The MD tag says that the first four aligned reference bases match, the next
reference base is A, and the following five bases match. The read has T at
that offset, so one mismatch row is emitted:
| chrom | start | name | cigar | seq | md | mismatchStart | mismatchEnd | readOffset | base | refBase | baseQuality |
|---|---|---|---|---|---|---|---|---|---|---|---|
| chr1 | 100 | read1 | 10M | AAAATAAAAA | 4A5 | 104 | 105 | 4 | T | A | 17 |
Layers can color base with a nominal scale and filter or fade marks using
baseQuality.
For a complete genomic visualization example, see BAM Read Alignments.