Selection label examples #5

Simard302 · 2024-06-10T14:05:39Z

Overview

This PR creates 2 new examples for creating labels based on selections.

Changes made

Created selection example "add_label_to_selection_whole"
- This examples shows you how to add a label to a grouping of atoms based on a selection
Created selection example "add_labels_to_selection_atoms"
- This example shows you how to add a label to singular atoms (in this cased Alpha Carbon) based on a selection

How to test

Ensure the selection is visible

Specific review requests

For each of the examples:

Are there enough comments to sufficiently describe the process?
Are the comments accurately describing the process?
Are there any anti-patterns in the examples?
Can the examples be more efficient?

papillot

This ended-up being quite complex, not because of the labels per se, but more because of the way StructureSelection are laid out from the Query and Loci are defined from units.

I think there is probably an antipattern with the add_labels_to_selection_atoms example because we are trying to create on representation for each label and that makes 140+ representations in one go. There is a noticeable pause in the rendering.
It would be better to use a way to create the label that's more efficient and would serve as "The Way (™️)"

The add_label_to_selection_whole is working kind of by chance: the Query.generator.chains construct creates a grouping of the matches by chain id. Fortunately, this is the same mapping as when we use the label_asym_id property.
But this is not the case if we'd use the auth_asym_id property. In this case, we'd have 3-4 labels per "chain". Probably the best, in that case, is to use a groupBy callback with a Query.generators.atoms (not Query.generators.chains because this overwrites whatever groupBy property there is).
I guess such an example would be actually more generic.

papillot · 2024-06-10T17:44:32Z

representation/transparency_using_selection/src/index.ts

@@ -31,7 +31,7 @@ async function init() {
    // Create a selection for chains A and B

        // A query defines the logic to select elements based on a predicate.
-        // The predicate is executed from a generator which updates the current element (here, an atom)
+        // The predicate is executed from a generator which updates the current element (here, a chain)


I do think it's an atom that's returned as the argument for the predicate, but that we are iterating only through the 1st one in each chain

From the code in structure/query/queries/generators the chainTest is executed with the element corresponding to the chainSegment.start of each chain segment.

Suggestion:
The predicate is executed from a generator that iterates over the structure hierarchy (chains, then residues, then atoms). At each iteration, the query context that is passed, is updated.
The chainTest predicate is executed once per chain. The element property represents the atom at the start of the current chain.
If the predicates return true, the entire chain segment is added to the selection.

papillot · 2024-06-11T12:43:52Z

selection/add_labels_to_selection_atoms/src/index.ts

+        const ctx = new QueryContext(struct);
+        const selection = query(ctx);
+
+    // A StructureSelection is a Singleton if each iteration only adds a single element (atom)


"is a Singleton" is not correct. Notice that the type is StructureSelection.Singletons (plural)
Suggestion:
// A StructureSelection is made of Singletons if each iteration only...

papillot · 2024-06-11T13:06:23Z

selection/add_labels_to_selection_atoms/src/index.ts

+        // The predicate is executed from a generator which updates the current element (here, a chain and an atom)
+        // in the query context, at each iteration. The predicate returns true if the element should be selected.


The predicate is executed from a generator that iterates over the structure hierarchy (chains, then residues, then atoms) and groups matches by residue. At each iteration, the query context that is passed, is updated.
The chainTest predicate is executed once per chain. The element property represents the atom at the start of the current chain.
The atomTest predicate is executed for each atom in the structure that passes the chainTest.
If both predicates return true, the atom is added to the selection.

papillot · 2024-06-11T13:08:24Z

selection/add_labels_to_selection_atoms/src/index.ts

+            atomTest: ctx => StructureProperties.atom.auth_atom_id(ctx.element) === 'CA',
+            chainTest: ctx => StructureProperties.chain.label_asym_id(ctx.element) === 'A'


maybe start the list with the chainTest, then the atomTest.
I know that order does not matter in the dictionnary, but it will be easier to get the notion that the chainTest is actually run first for efficiency purposes.

Sounds good, done

papillot · 2024-06-11T13:11:05Z

selection/add_labels_to_selection_atoms/src/index.ts

+    structure.units.forEach(unit => {
+        for (let i = 0; i < unit.elements.length; i++) { // Iterate over each atom in the unit (each alpha carbon)
+            // Create a Loci using the unit and the index of the atom
+            const indices = OrderedSet.ofSingleton(i as StructureElement.UnitIndex);
+            const loci = StructureElement.Loci(struct, [{unit, indices: indices}]);
+            // Create a location to retrieve the atom's compID (residue name)
+            const location = StructureElement.Location.create(struct, unit, unit.elements[i]);
+            const resName = StructureProperties.atom.auth_comp_id(location);
+            // Add label to the loci
+            plugin.managers.structure.measurement.addLabel(loci, {labelParams: {
+                // Set label parameters, in this case the text and size
+                customText: 'Alpha Carbon '+resName,
+                textSize: 1
+            }});
+        }
+    })


This works but is inefficient, probably because it's creating 140+ representations serially. Most of the code I've stumbled upon is using special construct with a LabeProvider.
I haven't dug out more, but I suspect this is actually an antipattern.

papillot · 2024-06-11T14:56:54Z