A large molecular structure can contain many groups, and scanning them one by one is a slow way to find a region with a particular size, composition, or charge. Structural group attributes in SAMSON’s Node Specification Language (NSL) give you a more direct approach: describe the property you care about, then use the expression to match structural groups with that property.
This is especially useful when you have a specific question in mind: Which groups contain fewer than 10 oxygen atoms? Which have a partial charge in a chosen range? Which groups are larger than 100 atoms? Instead of relying on names or visual appearance, you can query measurable attributes.
Start with the structural-group prefix
Structural group expressions use the structuralGroup attribute space, abbreviated as sg. The prefix matters: it indicates that the expression is targeting structural group nodes. For example, sg.nat > 100 uses the short name nat for numberOfAtoms and matches groups with more than 100 atoms.
If you prefer readable expressions over shorter ones, the long form is available too: structuralGroup.numberOfAtoms > 100. Short names are handy when writing repeated queries; long names can make a query easier to interpret later, especially when sharing it with someone who is new to NSL.
Use counts to narrow down by composition or size
Atom counts are a practical first filter when a structure contains groups of very different sizes. Use sg.nat for the total number of atoms, or choose an element-specific count: sg.nC for carbon, sg.nH for hydrogen, sg.nN for nitrogen, sg.nO for oxygen, and sg.nS for sulfur. Coarse-grained atom counts are available through sg.ncga.
For example, sg.nO < 10 matches groups with fewer than 10 oxygen atoms. To look for groups within a size interval, use a colon-separated range, as in sg.nat 100:200. The same style is used for element counts, such as sg.nC 10:20. These expressions help turn a broad inspection task into a more focused search based on properties you can state explicitly.
Check charge with the right attribute
Formal charge and partial charge are separate attributes, so choose the one that fits the question. Use sg.fc for formal charge, which takes integer values. For instance, sg.fc 1 matches groups with formal charge equal to 1, while sg.fc 6:8 describes a range.
For total partial charge, use sg.pc, which accepts real values. An expression such as sg.pc 1.5:2.0 matches groups with partial charge between 1.5 and 2.0. Keeping these two charge measures distinct helps avoid a common source of confusion: a query for formal charge is not a substitute for one based on partial charge.
Use IDs and inherited attributes when useful
Structural groups also have a structureID attribute, abbreviated as sg.id. You can match an ID directly, set a comparison such as sg.id >= 10, or specify multiple ranges, as in sg.id 5:10, 25:30. This is useful when you already know which IDs you want to locate.
Structural groups inherit several node attributes as well. For example, sg.n "A" refers to a name, while sg.v and sg.h query visibility and hidden state. Selection can be checked with sg.selected; structural groups do not use the node attribute’s short name s for this property. These inherited attributes provide ways to describe groups by more than their chemical counts and charges.
A simple way to build a useful query
Begin with one property that captures the problem: size, a particular element count, charge, or ID. Check whether the attribute uses integers or real values, then choose a comparison or range that expresses the condition. The examples above are individual expressions; consult the NSL reference for the language’s broader expression syntax before combining conditions. This measured approach makes it easier to understand what each part of a query is intended to match.
For the complete attribute list and additional examples, see the structural group attributes reference.
Note: SAMSON and all SAMSON Extensions are free for non-commercial use. Get SAMSON.
