A molecular structure can be present in a SAMSON document and still be absent from the view. The cause is not always a simple “hidden” switch: a node may inherit its visibility state from a parent in the hierarchy. That distinction matters when you are trying to diagnose a display problem, check a selection, or build a precise Node Specification Language (NSL) query.
NSL provides two useful ways to describe visibility. node.visibilityFlag (short name n.vf) checks a node’s own visibility flag. node.visible (short name n.v) describes whether the node is actually visible: its flag is true and its ancestors are visible too. The related node.hidden attribute (n.h) matches nodes that are hidden because their own flag is false or an ancestor’s flag is false.
Start with the effective state
If your question is “Which nodes are currently visible?”, query the effective state:
n.v
To find nodes that are not currently visible, use:
not n.v
These queries are useful when the visible result matters more than the setting on any individual node. For example, a child node can have its visibility flag set to true but still be hidden because an ancestor is hidden. Looking only at the child’s flag would not explain what you see; the effective visibility query accounts for the hierarchy.
Then inspect the local flag
To ask which nodes have their own visibility flag set to false, use:
n.vf false
Conversely, n.vf true matches nodes whose own flag is true. Comparing these results with n.v helps separate two different cases: a node hidden by its own flag, and a node whose own flag is enabled but whose visibility is affected by an ancestor. In other words, “flag is on” and “is visible” are not interchangeable questions.
Use the same distinction for selection
The hierarchy also affects selection queries. node.selectionFlag (n.sf) checks the selection flag on a node, while node.selected (n.s) matches nodes that are selected either directly or because an ancestor’s selection flag is true. To find nodes selected through the effective, inherited state, use n.s. To inspect nodes whose own selection flag is false, use n.sf false.
This difference is useful when a query seems to return more descendants than expected. A selected parent can make its descendants match the effective selected state even if their individual flags are not set. Use the flag query when investigating the node itself; use the effective-state query when asking what applies to the node in the hierarchy.
Make the query more specific
Visibility and selection attributes are node-level attributes, so they can be used across node types. If you want to narrow a query to a particular kind of structure, NSL also supports node types and categories. For example, n.t a in n.c lig matches atoms in ligands. The category lig is the short form of ligand, and a is the short form of atom.
A practical troubleshooting sequence is therefore: first ask whether the node is effectively visible with n.v or hidden with n.h; then inspect its own flag with n.vf; and, if selection is involved, compare n.s with n.sf. Keeping effective state separate from local flags makes hierarchy-related surprises easier to understand without assuming that every affected node has the same individual setting.
For the complete node-attribute reference and additional NSL details, see the SAMSON node attributes documentation.
Note: SAMSON and all SAMSON Extensions are free for non-commercial use. Get SAMSON.
