A molecular model can contain many structural groups, and finding the ones relevant to a question is not always straightforward. You might want to inspect only large groups, find groups rich in oxygen, or locate structures with a particular charge. Browsing the model by eye can make these simple checks surprisingly tedious.
SAMSON’s Node Specification Language (NSL) provides a compact way to describe the structural groups you want to match. The key idea is to start with a question you can express as an attribute, then use a short query to narrow the search. Structural-group attributes use the sg prefix, so the query is explicit about the kind of node being targeted.
Start with the scale of the group
If you need to distinguish small groups from larger ones, use numberOfAtoms, abbreviated nat. For example, sg.nat < 1000 matches structural groups with fewer than 1,000 atoms, while sg.nat 100:200 matches groups whose atom count falls between 100 and 200. This is a useful first pass when a model contains structures of very different sizes: it lets you focus on a meaningful size range instead of scanning every group.
For coarse-grained models, there is a separate count: sg.ncga filters by the number of coarse-grained atoms. Keeping that distinct from sg.nat matters because a coarse-grained atom count and a total atom count describe different things. Choose the attribute that matches the representation and question you are working with.
Use composition to find groups of interest
Structural groups can also be filtered by counts of particular elements. The short names are nC for carbon, nH for hydrogen, nN for nitrogen, nO for oxygen, and nS for sulfur. For example, sg.nO < 10 matches groups with fewer than 10 oxygen atoms, while sg.nC 10:20 matches groups with between 10 and 20 carbon atoms.
These queries can help turn a broad visual search into a specific question: Are there groups with many nitrogen atoms? Are the groups I want to inspect within a particular carbon-count range? You can try a threshold or range, review what matches, and adjust the criterion to suit the model. The element-count attributes are described as counts of atoms of the corresponding element; they do not, by themselves, identify a chemical role or functional group.
Keep formal and partial charge separate
Charge is another useful way to narrow a search, but NSL exposes two different charge attributes. sg.fc filters by total formal charge and accepts integers. For instance, sg.fc 6:8 matches structural groups with formal charge between 6 and 8. sg.pc filters by total partial charge and accepts real values; sg.pc 1.5:2.0 matches groups with partial charge in that range.
Those two attributes answer different questions, so choose one deliberately. A formal charge query is not a substitute for a partial charge query. When charge is the reason for filtering, it is worth checking which charge representation is relevant to your analysis before interpreting the result.
Make the query match your task
A practical approach is to write down the property you are trying to isolate, select the corresponding attribute, and begin with a readable threshold or range. For example:
sg.nat 100:200— focus on groups of a chosen size.sg.nN < 10— filter by nitrogen-atom count.sg.fc > 1— find groups with formal charge greater than 1.sg.pc 1.5:2.0— filter by a partial-charge interval.sg.id 10:20, 30:40— match groups whose structure IDs fall into either of two ranges.
Structure ID is useful when you already know which IDs matter; it is not the same as filtering by chemical composition. Meanwhile, inherited node attributes can help distinguish groups by state: for example, sg.v checks visibility, and not sg.selected matches groups that are not selected. These attributes complement composition and charge filters by describing node properties rather than molecular makeup.
One helpful habit is to keep queries focused on a single criterion while you are learning what each attribute matches. That makes it easier to understand why a group appears in the results and to revise the threshold if the set is too broad or too narrow. For the full 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.