When a molecular scene contains many structural groups, it can be difficult to spot the ones relevant to a question: Which groups are unusually large? Which have a particular charge? Where are the carbon-rich groups? Inspecting them one by one is slow, and visual appearance alone does not answer these questions.
SAMSON’s Node Specification Language (NSL) provides a way to search structural group nodes by attributes such as atom counts, charge, and structure ID. The key distinction is that these queries match structural groups, not individual atoms. That makes them useful when you want to locate or inspect groups based on their overall composition or properties.
Start with the group namespace
Structural group attributes use the structuralGroup attribute space, abbreviated sg. For example, sg.nat is the short form of structuralGroup.numberOfAtoms. The short forms make repeated queries easier to read, while the full names can be helpful when you are learning what an attribute represents.
For a first pass, you might look for groups with more than 100 atoms:
sg.nat > 100
Or inspect groups whose atom counts fall in a specified range:
sg.nat 100:200
These expressions give you a practical way to narrow a large scene by group size instead of relying on visual estimation. The same count-style query pattern is available for several element counts.
Use composition counts to ask focused questions
NSL exposes counts for carbon, hydrogen, nitrogen, oxygen, and sulfur atoms, as well as coarse-grained atoms. For example, the following expressions look for groups with fewer than 10 carbons or between 10 and 20 oxygens:
sg.nC < 10— number of carbonssg.nO 10:20— number of oxygenssg.nH 10:20— number of hydrogenssg.nN < 10— number of nitrogenssg.nS 10:20— number of sulfurssg.ncga 100:200— number of coarse-grained atoms
This is useful when a structural group’s elemental makeup matters more than its name or visual style. For example, a count query can help you identify groups worth examining for a composition-related reason. The query describes a property to match; it does not, by itself, explain why that group has that composition.
Distinguish formal and partial charge
The structural group attribute sg.fc matches total formal charge, while sg.pc matches total partial charge. They are separate attributes, so choose the one that fits the question you are asking.
sg.fc 6:8— formal charge between 6 and 8sg.pc 1.5:2.0— partial charge between 1.5 and 2.0
Formal charge accepts integer values; partial charge accepts real values. Keeping that difference in mind helps avoid treating a partial-charge query as if it were an integer-only count.
Use IDs and inherited attributes for organization
To search by structure ID, use sg.id. For instance, sg.id 5:10, 25:30 describes two ID ranges. This can be helpful when you already know which ID intervals you want to inspect.
Structural groups also inherit general node attributes. For example, sg.h refers to hidden status, sg.v to visibility, and sg.selected to selection state. The selected attribute has no short name in this attribute space, so use its full form. These attributes can help you distinguish groups by their current display or selection state as well as by composition.
A useful habit is to choose the attribute that directly describes the question, then use a comparison or range that makes the search specific. Check the attribute’s meaning before interpreting the result: atom counts, charges, IDs, and visibility describe different things, even though they can all be used to match structural groups.
For the complete attribute reference and additional examples, see the SAMSON structural group attributes documentation.
Note: SAMSON and all SAMSON Extensions are free for non-commercial use. Get SAMSON.