When a molecular model gets crowded, finding the atoms relevant to one question can become a task of its own. You may want the protein backbone, a particular residue range, aromatic carbons, or hydrogen-bond acceptors—but selecting each atom by hand is slow and easy to get wrong. SAMSON’s Node Specification Language (NSL) lets you describe the atoms you want using chemical and structural attributes.
This guide focuses on a practical habit: start with a specific modeling question, translate it into one or more atom attributes, then combine those conditions into a readable query. The examples use the a shorthand for the atom attribute space. Atom attributes match atom nodes only.
Start with the chemical feature
For a quick search, select by element symbol. For example, a.s O matches oxygen atoms, while a.s O, N matches oxygen or nitrogen atoms. You can narrow that set by adding another condition:
a.s C and a.arfinds aromatic carbon atoms.a.s O and a.hbafinds oxygen atoms marked as hydrogen-bond acceptors.a.s H and a.hpfinds polar hydrogens.
This is useful when “all oxygens” is too broad for the task. The element condition identifies a chemical family; the second attribute refines it. NSL also supports full attribute names, such as atom.symbol O and atom.hydrogenBondAcceptor, if you prefer clarity over brevity.
Use structural context to narrow the search
Atoms are often meaningful because of where they sit in a structure. To focus on a chain and a residue interval, combine the chain and residue-sequence attributes:
a.c A and a.resi 40:50
This describes atoms in chain A whose residue sequence numbers are between 40 and 50. A list can specify alternatives: a.c B, C matches chain B or C, and a.resi 40:50,100 can express a range plus a separate residue number. Combining filters is a compact way to avoid selecting similarly named residues elsewhere in a structure.
For backbone-focused work, a.aabb matches heavy atoms belonging to an amino-acid backbone. The attribute already specifies heavy atoms, so there is no need to add a separate heavy-atom condition. For nucleic acids, a.nabb matches heavy atoms that belong to a nucleic-acid backbone.
Separate record labels from chemical meaning
The a.het attribute matches atoms whose structure record is HETATM in the PDB format. This is a record-type filter, not a general definition of “ligand”: it tells you how atoms are labeled in the structure file. If you need to identify a particular chemical feature, pair a structural filter with attributes that describe the atoms themselves. For example, a.w matches atoms with the water flag, and a.s O and a.w narrows that to water-flagged oxygen atoms.
Use numeric filters to describe a range
Many atom attributes can be queried with comparisons or ranges. For example, a.nba > 3 matches atoms with more than three bonded atoms, and a.oc 0.6:0.7 matches atoms with occupancy between 0.6 and 0.7. Coordinate attributes can also help define a region of interest: a.x 1nm:10nm matches atoms whose x coordinate falls within that interval. Length values can use units, so keep the units explicit when writing coordinate or radius filters.
Ranges are especially helpful when structure identifiers are not a single value. They also make a query easier to inspect later: a condition such as a.resi 40:50 communicates the intended interval at a glance.
Check whether an attribute needs preparation
Some useful descriptors depend on information that may not be available automatically. Geometry must be computed before using a query such as a.g tet for tetrahedral atoms. Hybridization must be assigned before using a.hy sp2; the documentation notes that hybridization might not be specified by default. If a query returns no matches, check both the expression and whether the required attribute has been computed or assigned.
A reliable workflow is to begin with one simple condition, confirm that it represents the intended atoms, and then add filters one at a time. This makes it easier to spot whether a restrictive condition—or a missing piece of assigned data—is responsible for an empty result. It also leaves you with a query that can be read and adjusted instead of a long string of unexplained criteria.
For the complete attribute reference and additional examples, see the SAMSON atom attributes documentation.
Note: SAMSON and all SAMSON Extensions are free for non-commercial use. Get SAMSON.
