Finding the right atoms in a molecular structure can become tedious when a selection depends on remembering atom names, residue numbering, or chain labels. Names are useful, but they do not always describe what an atom does. In SAMSON, the Node Specification Language (NSL) lets you combine atom attributes—such as element, chain, residue number, and hydrogen-bond role—to make a selection that expresses your intent.
This is especially helpful when you need to inspect a particular chemical feature across a structure, or narrow a broad selection without clicking atoms one at a time. The examples below focus on practical ways to build and refine atom queries.
Start with the question, not the atom name
Atom attributes belong to the atom attribute space. You can write the full form, such as atom.symbol, or use its short form, a.s. NSL expressions can combine conditions with and and not; a comma can list alternative values for an attribute.
For example, to match oxygen atoms, use a.s O. To match oxygen or nitrogen atoms, use a.s O, N. These express element identity directly, rather than relying on a particular atom-label convention.
Narrow a selection by chain and residue
Suppose you want the oxygen atoms in residue 42 of chain A. Combine the three relevant attributes:
a.c A and a.resi 42 and a.s O
Here, a.c is the chain attribute, a.resi is the residue sequence number, and a.s is the element symbol. This kind of query is useful when several chains contain residues with the same number: the chain condition helps make the target unambiguous. To include oxygen and nitrogen in that residue, replace the final condition with a.s O, N.
Residue and chain identifiers are structural identifiers, not descriptions of chemical function. Pairing them with an element or another relevant attribute makes the selection more specific and easier to understand later.
Find atoms by interaction role
When investigating possible hydrogen-bonding sites, start with the role flags rather than guessing from atom names. The query a.hba matches atoms marked as hydrogen-bond acceptors, while a.hbd matches atoms marked as hydrogen-bond donors. To restrict acceptors to oxygen or nitrogen atoms, combine the conditions:
a.hba and a.s O, N
For polar hydrogens, use a.hp. For donor-linked hydrogens, use a.dbh. These attributes help identify relevant atoms for inspection, but a selection by itself does not establish that two atoms form a hydrogen bond or that their positions are geometrically suitable. Treat the query as a way to locate candidates, then inspect the molecular context.
Use conditions that reflect the feature you need
NSL also includes attributes for aromaticity, backbone membership, ring membership, formal charge, and bonded-atom counts. For instance, a.ar and a.s C matches aromatic carbon atoms. The query a.aabb selects heavy atoms belonging to an amino-acid backbone, and a.inRing selects atoms in rings. These properties can help you move from a general selection to a more chemically meaningful one.
Some attributes depend on information being available or computed. Geometry needs to be computed before queries such as a.g tet can use it, and hybridization may need to be assigned before a.hy sp2 is useful. SYBYL-type selections similarly require SYBYL types to be assigned. If a query returns fewer atoms than expected, check whether the needed property is present—not just whether the expression is spelled correctly.
A small habit that saves time
Build selections in stages: begin with the broad chemical feature, then add context such as chain, residue, or element. If the result is unexpectedly broad, add another condition; if it is empty, temporarily remove conditions one by one to see which narrows the match too far. This makes the selection easier to debug and helps keep the final expression readable.
Atom attributes match atom nodes, so use them when the target is an atom-level feature. The full reference includes the available attributes, short names, value types, and additional examples: SAMSON NSL atom attributes.
Note: SAMSON and all SAMSON Extensions are free for non-commercial use. Get SAMSON.