When building or analyzing molecular systems in SAMSON, it’s common to face unexpected behaviors: some atoms or structures might not be appearing in the workspace, or your scripts seem to be skipping parts of your model. Often, this is because certain nodes are not actually visible—either they have been manually hidden, or their visibility is affected by their parent nodes.
In this post, we explore how to use three essential attributes in the Node Specification Language (NSL) of SAMSON to debug and fine-tune visibility in molecular models: visible, hidden, and visibilityFlag. Understanding the difference between these can help you ensure accurate visual representation and correct analysis behavior.
Understanding the Three Visibility Attributes
1. node.visible (short: n.v)
This attribute matches nodes that are ultimately visible in the UI. That means the node’s own visibilityFlag must be true and none of its ancestors must be hidden. This is the most intuitive one to use when you want to select what is currently drawn on screen.
Example:
|
1 |
n.v |
Matches all nodes that are actually visible right now.
2. node.hidden (short: n.h)
This is the inverse of n.v in most cases. It matches nodes that are hidden—because their own visibilityFlag or that of an ancestor is false. It’s useful for checking which parts of a system are being suppressed.
Example:
|
1 |
n.h |
Matches all nodes that are hidden due to their own visibility or inherited from a parent node.
3. node.visibilityFlag (short: n.vf)
This attribute specifically refers to the flag on the node itself. It doesn’t consider ancestors. If you want to know whether the node wants to be visible, this is the attribute to check.
Example:
|
1 |
n.vf false |
Selects nodes that have a visibility flag set to false, even if their ancestors are visible.
Why This Matters for Molecular Modeling
If you’re working with complex systems—say, hundreds of residues across multiple chains—you might use NSL to filter or modify specific selections. Let’s say you’re running a script to measure distances, but it’s only working on a subset of atoms. Before diving into debugging your script, try this first:
|
1 |
not n.v |
This quickly tells you which nodes are not visible. Perhaps they were deactivated earlier or grouped under a hidden parent. On the other hand, if you’re assigning properties like materials only to visible atoms, knowing whether a node’s visibility is inherited or local also helps:
|
1 |
n.vf false |
That’s a local setting, and it’s easy to reset without affecting the whole tree.
Tips for Better Visibility Control
- Use
n.vwhen you want to operate only on what users can see. - Use
n.hwhen you want to detect and potentially reactivate hidden parts of your model. - Use
n.vfwhen toggling visibility inside scripts or extensions.
Understanding these distinctions is especially helpful in collaborative environments or in saved projects with multiple visibility layers.
You can learn more about visibility and other node attributes in the official SAMSON documentation.
SAMSON and all SAMSON Extensions are free for non-commercial use. You can download SAMSON at https://www.samson-connect.net.