Implement ribbon worms

[Tom Goddard]

Some users have requested ribbon worms (tubes of varying radius), most recently Gabe Lander.

From: Gabriel Lander via ChimeraX-users <chimerax-users@…>
Subject: [chimerax-users] worm plots?
Date: October 3, 2023 at 3:01:58 PM PDT
To: "chimerax-users@…" <chimerax-users@…>
Reply-To: Gabriel Lander

Is it by any chance possible to do b-factor worm plots in ChimeraX yet? I recall this was going to take a lot of effort since the code for ribbon depiction would have to be overhauled, but hoping maybe there's been some progress.
If not I'll keep exporting from Chimera.
thanks,
-gabe

[Tom Goddard]

Eric will add attribute support in C++ atomic data structures.
Tom will add graphics rendering code.
Then Eric can add command support and render by attribute by gui.

[Tom Goddard]

From: James Lingford via ChimeraX-users <chimerax-users@…>
Subject: [chimerax-users] Feature question: "Worms" plots in "Render By Attribute"
Date: January 24, 2024 at 4:05:23 PM PST
To: chimerax-users@…
Reply-To: James Lingford <>

Dear ChimeraX team,

I was wondering if ChimeraX v1.7+ has the function for rendering attributes by "Worms"? For example, rendering B-factors by the thickness of the backbone.

I noticed that it's possible in legacy version of Chimera, which I have since installed and generated worm plots with: ​https://www.cgl.ucsf.edu/chimera/ImageGallery/framedpecworm.html

Is this doable in the latest ChimeraX versions, however?

Many thanks for any help you can provide,
James

--
James Lingford | Research Officer, Greening Lab
Department of Microbiology, Monash Biomedicine Discovery Institute
Monash University

[pett]

Added worm data-structure support to the C++ layer, so the ball is back in T.G.'s court for graphical depiction. There is a worm_radius Residue float attribute and a worm_ribbon Structure boolean attribute. For one day, I had a RIBBON_MODE_WORM enum value in the helix mode and strand mode Structure attributes, but decided that was too hacky and changed it to the worm_ribbon boolean.

[Tom Goddard]

I added worm ribbon rendering, enabled with a new "worm" option to the cartoon style command

cartoon style #1 worm true

Worm style can only be set at the structure level, so it is used for all ribbons in a structure. Currently there is no code to set the residue worm_radius attribute which sets the radius of the ribbon. The "coil" cartoon cross-section which is circular by default is used in worm style. Square cross-section worms are amusing.

I've attached a Python script that sets the worm radii according to the residue principal atom bfactor for testing.

[Tom Goddard]

ChimeraX Python script to set worm radii using bfactor.

[Tom Goddard]

Reassigning to Eric so he can make Render by Attribute able to set the worm radius.

[pett]

Okay, have added command support but not Render By Attribute support yet. To set the worm thickness you use the "cartoon byattribute" command which basically has the exact same syntax as "size byattribute" except no 'style' or 'average' keywords. "cartoon byattribute" also turns on the worm depiction. You can turn off the worm depiction with "~worm" or "worm off", and turn it back on (without changing thicknesses) with "worm" or "worm on".

[pett]

I guess we need to decide if we want the "worm/~worm" commands in addition to Tom's "cartoon style #1 worm true" command.

[goddard@…]

I think users will almost always use the Render by Attribute gui to make a worm depiction. So I don't see much need for the simple worm command. But how does the user deworm? ie how do they turn off the worm? How is the worm turned off in Chimera? We don't want that to be too hard. Also some of our presets may need improvement to turn off worm.

[Tom Goddard]

On Mar 6, 2024, at 4:56 PM, Eric Pettersen wrote:

It might be nice to have the ends of the worms come to a rounded end like in Chimera. Right now, they actually seem to "flare out" to a large flat end where the polygonal nature of the cross section is clearly visible.

--Eric

Hi Eric,

The worm flare at the ends is because the cubic spline between the last to residues is being extrapolated 30% beyond the end (exactly like our center line ribbon path is extrapolated, using the same code in fact). If you are looking at bfactors the terminal residues often have increasing b-factors because the tails of the structure and disordered and the depositor build residues out as far as they could until they could not resolve the residues. So the flaring is just showing the data. Our caps on ribbon ends are alwayss flat. I'm not sure what the Chimera worm caps look like. I guess the worm radius could be artificially decreased to 0 to make it look spherical at the end. That doesn't sound like a good idea to me, seems better to follow the data.

Tom

[Elaine Meng]

Weell, by definition "extrapolation" is not following the data, it is making the worm even bigger than the terminal data value would imply (assuming the next-to-last data value is smaller than that).

We had discussed the wholeworms on/off issue and that it would be separate toggle similar to what you said, but not within "cartoon style" since it would be incompatible with all other "cartoon style" options.

Elaine

[pett]

Having the flat end makes it look like the ribbon was cut through by some kind of clipping plane. AFAIK, none of our other ribbon depictions come to an abrupt end like that. Having it taper to the end would also eliminate the faceting problem.

[Tom Goddard]

The terminal residue of any ChimeraX ribbon depiction all end in a flat cap. I'm perplexed why you think otherwise. A typical ribbon ends with a coil with exactly the same kind of cap, but it is true that the coil has a small radius (default 0.2 A I think) so perhaps you never noticed.

[pett]

Probably why I never noticed the faceting either.

[Tom Goddard]

I don't realy want to get into a pedantic spat about what "following the data" means. The actual ribbon spline extends beyond the last C-alpha atom by 30% of the inter-residue spacing and is extrapolated exactly in the same way as the worm. We could have chosen and still could choose not to extend ribbons beyond the last C-alpha atom position and that would avoid the suggestion that some extra data of the next missing residue was known. I think our current behavior is better though.

[Tom Goddard]

One additional detail. If you hide some residues in the ribbon then the worm radius and the center-line path of the ribbon is using the hidden residues. So it is only where the residue coordinates are missing (e.g. at the ends) that some liberty is taken to avoid showing a half residue.

[pett]

Reworked the command set. Added "cartoon byattribute on/off" subcommands and withdrew the "worm" option from "cartoon style". Added worm/~worm aliases pointing to "cartoon byattribute on/off".

[Tom Goddard]

Another technical note -- the faceted appearance of the end cap is because the coil by default has 12 sides, a parameter that can be set to give a smoother appearance

cartoon style #1 sides 24

For unknown reasons the value can only be <= 24, though I am sure that can trivially be fixed to not have a maximum, or have a higher maximum.

One worm detail I considered was that worm should have its own cross-section (and sides) instead of using the coil cross-section. This adds a fair bit of complexity in the code and it is not clear how the current cartoon style command could handle it since it does not offer a way to specify which cross section (helix, strand, coil) you are trying to change other than to list some residues of that type. So I opted to keep it simple.

[pett]

Replying to goddard@…:

I think users will almost always use the Render by Attribute gui to make a worm depiction. So I don't see much need for the simple worm command. But how does the user deworm? ie how do they turn off the worm? How is the worm turned off in Chimera? We don't want that to be too hard. Also some of our presets may need improvement to turn off worm.

Well, the command is "cartoon byattr off" or "~worm". In Chimera's Render By Attribute, there was an explicit "deworm" button on the interface and I imagine the ChimeraX version will have the same.

[Elaine Meng]

For our cylinders (tube-helix) cartoon preset we upped the number of cartoon sides to 24 since the faceting was more obvious in that case. I guess Conrad decided 24 would be plenty when he didn't have worms in mind yet, and perhaps thinking that high numbers would give so many triangles it would slow ChimeraX down. Increasing the max sounds like a good idea, but I don't have a good feel for what the limit should be, or whether we should just unlimit it entirely and let users find out for themselves!

Maybe we could add a sides option to "cartoon byattribute" with default 24 unless you think that would be too redundant. It already appears in two commands, "cartoon style" and "graphics quality."

[Tom Goddard]

I don't think anyone will find the sides attribute so we of course want the defaults to work well. The cartoon code "sides" actually is for the oval cross section, not for helix, strand, coil. So cartoon byattribute changes it to 24 then it will be 24 for helix and coil since those use oval cross-section. It is slower to render but probably will not be noticed. Slightly more troubling is we generally don't have commands change default values like that unless the user requests it.

[Elaine Meng]

The other two cartoon presets put the sides back to 12, at least.  I don't know how much use these three cartoon presets are getting, but as you (Tom) said, Eric will need to add turning off worm to each of them.

[pett]

"Worms" tab in Render By Attribute tool as of tomorrow's build.