Finding the right atoms in a large molecular structure can become a task of its own. You may need only the protein backbone, a few residue numbers, aromatic carbons, or atoms in a particular region of space. Clicking through the structure is slow, and a selection that is too broad can quietly affect the next step in your workflow.
SAMSON’s Node Specification Language (NSL) lets you describe the atoms you want using attributes, values, and logical combinations. The useful shift is to think of a selection as a small, readable question about your structure: Which atoms satisfy all these conditions?
Start with a specific chemical feature
For example, to find aromatic carbon atoms, combine an element-symbol condition with the aromatic flag:
a.s C and a.ar
Here, a.s C selects carbon atoms, while a.ar selects aromatic atoms. The and means both conditions must be met. This kind of combination is useful whenever one attribute alone returns too many atoms.
To focus on heavy atoms in an amino-acid backbone, use:
a.aabb
The documentation defines this attribute as matching heavy atoms that belong to an amino-acid backbone. That detail matters: it is not a general “all backbone atoms, including hydrogens” query.
Use residue and chain information to narrow the search
Structure metadata can turn a broad chemical selection into a targeted one. To select atoms in residues 40 through 50, for example:
a.resi 40:50
To match atoms from chain A, use a.c A. You can combine these conditions with a chemical filter—for instance, carbon atoms in that residue range and chain:
a.s C and a.resi 40:50 and a.c A
Ranges and comma-separated values are also available for many attributes. For example, a.resi 40:50,100 matches the specified range and residue 100. This can be more convenient than creating several separate selections.
Filter by values, not just labels
Some modeling tasks call for numeric criteria. To find atoms with a partial charge above 1.3, use a.pc >= 1.3. To select atoms whose occupancy is below 0.3, use a.oc < 0.3. Numeric attributes can also be queried with ranges, such as a.oc 0.6:0.7.
Coordinates are useful when you want to inspect a spatial slice of a structure. For example, a.x 1nm:10nm selects atoms whose x coordinate lies between 1 and 10 nanometers. You can combine axes to define a simple rectangular region:
a.x > 10 A and a.y > 10 A
Keep units explicit when working with distances. NSL examples use units such as angstroms (A), nanometers (nm), and picometers (pm), so a coordinate threshold is easier to review when its unit is visible.
Check whether an attribute needs preparation
Not every attribute is available in every structure, and some depend on prior calculations or particular atom types. Geometry must be computed before querying a.g; hybridization must be assigned before querying a.hy, and it may not be specified by default. Coarse-grained mass, radius, and type filters apply only to coarse-grained atoms. SYBYL queries likewise require SYBYL types to have been assigned.
This is a useful troubleshooting checklist when a query returns no matches: confirm that the attribute applies to the nodes you are selecting, and that any required property has been calculated or assigned.
Make selections easier to trust
Build a query from the most distinctive condition first, then add constraints one at a time. A good progression might be element, then aromaticity, then chain or residue range. This makes it easier to see which condition changes the result and to spot a typo or an unexpectedly restrictive filter. Short names such as a.s and a.resi are convenient, while the longer forms—such as atom.symbol and atom.residueSequenceNumber—can make a query more self-explanatory when sharing it with a collaborator.
For the complete attribute list and additional examples, see the SAMSON atom attributes reference.
Note: SAMSON and all SAMSON Extensions are free for non-commercial use. Get SAMSON.