The hidden-structure puzzle: reading visibility in SAMSON

A molecular structure can look absent from the viewport even when its nodes are still part of the document. That makes visibility a common source of confusion: is a node hidden itself, or is it hidden because something higher in the hierarchy is hidden? SAMSON’s Node Specification Language (NSL) lets you query both situations—and the difference matters when you want to find the cause rather than just inspect what is currently visible.

Two questions, two kinds of query

In NSL, node.visibilityFlag asks about a node’s own visibility flag. Its short form is n.vf. By contrast, node.visible, or n.v, describes effective visibility: a node is visible when its own visibility flag is true and its ancestors are visible.

This distinction explains why a node may have its visibility flag set to true but still not be visible. If an ancestor has its flag set to false, the descendant is hidden by the hierarchy. The related node.hidden attribute (n.h) matches nodes that are hidden either because their own flag is false or because an ancestor’s flag is false.

Queries for narrowing down the cause

  • n.v — find nodes that are effectively visible.
  • not n.v — find nodes that are not effectively visible.
  • n.vf false — find nodes whose own visibility flag is false.
  • n.vf true — find nodes whose own visibility flag is true, including nodes that may still be hidden by an ancestor.
  • n.h — find nodes that are hidden, whether the cause is their own flag or an ancestor’s.

A useful diagnostic sequence is to compare not n.v with n.vf false. The first query finds everything that is not currently visible according to the hierarchy. The second narrows that set to nodes with their own flag turned off. Nodes that are not visible but have n.vf true may be affected by an ancestor’s flag. This comparison helps separate local state from inherited state without assuming that a hidden-looking object has been removed.

Make the query more specific

Visibility queries can be combined with other node attributes to focus on a relevant part of a complex scene. For example, n.t a and not n.v expresses a search for atoms that are not effectively visible. To focus on a particular named node, combine a name condition with a visibility condition, such as n.n "L*" and not n.v, which matches nodes whose names start with “L” and are not visible.

You can also narrow a query by structural category. For example, n.c lig and not n.v targets ligand-category nodes that are not effectively visible; n.t a in n.c lig and not n.v narrows the search to atoms in ligands. These expressions use the documented category and type attributes alongside visibility, so you can investigate a specific class of nodes instead of searching the entire data graph.

Keep flags and outcomes separate

When troubleshooting, remember that n.vf reports a flag on the node, whereas n.v reports visibility in the context of the hierarchy. A true flag is not, by itself, proof that the node is visible. Likewise, n.h is a convenient way to find hidden nodes, but it does not distinguish whether the node’s own flag or an ancestor’s flag is responsible. Using these queries together gives you a clearer picture of the state you are inspecting.

For the complete list of node attributes and additional NSL examples, see the SAMSON node attributes reference.

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

Comments are closed.