Selection label examples by Simard302 · Pull Request #5 · molstar/example-gallery

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


        // 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

+        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

+        // 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

+            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

+    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

+    // A StructureSelection is a Singleton if each iteration only adds a single element (atom)
+    // A StructureSelection is a Sequence if any iteration adds multiple elements (atoms)


A StructureSelection is made of Singletons if there is no grouping (e.g. when using Queries.generators.atoms) or when every group only contains a single element (atom). Matched elements are merged in a single unit within a unique structure in the StructureSelection var.
A StructureSelection is a Sequence if it contains at least one group with more than one element. Each group is its own Structure object in the structures array property of the StructureSelection var.
In this query, Queries.generators.chains creates a grouping at the chain level, that contains elements from the entire chains: selection is of type StructureSelection.Sequence.

papillot · 2024-06-11T15:10:13Z

+    // A StructureSelection is a Singleton if each iteration only adds a single element (atom)
+    // A StructureSelection is a Sequence if any iteration adds multiple elements (atoms)
+    const loci: Loci[] = [];
+    if (StructureSelection.isSingleton(selection)) { // Singleton if each chain only has 1 atom


Singletons if grouping by atoms (no grouping)

papillot · 2024-06-11T15:59:28Z

+    // A StructureSelection is a Sequence if any iteration adds multiple elements (atoms)
+    const loci: Loci[] = [];
+    if (StructureSelection.isSingleton(selection)) { // Singleton if each chain only has 1 atom
+        // Iterate over each Unit in the selection and create a Loci for each Unit


Iterate over each Unit in the structure. By default the units in the struct initial object were segmented by chain identifiers. Each Unit corresponds to a distinct chain.

Don't take it for granted that each unit corresponds to a whole or single chain. Best to use selections!

papillot · 2024-06-11T16:01:53Z

+        // Iterate over each Unit in the selection and create a Loci for each Unit
+        selection.structure.units.forEach(unit => {
+            // Create an OrderedSet of indicies for the length of unit.elements
+            const indices = OrderedSet.ofBounds(0 as StructureElement.UnitIndex, unit.elements.length as StructureElement.UnitIndex)


const indices = OrderedSet.ofBounds(0, unit.elements.length)

papillot · 2024-06-11T16:07:06Z

+        // Iterate over each Structure in the selection and create a Loci for each SubStructure
+        selection.structures.forEach(structure => {
+            loci.push(Structure.toSubStructureElementLoci(struct, structure));
+        })


// Iterate over each Structure in the selection (one per chain) and create a Loci
...
loci.push(Structure.toStructureElementLoci(structure));

We have a label structure representation, which can do many use-cases much more efficiently (and happy to see more params added as needed)

Simard302 added 4 commits June 10, 2024 09:59

Created "Add label to selection whole"

d3edb9f

Created "Add labels to selection atoms

3ec27e0

Fixed comment

6a8c633

Updated readme

d62f9e9

Simard302 requested a review from papillot June 10, 2024 14:05

Simard302 and others added 2 commits June 10, 2024 14:24

Added residue name to label for atoms

ea7ae76

linting

364cd21

papillot reviewed Jun 11, 2024

View reviewed changes

Simard302 added 2 commits June 13, 2024 14:44

Comments changed

fc3e2aa

Made label example changes

5685541

		// 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.

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

		// A StructureSelection is a Singleton if each iteration only adds a single element (atom)
		// A StructureSelection is a Sequence if any iteration adds multiple elements (atoms)

Conversation

Simard302 commented Jun 10, 2024

Overview

Changes made

How to test

Specific review requests

Uh oh!

papillot left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

papillot Jun 10, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

papillot Jun 10, 2024 •

edited

Loading