A common molecular-modeling puzzle: you query for selected atoms, but the results seem to include atoms you never selected individually. Or a node’s visibility appears to disagree with its own visibility setting. In SAMSON, this can happen because a node’s effective state may come from an ancestor in the data graph.
Node Specification Language (NSL) provides two useful ways to reason about these states: the effective attributes selected, visible, hidden, and locked; and the corresponding flags, such as selectionFlag and visibilityFlag. Knowing which kind of question you are asking makes a query much easier to interpret.
Effective state versus a node’s own flag
node.selected (n.s) matches nodes that are selected because their own selection flag is true or because an ancestor’s selection flag is true. By contrast, node.selectionFlag (n.sf) tests the flag on the node itself.
That distinction matters when selection is applied higher in the hierarchy. If a parent is selected, its descendants can match n.s even when their own flags are not set. To inspect nodes whose own selection flag is false, use n.sf false. To find nodes selected either locally or through an ancestor, use n.s.
|
1 2 3 |
n.s n.sf true n.sf false |
These are different questions, not interchangeable spellings. One asks about the node’s selected state in context; the other asks about its individual flag.
The same idea applies to visibility and locking
node.visible (n.v) matches nodes whose visibility flag is true and whose ancestors are visible. So a node can have a true visibility flag of its own but still not be visible if an ancestor’s visibility flag is false. The node.visibilityFlag attribute (n.vf) checks the node’s own flag instead.
Similarly, node.hidden (n.h) includes nodes hidden by their own visibility flag or by an ancestor’s flag. For locking, node.locked (n.l) can match a node locked directly or through an ancestor, while node.lockedFlag (n.lf) checks the individual flag.
|
1 2 3 4 5 |
n.v n.vf false n.h n.l n.lf true |
Make the query answer a specific question
When troubleshooting a selection or display result, first decide whether you care about the state a node experiences in the hierarchy or the flag set directly on that node. For effective visibility, query n.v; to inspect a node’s own visibility flag, query n.vf. For effective selection, use n.s; for the local selection flag, use n.sf.
You can combine node-level attributes with categories and node types to narrow the result. For example, n.t a in n.c lig identifies atoms in ligands. Pairing that kind of structural filter with a state query lets you ask a more focused question, such as which ligand atoms are selected or visible, rather than inspecting every node in the scene.
A practical debugging sequence is to compare the effective attribute with its flag, then consider whether an ancestor may explain the difference. This avoids treating a hierarchy-wide state as though it were an isolated setting on each atom or structural group.
For the full list of node attributes, categories, types, and examples, see the SAMSON Node Specification Language node reference.
Note: SAMSON and all SAMSON Extensions are free for non-commercial use. Get SAMSON.