Taming Node Group Selections in SAMSON’s NSL: A Guide for Molecular Modelers

When working with complex molecular systems, a frequent challenge is isolating and manipulating specific parts of a model—such as ligands, protein domains, solvent clusters, or user-defined selections. In SAMSON, the Node Specification Language (NSL) gives modelers precision over structural selections, especially through node group attributes.

But here’s a common issue: after grouping nodes (which might include atoms, molecules, or visual models), how do you easily target just those specific groups later—maybe for visualization or scripting purposes—without selecting every individual atom again?

This is where node group attributes in NSL become useful. If you’re already familiar with node-level filtering, the transition to node groups will feel natural—yet it adds a layer of specificity that can make your workflows notably more efficient.

What Are Node Group Attributes?

Node group attributes let you filter and act specifically on node groups, using the nodeGroup namespace (short name: ng). These attributes are inherited from regular node attributes, but scoped only to node groups—this matters when your scene gets complex.

Here are the main attributes for node groups:

name (ng.n): Match node groups by name (supports wildcard matching).
selected: True if the node group is currently selected. (Note: this does not have a short name.)
selectionFlag (ng.sf): Whether the node group was marked during selection operations.

Practical Uses

If you’ve manually grouped all ligands into a node group called Ligands, and you want to apply a script to only this group, filtering with the following expression will work:

ng.n "Ligands"

1	ng.n "Ligands"

Or, if you have several similarly named groups—e.g., Ligand_1, Ligand_2—then the wildcard option helps like so:

ng.n "Ligand_*"

1	ng.n "Ligand_*"

To target only currently selected groups in your scene:

ng.selected

1	ng.selected

This proves particularly helpful when scripting across groups you’ve manually highlighted in the GUI.

Comparison With Node-Level Filtering

It’s worth noting: while selected, name, and selectionFlag exist on both nodes and node groups, the short name for selection s used with nodes does not exist for node groups. So, for node groups, always use the full keyword selected.

This distinction minimizes confusion in selection logic and lets you apply filters with reliability.

Efficiency Tips

When dealing with multiple grouped selections, using wildcards on ng.n is far more scalable than running multiple filters.
ng.sf is useful in combination with visual scripts that tag node groups during workflows.
Filtering selections by node group attribute avoids affecting unintended lower-level nodes—reducing scripting errors.

Whether you’re scripting selection logic, enhancing visuals, or preparing output files, knowing how to work with node group attributes can save time and prevent mistakes in large molecular systems.

To learn more, explore the full documentation page here: https://documentation.samson-connect.net/users/latest/nsl/nodeGroup/

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