From a crowded structure to the atoms you actually need

A molecular structure can contain thousands of atoms, and the difficult part is often not seeing them—it is narrowing the model to the atoms relevant to a question. Are you inspecting a protein backbone, isolating a ligand-like set of heavy atoms, or checking a region of space? Selecting by one property at a time can leave you with too much noise or miss the atoms you intended to find.

In SAMSON, the Node Specification Language (NSL) lets you describe atom selections as readable expressions. This guide focuses on a practical approach: combine atom type, structural context, and location to make a query more specific, then use the available attributes to troubleshoot it.

Start with the atom, then narrow the search

Atom attributes live in the atom attribute space, abbreviated a. For example, a.s O selects oxygen atoms, while a.heavy matches heavy atoms—atoms that are not hydrogen. Combining conditions with and narrows the match:

This example is deliberately simple: since oxygen is already a non-hydrogen element, the heavy-atom condition is redundant here. But the pattern is useful when building more complex selections. For instance, to focus on heavy atoms in an amino-acid backbone, use:

The backbone attribute specifically matches heavy atoms belonging to an amino-acid backbone. To further limit the selection to a chain and residue-number interval, add those conditions:

This reads as: heavy backbone atoms in chain A, within residues 40 through 80. Combining criteria turns a broad selection into a more useful working set without requiring you to manually pick atoms one by one.

Use chemical properties to find a subset

NSL also supports chemical and bonding attributes. To identify aromatic carbon atoms, combine the element symbol with the aromatic flag:

To search by local bonding patterns, use attributes such as a.nba (number of bonded atoms), a.nbo (number of bonded oxygens), or a.nbh (number of bonded hydrogens). For example:

This matches atoms with exactly two bonded oxygen atoms. You can also use comparisons and ranges, such as a.nba > 2 or a.fc -1, 1 for atoms with either of those formal charges. These filters are useful when a selection depends on local chemistry rather than residue identity alone.

Be precise about what “heteroatom” means

One common source of confusion is treating “heteroatom” as a single, unambiguous filter. The a.het attribute means an atom has a HETATM record in a Protein Data Bank file. That is a record-type distinction, not simply a test for atoms that are not carbon or hydrogen. If your goal is to select atoms by element instead, specify the symbols directly—for example, not (a.s H, C) matches atoms that are neither hydrogen nor carbon. Choose the condition that matches the question you are asking.

Limit selections by position

When investigating a binding site or another spatial region, coordinate attributes let you constrain atoms by their x, y, and z positions. Units matter: NSL examples include angstroms (A), nanometers (nm), and picometers (pm). For example, this selects atoms with x coordinates between 1 and 10 nanometers:

You can combine coordinate filters with and to define a box along multiple axes:

These conditions constrain x and y; they do not, by themselves, define a three-dimensional box. Add a z condition when the region needs a bound along that axis, and check that the units are consistent across the expression.

A few checks before trusting a query

• Confirm the attribute fits the atoms. Coarse-grained mass, radius, and type attributes apply to coarse-grained atoms; they are not general substitutes for the corresponding atom properties.
• Check whether a property must be assigned or computed. Geometry must be computed before using a.g, and hybridization may need to be assigned before using a.hy.
• Separate backbone selection from atom-name selection. The backbone flag can be combined with a name or other attribute when you need a narrower match.
• Use the full attribute name if a short name is unclear. NSL supports names such as atom.residueSequenceNumber as well as abbreviations such as a.resi.

A good atom query is a compact statement of the selection criteria you would otherwise have to apply manually. Start broad, add one condition at a time, and make sure each condition represents the structural or chemical property you actually intend to filter.

For the complete list of atom attributes, values, and examples, see the SAMSON atom attributes reference.

Note: SAMSON and all SAMSON Extensions are free for non-commercial use. Get SAMSON.