From crowded structure to focused selection: practical atom filters in SAMSON

When a molecular structure contains thousands of atoms, finding the few relevant ones can become a task of its own. You may need to isolate a chain, inspect a residue range, focus on likely hydrogen-bond partners, or hide hydrogens while keeping the rest of a model intact. In SAMSON, the Node Specification Language (NSL) lets you describe those targets as searchable criteria instead of selecting atoms one by one.

This guide focuses on a practical approach: start with a broad filter, add criteria to narrow it, and use the atom attributes that answer the question you actually have. Atom attributes use the atom space, often shortened to a. For example, atom.symbol O and a.s O both select oxygen atoms. Full names can be easier to read; short names are convenient when writing longer expressions.

Build a selection in steps

A useful query is often a combination of simple tests. Begin with a recognizable feature, then add conditions with and. For example, to find aromatic carbon atoms, use:

The first condition identifies carbon by element symbol; the second restricts the result to aromatic atoms. This is more precise than selecting all carbons, while still being easy to inspect and modify.

To focus on the backbone of a protein, the documentation provides a.aabb, which matches heavy atoms belonging to an amino-acid backbone. To narrow that selection to atoms named CA, combine the name test with the backbone attribute:

This illustrates a helpful habit: use a structural or chemical attribute to define the group, then add an atom-name or residue criterion only when needed.

Use ranges to target parts of a model

When you know the chain or residue numbers of interest, filter by those identifiers rather than relying on visual proximity. For example, a.c A selects atoms from chain A, while a.resi 40:50 selects atoms in the residue sequence-number range from 40 to 50. You can combine them:

This gives you a concise way to focus on a segment of one chain. The residue attribute refers to residue sequence numbers; it is not a general-purpose distance or spatial-neighborhood test.

For a coordinate-based region, use a.x, a.y, or a.z with length units. For example:

This selects atoms whose x and y coordinates are both greater than 10 angstroms. Coordinate filters can help isolate a region of the current structure, but remember that they refer to the coordinates in the model, so a changed position or orientation can change which atoms match.

Find chemically relevant atoms

NSL includes attributes that can help identify interaction-related atoms. Use a.hba for hydrogen-bond acceptors and a.hbd for hydrogen-bond donors. To focus on polar hydrogens, use a.hp; for non-polar hydrogens, use a.hnp. These filters are more informative than selecting every hydrogen or heteroatom when the question is about a particular interaction pattern.

For example, the query below combines an element filter with the water flag:

It selects oxygen atoms that have the water flag. That is distinct from simply selecting all oxygen atoms, which may also include oxygens in other molecules.

Check what the attribute depends on

Some attributes need preparation before they can be useful. Geometry must be computed before filtering with a.g, and hybridization must be assigned before using a.hy. The coarse-grained mass, radius, and type attributes apply only to coarse-grained atoms. If a query unexpectedly returns no matches, check whether the relevant information exists in the model and whether the attribute is applicable to those atoms.

Also distinguish attributes that sound similar. a.heavy means non-hydrogen atoms. a.het identifies atoms whose record type is HETATM in a PDB structure; it does not simply mean every atom that is not carbon or hydrogen. Choose the attribute that matches your intended definition.

A good workflow is to test a broad selection first, then add one condition at a time. This makes it easier to spot a mistaken chain ID, an unavailable computed property, or a filter that is narrower than intended. Once the expression behaves as expected, short names can make it more compact without changing its meaning.

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.