Why Is This Atom Selected? Read SAMSON’s Hierarchy Flags

You select a group in a molecular model, then find that many of its atoms also match a selection query. Or an atom appears hidden even though its own visibility setting seems enabled. These results can be confusing if you expect every node to be evaluated only by its own state.

In SAMSON’s Node Specification Language (NSL), some node attributes describe a node’s effective state: the state it has after taking its ancestors into account. Other attributes report the node’s own flag. Knowing which kind of question you are asking makes selection and visibility queries much easier to interpret.

Effective state versus the node’s own flag

Consider selection. The node.selected attribute, abbreviated n.s, matches nodes that are selected either because their own selection flag is true or because an ancestor’s selection flag is true. By contrast, node.selectionFlag, abbreviated n.sf, checks the flag on the node itself.

That distinction helps explain an apparent surprise: if a parent group is selected, its descendants can match n.s even when their own selection flags are not set. The query is not necessarily reporting a mistake; it may be reporting inherited selection.

  • n.s asks: “Is this node selected, including through an ancestor?”
  • n.sf true asks: “Is this node’s own selection flag set?”
  • n.sf false asks for nodes whose own selection flag is false.
  • not n.s asks for nodes that are not selected in the effective, hierarchy-aware sense.

Use the first kind of query when you care about what is currently selected in the hierarchy. Use the flag query when you need to inspect or distinguish a node’s own setting.

The same pattern applies to visibility

Visibility has a parallel distinction. node.visible (n.v) matches nodes whose visibility flag is true and whose ancestors are visible. node.visibilityFlag (n.vf) checks a node’s own visibility flag.

So a node can have a true visibility flag but still not be effectively visible if an ancestor’s visibility flag is false. For a hierarchy-aware visibility check, use n.v. To examine the local setting regardless of ancestor visibility, use n.vf true or n.vf false.

There is a similar inherited-state distinction for locking: node.locked (n.l) matches nodes locked by their own flag or by an ancestor’s flag, while node.lockedFlag (n.lf) checks the node’s own flag.

Make the query answer a specific question

When a result seems broader than expected, pause and identify the question behind the query:

  1. Do I want the effective state? Use n.s, n.v, or n.l for selection, visibility, or locking that includes ancestor effects.
  2. Do I want the node’s own setting? Use n.sf, n.vf, or n.lf to check the corresponding flag directly.
  3. Do I want a particular kind of node? Add a node-type or category filter to narrow the subject. For example, n.t a matches atoms, and n.c lig matches ligands. The documented expression n.t a in n.c lig selects atoms in ligands.

This way of thinking is useful when a query returns descendants you did not explicitly flag, or when a node’s local setting does not match its visible or selected state. It also makes queries easier to share with colleagues: describe whether you mean the node’s own flag or its effective state, then specify the node types or structural categories you want to inspect.

For the complete list of node attributes, categories, types, and examples, learn more in the SAMSON node attributes reference.

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

Comments are closed.