Planning to contribute a view of Molecular Annotations (MA/Ma) in the future

[mrvollger]

Hello,

We have been working on a draft tag for annotating intervals along a sequenced molecule: nucleosome positions, methylation-sensitive patches, regulatory element calls, or any user-defined region. MM/ML handles single-base calls well, but in Fiber-seq, much of the single-molecule data comes out as intervals, and there is nowhere to put them today.

To address this, we are working on a set of SAM tags (molecular annotation tags) which we hope to get officially included in the hts spec.

• Draft spec: https://github.com/fiberseq/Molecular-annotation-spec

I am opening this issue because, as we make progress on this, I hope to contribute a PR in the future for a molecular annotation coloring scheme that mirrors your existing basemod work. For now, we plan to just work in our fork:

• https://github.com/vollgerlab/igv

but in the future we'd like to contribute a PR if you approve, and we wanted to start the discussion as an issue.

Cheers,
Mitchell

[jrobinso]

@mrvollger I've added support for these tags, pushed and available in the snapshot build. I was actually responding to another request for this without connecting it in my mind with this ticket, and just made the connection now. Anyway let's use that as a starting point. Anything in this implementation can be changed. A user doc draft follows

---

Fiber-seq nucleosomes and MSPs

IGV can draw the nucleosomes and methylation sensitive patches (MSPs) called by
fibertools directly on each read, so you can see
the chromatin state of every individual molecule.

Requirements

A BAM or CRAM file processed by fibertools, with nucleosome and MSP calls stored in either tag format:

• Molecular annotation tags: Ma and Aq, written by current fibertools. The uppercase MA and AQ written by
  fibertools 0.10–0.12 are also supported.
• Legacy tags: ns/nl (nucleosomes) and as/al/aq (MSPs), written by older fibertools versions.

Turning it on

1. Load the file and navigate to a region with reads.
2. Right-click the alignment track and choose Color alignments by > fiber-seq nucleosomes / MSPs.

The menu item appears only after IGV has loaded reads that carry these tags.

What you see

Each read is drawn in a pale color for its strand, with its annotations on top:

Color	Meaning
Gray	Nucleosome
Teal	MSP (methylation sensitive patch)
Red	MSP called as a FIRE (Fiber-seq Inferred Regulatory Element). Darker red means a higher FIRE quality.

These colors can be changed in View > Preferences > Base Mods, under Fiber-seq colors.

Hover over or click a read to see the annotations at that position, for example:

Nucleosome: 3081871-3082038 (168 bp)
MSP: 47481338-47481485 (148 bp), FIRE quality 243

Positions are 1-based and inclusive.

As with base modification coloring, mismatched bases that are not covered by an annotation are shown in gray rather
than in nucleotide colors, so they don't compete with the annotations. Small insertion markers (the purple I-beams)
are not drawn; insertions large enough to be labeled with their size still are.

Sessions and batch scripts

The color mode is saved with the session. In a batch script, select it with:

colorBy FIBERSEQ

Limitations

• Reads whose sequence was changed after fibertools annotated them, for example by trimming, are drawn without
  annotations. IGV detects this from the read length recorded in the Ma tag.
• Reads with legacy tags and no stored sequence (SEQ of *, common for secondary alignments) are drawn without
  annotations.
• For hard-clipped alignments with legacy tags, such as some supplementary alignments, annotations may be misplaced.
  fibertools itself handles these tags the same way.
• Annotations are not drawn when supplementary alignments are linked into a single row.
• Annotation names (An tag) are not shown.

[mrvollger]

Hi @jrobinso,

This is great news! Thanks for your effort.

I will put together some suggestions for the user doc, but I wanted to play with the snapshot first. Can you remind me where to find the main branch snapshot? I went to the website and downloaded the v3 beta, but that doesn't seem to be the right one.

Thanks in advance!

Cheers,
Mitchell

[jrobinso]

Hi @mrvollger . You can download the snapshot from here: https://igv.org/doc/desktop/#DownloadSnapshot/. See the instructions if you are on a Mac, we don't create notarized mac packages for the snapshot. If you'd rather wait for a packaged Mac app we will be updating the beta release later this week.

I've been testing with "NAPA.bam", it's the only test data I have. I welcome input not only on the doc but the also the implementation, including choice of colors.

[mrvollger]

Awesome, got it working! I will play with it and come back with ideas ASAP on the docs + implementation.

One request: these are the colors we have used in the past for these elements, and it would be great to keep them the same here if possible.
nuc │ 169,169,169
msp │ 147,112,219
fire | 139,0,0

[jrobinso]

Will do (change the colors). WRT fire, this implementation shades by FIRE quality. Specifically opacity increases with FIRE quality, is that something you have been doing, or is desired?

[mrvollger]

I think that is a good idea and we would use it. Right now we use a color pallet of different reds but that doesn't generalize well and it would be good to match base mods so I like the opacity idea.

[mrvollger]

Hi @jrobinso,

It has been great using this! I have included a couple of comments below after using it on some data and playing around, and at the end I've suggested reframing the user docs to be more open to non-Fiber-seq data (with a draft).

Thanks again for your effort; this is really useful to us!

---

This might be better suited for another issue, but I noticed it while playing with this data. Setting different row heights can create very disproportionate amounts of white space between reads. e.g., this is row height 2 vs row height 3:

---

An awesome feature, maybe for the future, would be the ability to group reads by their molecular annotation at a position. E.g. see all the reads with a FIRE at base position X grouped together at the top.

---

Ideally, rename this menu to color by "Molecular Annotations (Ma)"

---

Ideally, rename this as well from Fiber-seq to Molecular Annotations.

---

Ideally, for batch script coloring, use:

colorBy MOLECULAR_ANNOTATION

---

Suggested update to the user docs:

Molecular annotations

Molecular annotations mark intervals along an individual sequenced molecule: a nucleosome, a footprint, a stretch of accessible chromatin, a bound protein, or any other region a tool has called on that read. They are the interval counterpart to base modifications. Where the MM/ML tags record a state at single bases, molecular annotation tags record a start, a length, and an optional quality for a segment of the read.

IGV can draw these annotations directly on each alignment, so you can see the state of every individual molecule rather than a pileup average. The format is described in the molecular annotation spec. Fiber-seq is the first data type to use the format and is the worked example on this page.

Requirements

A BAM or CRAM file whose reads carry molecular annotation tags:

• Molecular annotation tags: Ma (intervals) and Aq (qualities). The all-uppercase MA and AQ are also read to future-proof if the tags are formally adopted into the hts-spec.
• Legacy Fiber-seq tags: ns/nl (nucleosomes) and as/al/aq (MSPs), written by older fibertools versions.

Coordinates in the Ma tag are positions on the read, not the reference. IGV lifts them to reference coordinates using the alignment, so annotations follow the read across indels and are flipped correctly on reverse-strand alignments.

Turning it on

1. Load the file and navigate to a region with reads.
2. Right-click the alignment track and choose Color alignments by > Molecular Annotations (Ma).

The menu item appears only after IGV has loaded reads that carry these tags.

What you see

Each read is drawn in a pale color for its strand, with its annotations on top. Each annotation type gets its own color. Types with a quality score are drawn with opacity proportional to that score, so a faint patch is a low-confidence call and a solid patch is a high-confidence one.

Colors can be changed in View > Preferences > Base Mods, under Molecular annotation colors. Named types have their own entries; any other type uses the Other color.

Hover over or click a read to see the annotations at that position. Each line gives the type, the reference interval, the length, and the quality if the type carries one, for example:

nuc: 3081871-3082038 (168 bp)
msp: 47481338-47481485 (148 bp)
fire: 47481338-47481485 (148 bp), quality 243

Positions are 1-based and inclusive, on the reference.

As with base modification coloring, mismatched bases that are not covered by an annotation are shown in gray rather than in nucleotide colors, so they don't compete with the annotations. Small insertion markers (the purple I-beams) are not drawn; insertions large enough to be labeled with their size still are.

Example: Fiber-seq

Fiber-seq reads carry three annotation types written by fibertools:

Type	Color	Meaning
nuc	Gray	Nucleosome
msp	Purple	Methylation sensitive patch: a linker or accessible region between nucleosomes
fire	Red, opacity by quality	Fiber-seq Inferred Regulatory Element: an MSP called as a regulatory element, drawn over the MSP

On a typical read the gray nucleosomes and purple MSPs alternate along the molecule. Regulatory elements show up as red patches that line up across many reads at the same position, while the surrounding nucleosome positions vary from molecule to molecule. Because each row is a single molecule, you can see which reads have an element open and which do not, and compare that to the base modification calls on the same read by switching between this color mode and base modification coloring.

Sessions and batch scripts

The color mode is saved with the session. In a batch script, select it with:

colorBy MOLECULAR_ANNOTATION

Limitations

• Reads whose sequence was changed after they were annotated, for example by trimming, are drawn without annotations. IGV detects this from the read length recorded in the Ma tag.
• Reads with legacy tags and no stored sequence (SEQ of *, common for secondary alignments) are drawn without annotations.
• For hard-clipped alignments with legacy tags, such as some supplementary alignments, annotations may be misplaced. fibertools itself handles these tags the same way.
• Annotations are not drawn when supplementary alignments are linked into a single row.
• Annotation names (An tag) are not shown.
• Types with more than one quality value per annotation use the first value for opacity.

[jrobinso]

I added the "group by molecular annotation at base", also "sort by". One thing this brought to light, unrelated to this work, is that "Group by" works off the base you clicked over. "Sort by" works over the base at the center. This is something we might address but that's how it's been for some time. One thing I think we should change, the nucleosome color of 169,169,169 looks too much like the background alignment color. I think we should change this to something non-gray, gray is generally reserved for default or non-modified things.

…

On Thu, Sep 17, 2026 at 8:35 AM Mitchell Robert Vollger < ***@***.***> wrote: *mrvollger* left a comment (igvteam/igv#1851) <#1851 (comment)> Hi @jrobinso <https://github.com/jrobinso>, It has been great using this! I have included a couple of comments below after using it on some data and playing around, and at the end I've suggested reframing the user docs to be more open to non-Fiber-seq data (with a draft). Thanks again for your effort; this is really useful to us! ------------------------------ This might be better suited for another issue, but I noticed it while playing with this data. Setting different row heights can create very disproportionate amounts of white space between reads. e.g., this is row height 2 vs row height 3: Image: Image (view on web) <https://github.com/user-attachments/assets/6957d064-6442-4f9e-86fa-21e8bbfc6635> Image: Image (view on web) <https://github.com/user-attachments/assets/c6e6aa3a-2b0a-400e-aa50-023051df1abd> ------------------------------ An awesome feature, maybe for the future, would be the ability to group reads by their molecular annotation at a position. E.g. see all the reads with a FIRE at base position X grouped together at the top. ------------------------------ Ideally, rename this menu to color by "Molecular Annotations (Ma)" Image: Image (view on web) <https://github.com/user-attachments/assets/eb8faa6b-c176-4876-9cff-907c0b46711d> ------------------------------ Ideally, rename this as well from Fiber-seq to Molecular Annotations. Image: Image (view on web) <https://github.com/user-attachments/assets/df245522-b1dd-4943-9768-fcfa5bcaa84d> ------------------------------ Ideally, for batch script coloring, use: colorBy MOLECULAR_ANNOTATION ------------------------------ Suggested update to the user docs: Molecular annotations Molecular annotations mark intervals along an individual sequenced molecule: a nucleosome, a footprint, a stretch of accessible chromatin, a bound protein, or any other region a tool has called on that read. They are the interval counterpart to base modifications. Where the MM/ML tags record a state at single bases, molecular annotation tags record a start, a length, and an optional quality for a segment of the read. IGV can draw these annotations directly on each alignment, so you can see the state of every individual molecule rather than a pileup average. The format is described in the molecular annotation spec <https://github.com/fiberseq/Molecular-annotation-spec>. Fiber-seq <https://github.com/fiberseq/fibertools-rs> is the first data type to use the format and is the worked example on this page. Requirements A BAM or CRAM file whose reads carry molecular annotation tags: - *Molecular annotation tags:* Ma (intervals) and Aq (qualities). The all-uppercase MA and AQ are also read to future-proof if the tags are formally adopted into the hts-spec. - *Legacy Fiber-seq tags:* ns/nl (nucleosomes) and as/al/aq (MSPs), written by older fibertools versions. Coordinates in the Ma tag are positions on the read, not the reference. IGV lifts them to reference coordinates using the alignment, so annotations follow the read across indels and are flipped correctly on reverse-strand alignments. Turning it on 1. Load the file and navigate to a region with reads. 2. Right-click the alignment track and choose *Color alignments by > Molecular Annotations (Ma)*. The menu item appears only after IGV has loaded reads that carry these tags. What you see Each read is drawn in a pale color for its strand, with its annotations on top. Each annotation type gets its own color. Types with a quality score are drawn with opacity proportional to that score, so a faint patch is a low-confidence call and a solid patch is a high-confidence one. Colors can be changed in *View > Preferences > Base Mods*, under *Molecular annotation colors*. Named types have their own entries; any other type uses the *Other* color. Hover over or click a read to see the annotations at that position. Each line gives the type, the reference interval, the length, and the quality if the type carries one, for example: nuc: 3081871-3082038 (168 bp) msp: 47481338-47481485 (148 bp) fire: 47481338-47481485 (148 bp), quality 243 Positions are 1-based and inclusive, on the reference. As with base modification coloring, mismatched bases that are not covered by an annotation are shown in gray rather than in nucleotide colors, so they don't compete with the annotations. Small insertion markers (the purple I-beams) are not drawn; insertions large enough to be labeled with their size still are. Example: Fiber-seq Fiber-seq reads carry three annotation types written by fibertools: Type Color Meaning nuc Gray Nucleosome msp Purple Methylation sensitive patch: a linker or accessible region between nucleosomes fire Red, opacity by quality Fiber-seq Inferred Regulatory Element: an MSP called as a regulatory element, drawn over the MSP On a typical read the gray nucleosomes and purple MSPs alternate along the molecule. Regulatory elements show up as red patches that line up across many reads at the same position, while the surrounding nucleosome positions vary from molecule to molecule. Because each row is a single molecule, you can see which reads have an element open and which do not, and compare that to the base modification calls on the same read by switching between this color mode and *base modification* coloring. Sessions and batch scripts The color mode is saved with the session. In a batch script, select it with: colorBy MOLECULAR_ANNOTATION Limitations - Reads whose sequence was changed after they were annotated, for example by trimming, are drawn without annotations. IGV detects this from the read length recorded in the Ma tag. - Reads with legacy tags and no stored sequence (SEQ of *, common for secondary alignments) are drawn without annotations. - For hard-clipped alignments with legacy tags, such as some supplementary alignments, annotations may be misplaced. fibertools itself handles these tags the same way. - Annotations are not drawn when supplementary alignments are linked into a single row. - Annotation names (An tag) are not shown. - Types with more than one quality value per annotation use the first value for opacity. — Reply to this email directly, view it on GitHub <#1851?email_source=notifications&email_token=AAHD2HC7ZKKYS4A2F5KICXT5PQAEVA5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTKNZRG4YDMOBSGM22M4TFMFZW63VHNVSW45DJN5XKKZLWMVXHJLDGN5XXIZLSL5RWY2LDNM#issuecomment-5717068235>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAHD2HETLGXLWVWQ6UVKVST5PQAEVAVCNFSNUABDKJSXA33TNF2G64TZHMZTIMJWGU3TQO2JONZXKZJ3GUYDGMZTGY3TIOBQUF3AE> . Triage notifications, keep track of coding agent tasks and review pull requests on the go with GitHub Mobile for iOS <https://github.com/notifications/mobile/ios/AAHD2HGWRFXKTSRHWQVSFHL5PQAEVA5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTKNZRG4YDMOBSGM22M4TFMFZW63VHNVSW45DJN5XKKZLWMVXHJKTGN5XXIZLSL5UW64Y> and Android <https://github.com/notifications/mobile/android/AAHD2HDHAJBCXGLJP3PMHRL5PQAEVA5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTKNZRG4YDMOBSGM22M4TFMFZW63VHNVSW45DJN5XKKZLWMVXHJLTGN5XXIZLSL5QW4ZDSN5UWI>. Download it today! You are receiving this because you were mentioned.Message ID: <igvteam/igv/issues/1851/5717068235 ***@***.***>

[jrobinso]

@mrvollger Update - "Group by" now works off the base at the center of view, the center line, to be consistent with sort by.

I still think we should give nucleosome a non-gray color. It can be subtle, just not gray.

[jrobinso]

Another decision on colors. The MA coloring was coded as a generalization of base-mods. For base modifications strand is often important, so alignments are colored subtly by strand. If this is a distraction or too much information for the MA use case we can drop that.

[mrvollger]

Awesome, thanks!

Re the color. We can change the default color. Maybe a light tan? Trying to think of something most close to gray because nucleosome status in fiber-seq is similar to a default background, thus the original gray choice.

Re strand I think opacity or slightly different colors could work however since it's an interval do you think we could make the block have an arrow like shape as you do with supplement alignments to indicate direction, and just simple blocks when no strand is specified? If helpful I can make some mock data with strand info?

Thanks,
Mitchell