Simplify labeling contacting residues

[goddard@…]

The following bug report has been submitted:
Platform:        macOS-12.3.1-arm64-arm-64bit
ChimeraX Version: 1.4.dev202204220707 (2022-04-22 07:07:55 UTC)
Description
I want to show contacting residues between chain D and other atoms and label them for a tutorial I am giving at Stanford on Monday.  I decided I can't do it because it is too complex and intimidating.  This should be an easy task.  Maybe I haven't found the best way.

Here is how I think this common task could be greatly simplified.

The two hard steps are selecting only the contacting residues, then labeling them.  Here is what I have now for selecting them

select (/D :<3.2 & ~/D) | ((~/D) :<3.2 & /D)

How about instead we add a subcommand

select contacts /D range 3.2

and also add this option to the Zone Selection panel.

For labeling I want to show the residue name and number but not the chain id.  Currently the Actions / Label / Residues menu can only show the labels with chain id.  It would be good to have the menu provide versions without the cluttering chain identifiers.   I would probably just replace the current versions dropping the chain id, but both could be provided if desired.  Currently the simple

label sel residues

makes the labels without chain identifiers.

Log:
UCSF ChimeraX version: 1.4.dev202204220707 (2022-04-22)  
© 2016-2022 Regents of the University of California. All rights reserved.  
How to cite UCSF ChimeraX  

> open 7sth format mmcif fromDatabase pdb

7sth title:  
Full-length insulin receptor bound with unsaturated insulin WT (2 insulin
bound) symmetric conformation [more info...]  
  
Chain information for 7sth #1  
---  
Chain | Description | UniProt  
A B | Insulin receptor | INSR_MOUSE  
C D | Insulin | INS_HUMAN  
  

> color bychain

> select (/D :<3.2 & ~/D) | ((~/D) :<3.2 & /D)

149 atoms, 139 bonds, 17 residues, 1 model selected  

> label sel text "{0.name} {0.number}"

> show sel




OpenGL version: 4.1 Metal - 76.3
OpenGL renderer: Apple M1 Max
OpenGL vendor: Apple

Python: 3.9.11
Locale: UTF-8
Qt version: PyQt6 6.3.0, Qt 6.3.0
Qt runtime version: 6.3.0
Qt platform: cocoa
Hardware:

    Hardware Overview:

      Model Name: MacBook Pro
      Model Identifier: MacBookPro18,2
      Chip: Apple M1 Max
      Total Number of Cores: 10 (8 performance and 2 efficiency)
      Memory: 32 GB
      System Firmware Version: 7459.101.3
      OS Loader Version: 7459.101.3

Software:

    System Software Overview:

      System Version: macOS 12.3.1 (21E258)
      Kernel Version: Darwin 21.4.0
      Time since boot: 18 days 11:02

Graphics/Displays:

    Apple M1 Max:

      Chipset Model: Apple M1 Max
      Type: GPU
      Bus: Built-In
      Total Number of Cores: 32
      Vendor: Apple (0x106b)
      Metal Family: Supported, Metal GPUFamily Apple 7
      Displays:
        Color LCD:
          Display Type: Built-in Liquid Retina XDR Display
          Resolution: 3456 x 2234 Retina
          Main Display: Yes
          Mirror: Off
          Online: Yes
          Automatically Adjust Brightness: No
          Connection Type: Internal


Installed Packages:
    alabaster: 0.7.12
    appdirs: 1.4.4
    appnope: 0.1.3
    Babel: 2.10.1
    backcall: 0.2.0
    blockdiag: 3.0.0
    certifi: 2021.10.8
    charset-normalizer: 2.0.12
    ChimeraX-AddCharge: 1.2.3
    ChimeraX-AddH: 2.1.11
    ChimeraX-AlignmentAlgorithms: 2.0
    ChimeraX-AlignmentHdrs: 3.2.1
    ChimeraX-AlignmentMatrices: 2.0
    ChimeraX-Alignments: 2.4.2
    ChimeraX-AlphaFold: 1.0
    ChimeraX-AltlocExplorer: 1.0.2
    ChimeraX-AmberInfo: 1.0
    ChimeraX-Arrays: 1.0
    ChimeraX-Atomic: 1.38.1
    ChimeraX-AtomicLibrary: 7.0
    ChimeraX-AtomSearch: 2.0.1
    ChimeraX-AxesPlanes: 2.1
    ChimeraX-BasicActions: 1.1
    ChimeraX-BILD: 1.0
    ChimeraX-BlastProtein: 2.1.1
    ChimeraX-BondRot: 2.0
    ChimeraX-BugReporter: 1.0
    ChimeraX-BuildStructure: 2.7
    ChimeraX-Bumps: 1.0
    ChimeraX-BundleBuilder: 1.1
    ChimeraX-ButtonPanel: 1.0
    ChimeraX-CageBuilder: 1.0
    ChimeraX-CellPack: 1.0
    ChimeraX-Centroids: 1.2
    ChimeraX-ChemGroup: 2.0
    ChimeraX-Clashes: 2.2.3
    ChimeraX-ColorActions: 1.0
    ChimeraX-ColorGlobe: 1.0
    ChimeraX-ColorKey: 1.5.1
    ChimeraX-CommandLine: 1.2.3
    ChimeraX-ConnectStructure: 2.0.1
    ChimeraX-Contacts: 1.0
    ChimeraX-Core: 1.4.dev202204220707
    ChimeraX-CoreFormats: 1.1
    ChimeraX-coulombic: 1.3.2
    ChimeraX-Crosslinks: 1.0
    ChimeraX-Crystal: 1.0
    ChimeraX-CrystalContacts: 1.0
    ChimeraX-DataFormats: 1.2.2
    ChimeraX-Dicom: 1.1
    ChimeraX-DistMonitor: 1.1.5
    ChimeraX-Dssp: 2.0
    ChimeraX-ExperimentalCommands: 1.0
    ChimeraX-FileHistory: 1.0
    ChimeraX-FunctionKey: 1.0
    ChimeraX-Geometry: 1.2
    ChimeraX-gltf: 1.0
    ChimeraX-Graphics: 1.1
    ChimeraX-Hbonds: 2.1.2
    ChimeraX-Help: 1.2
    ChimeraX-HKCage: 1.3
    ChimeraX-IHM: 1.1
    ChimeraX-ImageFormats: 1.2
    ChimeraX-IMOD: 1.0
    ChimeraX-IO: 1.0.1
    ChimeraX-ItemsInspection: 1.0
    ChimeraX-Label: 1.1
    ChimeraX-ListInfo: 1.1.1
    ChimeraX-Log: 1.1.5
    ChimeraX-LookingGlass: 1.1
    ChimeraX-Maestro: 1.8.1
    ChimeraX-Map: 1.1
    ChimeraX-MapData: 2.0
    ChimeraX-MapEraser: 1.0
    ChimeraX-MapFilter: 2.0
    ChimeraX-MapFit: 2.0
    ChimeraX-MapSeries: 2.1
    ChimeraX-Markers: 1.0
    ChimeraX-Mask: 1.0
    ChimeraX-MatchMaker: 2.0.6
    ChimeraX-MDcrds: 2.6
    ChimeraX-MedicalToolbar: 1.0.1
    ChimeraX-Meeting: 1.0
    ChimeraX-MLP: 1.1
    ChimeraX-mmCIF: 2.7
    ChimeraX-MMTF: 2.1
    ChimeraX-Modeller: 1.5.5
    ChimeraX-ModelPanel: 1.3.2
    ChimeraX-ModelSeries: 1.0
    ChimeraX-Mol2: 2.0
    ChimeraX-Morph: 1.0
    ChimeraX-MouseModes: 1.1
    ChimeraX-Movie: 1.0
    ChimeraX-Neuron: 1.0
    ChimeraX-Nucleotides: 2.0.2
    ChimeraX-OpenCommand: 1.9
    ChimeraX-PDB: 2.6.6
    ChimeraX-PDBBio: 1.0
    ChimeraX-PDBLibrary: 1.0.2
    ChimeraX-PDBMatrices: 1.0
    ChimeraX-PickBlobs: 1.0
    ChimeraX-Positions: 1.0
    ChimeraX-PresetMgr: 1.1
    ChimeraX-PubChem: 2.1
    ChimeraX-ReadPbonds: 1.0.1
    ChimeraX-Registration: 1.1
    ChimeraX-RemoteControl: 1.0
    ChimeraX-ResidueFit: 1.0
    ChimeraX-RestServer: 1.1
    ChimeraX-RNALayout: 1.0
    ChimeraX-RotamerLibMgr: 2.0.1
    ChimeraX-RotamerLibsDunbrack: 2.0
    ChimeraX-RotamerLibsDynameomics: 2.0
    ChimeraX-RotamerLibsRichardson: 2.0
    ChimeraX-SaveCommand: 1.5
    ChimeraX-SchemeMgr: 1.0
    ChimeraX-SDF: 2.0
    ChimeraX-Segger: 1.0
    ChimeraX-Segment: 1.0
    ChimeraX-SelInspector: 1.0
    ChimeraX-SeqView: 2.6
    ChimeraX-Shape: 1.0.1
    ChimeraX-Shell: 1.0
    ChimeraX-Shortcuts: 1.1
    ChimeraX-ShowAttr: 1.0
    ChimeraX-ShowSequences: 1.0
    ChimeraX-SideView: 1.0
    ChimeraX-Smiles: 2.1
    ChimeraX-SmoothLines: 1.0
    ChimeraX-SpaceNavigator: 1.0
    ChimeraX-StdCommands: 1.8
    ChimeraX-STL: 1.0
    ChimeraX-Storm: 1.0
    ChimeraX-StructMeasure: 1.0.1
    ChimeraX-Struts: 1.0.1
    ChimeraX-Surface: 1.0
    ChimeraX-SwapAA: 2.0
    ChimeraX-SwapRes: 2.1.1
    ChimeraX-TapeMeasure: 1.0
    ChimeraX-Test: 1.0
    ChimeraX-Toolbar: 1.1
    ChimeraX-ToolshedUtils: 1.2.1
    ChimeraX-Tug: 1.0
    ChimeraX-UI: 1.16.5
    ChimeraX-uniprot: 2.2
    ChimeraX-UnitCell: 1.0
    ChimeraX-ViewDockX: 1.1.2
    ChimeraX-VIPERdb: 1.0
    ChimeraX-Vive: 1.1
    ChimeraX-VolumeMenu: 1.0
    ChimeraX-VTK: 1.0
    ChimeraX-WavefrontOBJ: 1.0
    ChimeraX-WebCam: 1.0
    ChimeraX-WebServices: 1.1.0
    ChimeraX-Zone: 1.0
    colorama: 0.4.4
    cxservices: 1.2
    cycler: 0.11.0
    Cython: 0.29.26
    debugpy: 1.6.0
    decorator: 5.1.1
    docutils: 0.17.1
    entrypoints: 0.4
    filelock: 3.4.2
    fonttools: 4.33.2
    funcparserlib: 1.0.0a1
    grako: 3.16.5
    html2text: 2020.1.16
    idna: 3.3
    ihm: 0.27
    imagesize: 1.3.0
    ipykernel: 6.6.1
    ipython: 7.31.1
    ipython-genutils: 0.2.0
    jedi: 0.18.1
    Jinja2: 3.0.3
    jupyter-client: 7.1.0
    jupyter-core: 4.10.0
    kiwisolver: 1.4.2
    line-profiler: 3.4.0
    lxml: 4.7.1
    lz4: 3.1.10
    MarkupSafe: 2.1.1
    matplotlib: 3.5.1
    matplotlib-inline: 0.1.3
    msgpack: 1.0.3
    nest-asyncio: 1.5.5
    networkx: 2.6.3
    numpy: 1.22.1
    openvr: 1.16.802
    packaging: 21.0
    ParmEd: 3.4.3
    parso: 0.8.3
    pexpect: 4.8.0
    pickleshare: 0.7.5
    Pillow: 9.0.1
    pip: 21.3.1
    pkginfo: 1.8.2
    prompt-toolkit: 3.0.29
    psutil: 5.9.0
    ptyprocess: 0.7.0
    pycollada: 0.7.2
    pydicom: 2.2.2
    Pygments: 2.11.2
    PyOpenGL: 3.1.5
    PyOpenGL-accelerate: 3.1.5
    pyparsing: 3.0.8
    PyQt6: 6.3.0
    PyQt6-Qt6: 6.3.0
    PyQt6-sip: 13.3.1
    PyQt6-WebEngine: 6.3.0
    PyQt6-WebEngine-Qt6: 6.3.0
    python-dateutil: 2.8.2
    pytz: 2022.1
    pyzmq: 22.3.0
    qtconsole: 5.3.0
    QtPy: 2.0.1
    requests: 2.27.1
    scipy: 1.7.3
    setuptools: 59.8.0
    six: 1.16.0
    snowballstemmer: 2.2.0
    sortedcontainers: 2.4.0
    Sphinx: 4.3.2
    sphinx-autodoc-typehints: 1.15.2
    sphinxcontrib-applehelp: 1.0.2
    sphinxcontrib-blockdiag: 3.0.0
    sphinxcontrib-devhelp: 1.0.2
    sphinxcontrib-htmlhelp: 2.0.0
    sphinxcontrib-jsmath: 1.0.1
    sphinxcontrib-qthelp: 1.0.3
    sphinxcontrib-serializinghtml: 1.1.5
    suds-community: 1.0.0
    tifffile: 2021.11.2
    tinyarray: 1.2.4
    tornado: 6.1
    traitlets: 5.1.1
    urllib3: 1.26.9
    wcwidth: 0.2.5
    webcolors: 1.11.1
    wheel: 0.37.1
    wheel-filename: 1.3.0

[pett]

Hi Tom,

So you are aware that there is a "contacts" command, and a Contacts tool under Structure Analysis? The rough equivalent of your suggested "select contacts /D range 3.2" command would be:

contacts /D restrict ~/D sel true make false

The "make false" is to suppress showing pseudobonds between the contacts, assuming that's what you actually want. There are a lot more options to the command, such as saving to the log or file.

I could certainly add a few more entries to Actions→Label→Residues that suppress chain IDs.

--Eric

[pett]

Also, the "restrict ~/D" in the command I mentioned could instead be "intraMol false".

[Tom Goddard]

It did not occur to me that the contacts command could do this. This is a very common need and it will be very hard for users to find this way of doing it. So I still feel that the Select Zone panel should be improved to enable it, and a select subcommand would also be helpful. And an easier method to do the most common kind of residue label display (residue name and number) would be desirable.

This ticket was not because I could not do the task -- I can do it easily since I know how to type very exotic commands. It is about allowing users to do it in a simple way.

[Elaine Meng]

There is also a Contacts tool (GUI) with all these options. Hopefully tools in the Tools menu are not hard to find.

[pett]

Yes, I am aware that you personally can do the task -- I asked because you seemed to have overlooked a reasonably simple command to carry out the task instead of the exotic alternative you resorted to.

At any rate, I'm perfectly willing to put a "Contacts" button on the zone panel for the users who wandered to that panel in search of that capability instead of finding the Contacts tool. It will also give them access to a much larger set of capabilities, such as showing pseudobonds, saving contacts to a file, etc.

I'm not a fan of a new subcommand. A user may also want to select hydrogen-bonding residues. Should that be a selection subcommand instead of part of the hbonds command? Perhaps labeling contacts should be a subcommand of the label command? It just seems like poor design to have a very limited subcommand along side a fully functional standalone command. Some users will think that the subcommand is all that ChimeraX can do vis a vis contacts and may miss the full featured command entirely.

And like I said before, also perfectly happy to add more options to the Actions→Label→Residue menu.

[goddard@…]

I tried the Contacts GUI as a way to show interfaces.  This is way too complex given what I want to do -- show all residues with 3.5 Angstroms of each other at an interface (between selected and unselected residues say).  It took minutes trying to make sense of this very complex panel, and I am an expert at it.  There is no distance threshold since it uses more complex criteria.

It is ok if you don't want to work on this. Presenting live ChimeraX tutorials I never present this basic capability to show interface residues because its complexity gives the wrong impression of ChimeraX.  So I think it could get a lot more use if simpler controls to show interface residues were available.  We have the zone selection command syntax which is relatively simple and the Select Zone GUI is very simple, but they don't handle the most common need of symmetrically selecting interacting residues.

[Elaine Meng]

That setting  is right at the top of the Contacts dialog.  Just choose the second option (center-center distance) as the criterion instead of the first option (VDW overlap).

[pett]

In email, the following plan was agreed upon:

(1) Improve the Contacts/Clashes GUI for clarity

(2) Change the Select Zone dialog to have a tabbed interface. One tab (Zone?) would be exactly what's there now. The other tab (Contacts) would show the Contacts GUI having only the Interaction Parameters section and not the Treatment of Results, Write Information, or Frequency of Checking sections. There would also be a button for showing the full Contacts tool. Perhaps the Select menu entry would be changed to "Zone/Contacts..."

(3) Add additional entries to the Actions→Label→Residues menu for labels without chain IDs

[pett]

Did #1 and pushed the changes. Elaine, let me know what you think once its in the build.

[pett]

Okay, #2 implemented and pushed too. So just the residue labeling options left.

[pett]

Refined #1 and #2 based on feedback from Elaine

[pett]

Added no-chain variants for the Name and 1-Letter Code combo entries of the residue-naming menu

[Tom Goddard]

All those changes are very helpful. I tried them on 2VAA trying to find contacts between chains A and B, or between chains A and P.

I think this operation of selecting interacting residues is one of the most common needs of every researcher looking at atomic models and it still involves studying a lot of options. It took me several minutes studying the gui to get what I wanted. Here is the level of simplicity I think would be desirable in command form and what would be nice in equivalent gui form

select contacts /A with /B distance 3.5

Here are some of the complexities of the current Zone/Contacts gui that made it much harder for me. First I decide VDW vs strict distance. Then the "limit by selection" menu has 4 choices. In my example I first tried "at least one end selected" with /B selected -- wrong choice since that gave intra-B contacts, so I then tried exactly one end selected -- again wrong choice because it turned out their were waters in chain B that did not get selected when I used the log chain table "B" link so it curiously selected all the B residues interacting with B waters (took a while to figure this out since waters were not shown), so finally I homed in on "between selection and atom spec..." requiring me to know typed atom spec syntax. Then it only selected the contacting atoms, not whole residues so I had to use uparrow key. These steps were a difficult translation of my thought to select contacting residues between A and B.

I think a command like the one above would be a worthwhile addition. The current gui generated this command

contacts sel restrict /A distanceOnly 4.0 select true makePseudobonds false

And I think a simpler GUI with perhaps two menus and a distance would allow many more researchers to figure out how to do this task. The menus would allow choosing a chain id, "selected residues", and each ligand. The current GUI and contacts command is of course very useful and this command and gui would augment those to allow doing the common case in a very simple way.

[pett]

Aren’t you actually interested in some variant of the ‘interfaces’ command rather than ‘contacts’ per se?



interfaces select  atom-spec1 <applewebdata://48D71F63-B052-48A2-A9A6-F75CFF6AA221/atomspec.html>  contacting  atom-spec2 <applewebdata://48D71F63-B052-48A2-A9A6-F75CFF6AA221/atomspec.html>  [ bothSides  true | false ] [ probeRadius  rad ] [ areaCutoff  interface-area ] [ interfaceResidueAreaCutoff  res-area ]

The interfaces select command selects <applewebdata://48D71F63-B052-48A2-A9A6-F75CFF6AA221/selection.html> interface residues based on the buried area between chains in atom-spec1 <applewebdata://48D71F63-B052-48A2-A9A6-F75CFF6AA221/atomspec.html> and atom-spec2 <applewebdata://48D71F63-B052-48A2-A9A6-F75CFF6AA221/atomspec.html>. Only chain-chain contacts that bury at least the areaCutoff value are counted as interfaces, and only residues with at least the interfaceResidueAreaCutoff value buried are considered to be interface residues (same defaults as above). The bothSides option indicates whether to select interface residues from both atom-spec1 <applewebdata://48D71F63-B052-48A2-A9A6-F75CFF6AA221/atomspec.html> and atom-spec2 <applewebdata://48D71F63-B052-48A2-A9A6-F75CFF6AA221/atomspec.html> (if true) or from atom-spec1 <applewebdata://48D71F63-B052-48A2-A9A6-F75CFF6AA221/atomspec.html> only (if false, default). For a similar calculation but without grouping residues by chain, see measure buriedarea <applewebdata://48D71F63-B052-48A2-A9A6-F75CFF6AA221/measure.html#buriedarea>.

[Elaine Meng]

I could imagine designing a different GUI, but as for a command, the distance-based residue selection could be accomplished simply  with:

select sel :<3.5

(or whatever distance you wanted instead of 3.5 A)

[Tom Goddard]

The "interface select" command is related but it uses the more complicated criteria of buried solvent accessible area. This ticket is about having a way to use the simple distance criteria for showing interface residues that does not intimidate new users when I give tutorials. I feel all our current methods are more complex than everything I show in tutorials and would hurt our effort to attract new users if I showed it. Also I suspect a simple gui and command would get more use than contacts, select zone, and interfaces tools and commands combined.

[Tom Goddard]

"select sel :<3.5" leaves all of the original selection selected. This ticket is about selecting just the residues on both sides of the interface that are in contact so they can be shown as stick, colored, labeled.

[Elaine Meng]

If you don't care about the niceties of VDW overlap, might as well jettison the "Contacts" tab.  Instead simply add one option to the Zone dialog for specifying the second set of atoms, e.g. something like

[x] Restrict to [some kind of menu(s) or other way to specify a second set of atoms]

...where you could use other words, e.g. "limit selection to" or "limit zone to" or "only consider atoms in"

The command is not too hard for us to construct (the people you are targeting would only use the GUI anyway).  For example, if somebody chooses chain B from that menu:

select ((sel & /B :<4) | (/B & sel :<4))

If atom-based instead of residue-based use @< instead of :<, and if you don't want to include nonpolymer stuff, that can also be arranged:

select ((sel & /B :<4) | (/B & sel :<4)) & ::polymer_type>0

If you don't want to make the decision for the user about the latter, could be another option, say something like:

[x] Include only protein/nucleic 
- OR -
[x] Include heteroresidues
- OR -
[x] Ignore water

[pett]

It seems to me that you want the exact capability that the interfaces command gives you -- finding inter-chain contacts -- but just with a simpler criteria. You never say why you want to use this simpler criteria instead of the more sophisticated one that interfaces already supports, but I'm supposing there's a good reason. At any rate, I feel that the interfaces command should be enhanced to support this alternative criteria rather than adding yet a third command that finds contacts.

Here's my plan for the 1.4 release: in the "Select Contacts" tab, have two subtabs: "Chain" and "Atomic" ("Chain" showing by default). The contents of the Atomic tab would be same as they are now. The Chain tab would have two chain-selection lists and a "criteria" area. That area would have a choice between the buried area criteria and a simple distance criteria. In the long term that tab would issue an interfaces command, but in the short term the distance criteria choice would issue a fairly complex select command.

[goddard@…]

I think this should not go in the 1.4 release.  It is not urgent and it will likely require use and refinement to make it as nice as possible.

I think a separate "select contacts" command is good and desirable.  I do not put high importance on trying to combine a lot of complex ways to do similar things all under one umbrella.  For the same reason I am not too keen on the separate tabs of the select contacts gui, and think maybe two or 3 separate guis would be easier and function better.  Already with the two tabs it has made the simple case of Select Zone uglier and more intimidating with that panel now being much bigger than it used to be, and making the user wonder if that other tab is options they need to set.

[goddard@…]

Correction "I do not put high importance on combining..."

[pett]

Along the lines of what I suggested, I broke the Contacts tab out into its own dialog (Select→Contacts) with buried-surface and distance criteria alternatives. Doing it this way does make it easy to see that the default buried-surface criteria finds a lot more contacts that a 3.5 angstrom distance criteria.

This is only on the 1.5 / daily build branch.