A molecular structure can look incomplete for a simple reason: a node may be hidden even when its own visibility setting appears to be on. In SAMSON, visibility is hierarchical. An ancestor’s visibility flag can affect everything beneath it, so checking just the atom, residue, or group you care about may not explain what you see.
Node Specification Language (NSL) gives you two useful ways to investigate this: query a node’s visibility state, or query its visibility flag. They sound similar, but answer different questions. Knowing which one to use can save time when a selection or display seems inconsistent.
Visible state versus visibility flag
node.visibilityFlag (short form n.vf) checks the flag on the node itself. For example, n.vf false finds nodes whose own visibility flag is false.
node.visible (short form n.v) checks whether the node is visible after accounting for its ancestors. A node is visible when its own visibility flag is true and its ancestors are visible. Therefore, a node can have a true visibility flag and still not be visible if an ancestor has a false flag.
To investigate a missing part of a structure, start with these searches:
n.v— find nodes that are visible, including the effect of their ancestors.not n.v— find nodes that are not visible.n.vf false— find nodes whose own visibility flag is false.n.vf true— find nodes whose own visibility flag is true.
If a node has n.vf true but is found by not n.v, that points you toward the hierarchy: inspect its parent groups and other ancestors for a false visibility flag. The query results help distinguish a local setting from an inherited effect; they do not, by themselves, identify which ancestor is responsible.
Apply the same idea to selection
Selection has a similar distinction. node.selectionFlag (short form n.sf) checks a node’s own selection flag. node.selected (short form n.s) reflects selection that can come from the node itself or from an ancestor. This matters when a whole group is selected: its descendants can count as selected even if their individual flags are not set.
n.s— find selected nodes, taking ancestors into account.not n.s— find nodes that are not selected.n.sf true— find nodes with their own selection flag set to true.n.sf false— find nodes with their own selection flag set to false.
Use the derived state when the question is practical — for example, which nodes are currently visible or selected? Use the flag when you are investigating the node’s own setting. Keeping those questions separate makes hierarchy-related surprises easier to reason about.
A small, repeatable troubleshooting routine
- Search for the state you observe, such as
not n.vfor nodes that are not visible. - Check the corresponding flag, such as
n.vf false, to see which nodes have a local false flag. - For nodes whose effective state differs from their own flag, inspect the ancestor chain.
- If the scene contains many kinds of nodes, narrow your investigation by node type. For example,
n.t amatches atoms, whilen.t rmatches residues. You can run the type query separately from the visibility query while troubleshooting.
The distinction also applies to locking. n.l reports nodes that are locked either directly or through a locked ancestor, while n.lf true checks for a true locked flag on the node itself. In all three cases — visibility, selection, and locking — the effective state and the local flag are related, but they are not interchangeable.
These short queries are useful when a large molecular hierarchy makes it difficult to tell whether a display or selection issue belongs to an individual node or to a containing group. For the complete node attribute reference and additional examples, see the SAMSON NSL node attributes documentation.
Note: SAMSON and all SAMSON Extensions are free for non-commercial use. Get SAMSON.
