From Molecular Haystack to Target Atoms: Practical NSL Filters

Large molecular structures can make a simple modeling task unexpectedly tedious: isolate a chain, inspect a residue range, or focus on heavy atoms without clicking through the structure one atom at a time. SAMSON’s Node Specification Language (NSL) lets you describe those criteria as compact, repeatable expressions. The key is to combine a few atom attributes that answer one clear question at a time.

Atom attributes use the atom attribute space, which can be shortened to a. For example, atom.symbol O and a.s O both select oxygen atoms. The short forms are handy when expressions get longer; the full names can be easier to read when you are learning or sharing a query.

Start with a chain and residue range

When a structure contains several chains or a long sequence, narrow the selection using chain and residue identifiers. For example:

This combines chain A with residues 40 through 50. Add a heavy-atom condition when you want to leave hydrogens out:

Here, a.heavy means non-hydrogen atoms. This is useful for many structural inspections, while retaining hydrogens may be important for tasks where their positions or interactions matter.

Use alternatives instead of repeating a query

A comma-separated list matches any listed value. To find atoms in chain B or chain C, use a.c B, C. The same pattern works for residue numbers and element symbols: a.resi 40:50,100 includes a range and a separate residue number, while a.s O, N matches oxygen or nitrogen atoms.

Ranges and comparison operators help when the exact value is not known. For example, a.sn > 1000 filters by serial number, and a.oc < 0.3 filters by occupancy. Coordinate attributes can narrow by a region of space: a.x 0A:100A selects atoms whose x coordinate falls within the stated interval. Coordinates use length units, so include a unit such as A or nm to make the intended scale clear.

Make the chemical criterion explicit

Element and symbol are two ways to identify atoms by element. For instance, a.e Carbon uses the element name, while a.s C uses its symbol. To focus on aromatic carbon atoms, combine the symbol and aromatic attributes:

Other useful combinations include a.hba for hydrogen-bond acceptors and a.hbd for hydrogen-bond donors. These let you express a chemically meaningful filter rather than relying only on atom names or visual appearance.

Check what an attribute actually means

Some similarly named concepts are not interchangeable. a.het refers to atoms recorded as HETATM in the PDB file format; it does not simply mean “an atom whose element is unusual.” The documentation also gives not for excluding matches—for example, n.t a and not a.f selects atom nodes that are not fixed.

A few attributes depend on information that may need to be prepared first. Geometry must be computed before using a.g, and hybridization must be assigned before filtering with a.hy. Coarse-grained mass, radius, and type apply to coarse-grained atoms; they are not substitutes for the corresponding properties of ordinary atoms. These checks can explain why a valid-looking query returns fewer matches than expected.

A small habit that saves time

Build a filter in stages: first choose the chain, then the residue range, then add element or chemical-property criteria. This makes it easier to notice which condition removed an unexpected atom. Once the expression is right, keeping it as text also makes the selection easier to repeat or communicate to a colleague.

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.

Comments are closed.