When a node looks selected—or hidden—check the hierarchy

A molecular model can be confusing to inspect when a node appears selected, hidden, or locked even though its own setting does not seem to explain what you see. In SAMSON, some node states are inherited from ancestors in the data graph. That distinction matters when you are building searches: do you want nodes with a particular flag set themselves, or every node that is affected by a setting higher in the hierarchy?

The Node Specification Language (NSL) provides separate attributes for these two questions. Knowing which one to use can make a query much more precise—and help explain why a search returns more nodes than expected.

Effective state versus a node’s own flag

For selection, use node.selected (short form n.s) to match nodes that are selected either directly or because an ancestor’s selection flag is true. Use node.selectionFlag (short form n.sf) to query the flag on the node itself.

• node.selected finds nodes that are selected in the hierarchy-aware sense.
• node.selectionFlag true finds nodes whose own selection flag is true.
• node.selectionFlag false finds nodes whose own selection flag is false.

This is useful when a group has been selected and its descendants consequently match node.selected. If your aim is to find nodes whose flags were explicitly set, query node.selectionFlag instead. If your aim is to identify everything currently affected by selection, use node.selected.

Visibility follows the same pattern

A node can be hidden because its own visibility flag is false, or because an ancestor’s visibility flag is false. The effective-state query node.hidden (short form n.h) matches nodes hidden for either reason. The inverse perspective is available with node.visible (short form n.v): it matches nodes whose visibility flag is true and whose ancestors are visible.

To inspect the flag on a node itself, use node.visibilityFlag (short form n.vf). For example, node.visibilityFlag false asks about the local flag, while node.hidden asks whether the node is hidden in the hierarchy. These queries answer different questions, so a node can match one without matching the other.

Locked nodes can also inherit state

The distinction applies to locking too. node.locked (short form n.l) matches nodes that are locked because their own locked flag is true or because an ancestor’s flag is true. node.lockedFlag (short form n.lf) checks the node’s own flag. If you are diagnosing why a node is locked, comparing the effective query with the flag query helps separate inherited state from local state.

A practical way to choose a query

1. Start with the result you need. Are you looking for every node affected by a state, or only nodes whose own flag is set?
2. Use the effective attribute for the first question. Try node.selected, node.hidden, or node.locked.
3. Use the flag attribute for the second. Try node.selectionFlag, node.visibilityFlag, or node.lockedFlag, followed by true or false when you want to specify a value.

For example, node.selectionFlag false is not simply another spelling of not node.selected. The first asks whether a node’s own flag is false; the second excludes nodes that are selected, including through an ancestor. Choosing based on intent avoids conflating local settings with the state a node inherits.

The same node-level attributes are available across node types, which makes them useful when a search should cover more than one kind of node. In short: use the flag attributes to inspect local settings, and the state attributes to search by the result of those settings across the hierarchy.

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

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