RFE: label residues with color-coded grid of column prevalences from associated MSA

[Elaine Meng]

Idea is to label residues with color-coded grids like we already have for deep mutational scanning (see mutationscores command) except that except for scores for each residue type, coloring is by prevalence of that residue type at that position in an associated multiple sequence alignment (MSA). This is basically the information in the associated column of a Profile Grid. Maybe it could also work for sequence alignments open in the regular Sequence Viewer as well.

My initial thought is that maybe it could be implemented as a "sequence label" commmand partially analogous to "mutationscores label" (some options would be the same, some different due to different situation). I haven't thought out the ramifications of each option, however, so depends what you guys think.

[Tom Goddard]

Here is the command syntax for the "mutationscores label" command

mutationscores label residues scoreName [mutationSet a text string] [range range] [palette a colormap] [noDataColor a color] [height a number] [offset offset] [onTop true or false]

Arguments scoreName, mutationSet, and noDataColor would not apply for sequence prevalence.

While there should be a new command for the sequence alignment case, I think I will also want the mutationscores label command to be able to handle this "score" using some special scoreName (e.g. name of the alignment). I think it could be interesting to due queries on actual DMS scores that combine sequence prevalence. For instance which mutations are gain-of-function and also observed above 20% in this deep sequence alignment?

[Eric Pettersen]

I note that "mutationscores label" reaches into the internals of the normal label machinery to get its image displayed as a label. Given that a "sequence label" command would need to do the same thing, perhaps some kind of public API should be created for this?

[Tom Goddard]

Yeah, I agree there should be an public API to provide an arbitrary image for a label. Currently the mutationscores label command monkey patches method ObjectLabel._label_image(). One idea is to add an ObjectLabel.label_image = None and clients can set label_image to a method and the current _label_image() will call that method if it is not None. I'd be a bit concerned how this works with session saving. The mutationscores label code does some fancy footwork in session restore to restore the monkey patches. It would be better if a public API made it less likely for you to shoot yourself in the foot on session restore.

[Eric Pettersen]

Sounds good. I'd add one slight refinement in that if the called function returns None then it can't label this kind of object and the normal label should be shown. I'd be willing to take this on myself, but I would need some way of creating mutationscores labels for testing purposes.

[Tom Goddard]

Here is a ChimeraX 1.11 session with mutation scores for testing mutation labels.

[Tom Goddard]

I attached a ChimeraX 1.11 session with mutation scores to test labeling. Here is a labeling command that shows the labels

mutation label :58-73 SE_ph65

[Eric Pettersen]

So why a function instead of an actual image? I'm guessing you must have had some kind of motivation for suggesting a function. If it was an image, it would make session saving 1000x easier...

[Tom Goddard]

I'm not sure why I had mutation labels replace the _label_image() method. That was added in 2024. My guess is that I wanted to keep this hackery in the mutation code rather than try to provide a new facility for supporting images in labels. Looking at the what the mutation _label_image method does (mutation_scores/src/ms_label.py) shows it just provides a precomputed RGBA image array. So it seems if the label code were enhanced so it managed custom rgba arrays for labels the mutation code could work with that.

[Eric Pettersen]

So I revamped the label / mutation label codes to use a public API for providing custom label images and pushed that out.

Now that I'm looking to implement analogous profile-grid labels, I'm seeing another private API that I need that is used heavily in other parts of the code, namely _use_full_range and _colormap_with_range from chimerax.surface.colorvol. In addition to "mutationscores label", it's used in "color radial/height/cylindrical/byattr" and "size byattr". Maybe we should make these APIs public as well. Any reason they're private?

[Tom Goddard]

Yeah, you probably even missed some uses of colormap_with_range. The surface/colorvol.py is the code that defines those private methods. Probably it should be public. The reason it is not is because it was intended only for that surface module use. More uses came along and whether the code is right for those uses is iffy. So the stuff did not become public because I did not put the effort in to figure out if the API was well designed for other uses. Put more strongly, I think these routines are possibly half-baked.

[Eric Pettersen]

Profile Grid labels available through "sequence grid label" command or Profile Grid's "Label Residues..." context menu entry.