Find the Right Group: A Practical Guide to Node-Group Queries

In a molecular model, the hard part is not always finding an atom or residue. Sometimes the challenge is locating the group that organizes the part of the model you want to inspect. A query aimed at the wrong kind of node can miss the target—or make it harder to tell what your expression is matching.

SAMSON’s Node Specification Language (NSL) provides a dedicated attribute space for node groups: nodeGroup, abbreviated ng. That scope is a useful starting point when your goal is to match node group nodes specifically.

Start by narrowing the node type

Use ng before an attribute to express that the query concerns node groups. For example, ng.n "A" uses the short name n for the group’s name. The full attribute form is ng.name "A". Both examples make the target type explicit, which is helpful when a model contains many different kinds of nodes.

The reference also shows ng.n "L*" as an example. If you are relying on a particular pattern-matching behavior, check the NSL examples or test the expression in your context; this attribute reference lists the expression but does not explain the matching rules for the asterisk.

Tell selection state from selection flags

Node groups inherit several attributes from the general node attribute space. Two are easy to confuse:

  • selected describes the selected state. For node groups, write ng.selected or not ng.selected. The node-group reference specifically notes that this attribute does not use the short name s.
  • selectionFlag, abbreviated sf, is a separate Boolean attribute. The documented examples are ng.sf and ng.sf false.

These are distinct attributes, so choose the one that matches the question you are asking. Are you querying whether a group is selected, or querying its selection flag? Keeping those ideas separate can make an expression easier to read and troubleshoot.

A small, careful query workflow

  1. Choose the node type. Begin with ng when the target is a node group, rather than writing a query that leaves the intended node type unclear.

  2. Choose one attribute. Use ng.n or ng.name to query a name, ng.selected to query selection state, or ng.sf to query the selection flag.

  3. Use the value that answers your question. For example, ng.n "A" is the documented name example; not ng.selected expresses the inverse of the selected-state test.

  4. Keep expressions readable. When debugging, inspect the node type, attribute, and value separately. This makes it easier to spot a mistaken scope or a confusion between selected and selectionFlag.

Node-group queries are most useful when they reflect the structure you are actually trying to work with. Starting with the ng scope and choosing the precise inherited attribute gives you a compact, understandable expression without mixing up a group’s name, selected state, and selection flag.

For the complete attribute reference, see the SAMSON node group attributes documentation.

Note: SAMSON and all SAMSON Extensions are free for non-commercial use. Get SAMSON.

Comments are closed.