Why You Can’t See That Atom: Understanding Visibility in Molecular Models

Have you ever loaded a molecular model, only to find that some atoms, bonds, or entire molecular groups seem to have vanished? If you’re working in SAMSON and this has puzzled you, you’re not alone. The cause is often related to the visibility architecture in SAMSON’s data graph—and today we’ll take a closer look at how to debug these cases using the Node Specification Language (NSL).

Visibility vs. Visibility Flag

In SAMSON, nodes in the data graph (whether they are atoms, molecules, bonds, or visual models) can be made visible or hidden. But here’s the kicker: there’s a difference between a node’s visibility flag and whether it is actually visible.

The node.visibilityFlag (short name: n.vf) determines whether that node is allowed to be displayed. However, for a node to be truly visible, its visibility flag must be true, and all of its parent nodes must also be visible. Only then will node.visible (short name: n.v) return true.

Example Scenarios

Let’s say you are trying to select all visible atoms in a complex model:

This returns only the atoms whose visibility flag is true and that are part of a visible hierarchy. Handy when exporting models or preparing figures!

Now suppose you want to find atoms that are not visible, but should be based on their own flag. You can identify these situations like so:

This selects nodes that are supposed to be visible (via their flag) but are hidden because of an ancestor being hidden.

Debugging Hidden Nodes

If part of your model ‘disappeared’, you can examine hidden elements using node.hidden (short name: n.h). For instance:

This simple expression selects all nodes that are currently hidden, regardless of why.

If you also want to understand whether it’s due to their own visibility flag or that of an ancestor, compare:

The first one will select nodes whose own flag is false. The second one selects nodes that are hidden because of their ancestry—good to debug model-wide visibility issues.

Best Practices

• Use n.v when you need to select only truly visible nodes.
• Use n.vf when you’re configuring visibility from scripts or adjusting view options.
• To restore visibility, apply n.vf true to affected nodes and their ancestors.

Wrapping Up

Understanding the difference between visibilityFlag and visible will save you time, especially when working with large molecular systems or nested data graphs. SAMSON’s NSL lets you target and correct hidden elements with precision, once you know what you’re looking for.

To learn more, visit the full SAMSON NSL documentation on node attributes.

SAMSON and all SAMSON Extensions are free for non-commercial use. You can download SAMSON at https://www.samson-connect.net.