Large molecular models can be difficult to inspect one group at a time. You may be looking for a particularly charged region, a group within a certain size range, or a structure with a known ID. In SAMSON, the Node Specification Language (NSL) lets you describe those criteria as queries over structural group nodes.
This is useful when visual inspection alone is slow or when you want to make your selection criteria explicit and repeatable. Structural group attributes are collected in the structuralGroup attribute space, abbreviated sg. The key first step is to choose an attribute that matches the question you are asking.
Start with the kind of group you need
If you are narrowing candidates by size, use numberOfAtoms, short name nat. For example, sg.nat < 1000 matches groups with fewer than 1,000 atoms, while sg.nat 100:200 matches groups in the documented 100-to-200 range. The range form is a compact way to express a bounded search rather than checking several sizes individually.
When total size is too broad a measure, element counts can make the search more specific. Use sg.nC for carbon atoms, sg.nH for hydrogen, sg.nN for nitrogen, sg.nO for oxygen, and sg.nS for sulfur. For instance, sg.nO 10:20 identifies structural groups with a number of oxygen atoms in that range. The same comparison and range style applies to these element-count attributes.
Use charge carefully
Charge can help distinguish groups that have similar sizes or compositions. sg.fc queries total formal charge, which takes integer values; sg.fc > 1 selects groups with formal charge greater than one. sg.pc queries total partial charge, which can be a real number. For example, sg.pc 1.5:2.0 matches groups with partial charge between 1.5 and 2.0.
These are different attributes, so choose the one that corresponds to the quantity you intend to inspect. A formal-charge query is not interchangeable with a partial-charge query. If you are unsure which is relevant to your analysis, keep the distinction visible in your query and in any notes you make about the selection.
Keep identity and display state separate
When you already know a structure ID, sg.id can locate groups by that identifier. For example, sg.id >= 10 matches IDs greater than or equal to 10, and sg.id 5:10, 25:30 expresses two ID ranges. This can be more direct than searching by composition when the identifier is the information you have.
Structural groups also inherit node attributes such as visible, hidden, and selected. These describe display or selection state, not chemical composition. For example, sg.v concerns visibility, whereas sg.nO concerns oxygen count. Keeping those categories distinct helps prevent a display-state query from being mistaken for a chemical filter. The selected attribute is written as sg.selected; it has no short name in this attribute space.
A practical way to build a search
- Decide what you know: group size, an element count, charge, or structure ID.
- Choose the matching attribute and begin with a simple condition, such as
sg.nat < 1000orsg.fc 6:8. - Use a range when you have a meaningful interval, and a comparison such as
>or>=when you have a threshold. - Check that the attribute describes the quantity you care about—for example, total partial charge rather than total formal charge.
NSL makes the criterion legible: a query like sg.nC < 10 says directly that the search concerns carbon count, while sg.id 1 says it concerns identity. That clarity is valuable when revisiting a model or sharing how a set of structural groups was found.
For the complete attribute reference and additional examples, see the structural group attributes documentation.
Note: SAMSON and all SAMSON Extensions are free for non-commercial use. Get SAMSON.