A molecular structure can contain many groups, and finding the ones that matter is not always a visual task. You may need to identify a group by its atom count, elemental composition, charge, or structure ID before inspecting it further. In SAMSON, the Node Specification Language (NSL) provides attributes for describing structural groups with these properties.
This guide focuses on a practical subset of those attributes: using group-level counts and charge values to narrow down what you are looking for. The expressions below match structural group nodes, rather than individual atoms. That distinction matters: a group’s carbon count, for example, describes the number of carbon atoms in that group.
Start with the group namespace
Structural-group attributes belong to the structuralGroup attribute space. Its short name is sg, so you can write expressions such as sg.nat < 1000 instead of structuralGroup.numberOfAtoms < 1000. The short form makes repeated queries easier to read, while the full form can be helpful when you are learning what each attribute means.
Use size to narrow the search
If you want to distinguish smaller groups from larger ones, use numberOfAtoms, abbreviated nat. For instance, sg.nat < 100 matches structural groups with fewer than 100 atoms. To look for groups in a particular span, use a range: sg.nat 100:200.
Size alone may not tell you what a group contains, so NSL also provides counts for specific elements. The short names are nC for carbon, nH for hydrogen, nN for nitrogen, nO for oxygen, and nS for sulfur. For example, sg.nC < 10 describes groups with fewer than 10 carbon atoms, while sg.nO 10:20 describes groups with an oxygen count between 10 and 20. These are group-level counts—not a claim about the order or connectivity of atoms.
There is also ncga, short for numberOfCoarseGrainedAtoms. It can be queried in the same style as the total atom count, for example sg.ncga < 1000. This provides a separate count for coarse-grained atoms.
Don’t treat charge values as interchangeable
Two charge attributes are available, and they describe different quantities. formalCharge (fc) uses integer values. For example, sg.fc > 1 matches groups whose formal charge is greater than 1, and sg.fc 6:8 specifies a range.
partialCharge (pc) represents the group’s total partial charge and accepts real numbers. Examples include sg.pc > 1.5 and sg.pc 1.5:2.0. When choosing an attribute, use the one that corresponds to the charge measure you actually need; a formal charge and a partial charge are not simply two spellings of the same value.
Keep track of structure IDs and display state
If structure IDs are useful in your workflow, the short attribute is id. For example, sg.id >= 10 matches groups with IDs greater than or equal to 10, while sg.id 5:10, 25:30 specifies two ID ranges.
Structural groups also inherit node attributes for state and display-related properties. Examples include sg.selected, sg.v for visible, and sg.h for hidden; their negated forms can be written as not sg.selected and not sg.v. These can help express whether a group is selected or visible, alongside the structural properties described above.
A simple way to approach a query
- Decide whether you are asking about the whole group or an individual atom. The attributes here match groups.
- Choose the property that answers your question: total size (
nat), an element count (nC,nO, and so on), a charge (fcorpc), or an ID (id). - Use a comparison for a cutoff, such as
<or>=, or a range when you want to specify a span. - Check that the chosen attribute’s value type fits the query: counts and formal charge use integers, while partial charge uses real numbers.
This approach turns a vague search—“find the groups with the composition or charge I care about”—into a specific, inspectable criterion. To see the complete structural-group attribute reference and more examples, visit the SAMSON structural group attributes documentation.
Note: SAMSON and all SAMSON Extensions are free for non-commercial use. Get SAMSON.