From crowded structure to useful atoms: a practical NSL filtering workflow

A molecular structure can contain thousands of atoms, while a useful modeling task may concern only a few: the heavy atoms in one chain, a residue range, or atoms that can participate in hydrogen bonding. Selecting by eye is slow, and a selection that is too broad can make inspection and downstream work harder. SAMSON’s Node Specification Language (NSL) lets you combine atom attributes to describe the subset you want.

This workflow starts with a common goal: narrow a protein structure to potential hydrogen-bonding atoms in a specific region. It is a selection strategy, not a hydrogen-bond calculation. NSL identifies atoms that match the attributes in your expression; it does not by itself establish that two atoms are close enough or oriented correctly to form an interaction.

Build the selection in layers

NSL atom attributes use the atom attribute space, abbreviated as a. You can use the full attribute name or its short form. For example, atom.chain and a.c refer to the chain attribute, while atom.residueSequenceNumber and a.resi refer to the residue sequence number.

First, restrict the selection to a chain and a residue interval:

This matches atoms in chain A whose residue sequence numbers are between 40 and 50. A range is useful when you know the region of interest but do not want to enter every residue number individually. To select a few specific residue numbers instead, use a comma-separated list, such as a.resi 42, 45, 49.

Next, keep heavy atoms. The a.nonH attribute matches non-hydrogen atoms. Combine it with the region filter:

This can make a crowded structure easier to inspect by excluding hydrogens from the selection. It does not delete atoms or change the model; it only specifies which atoms match.

Focus on hydrogen-bond roles

NSL provides separate boolean attributes for hydrogen-bond acceptors and donors: a.hba and a.hbd. Combine them with the chain, residue range, and heavy-atom filter to select atoms in either role:

The parentheses make the intended grouping explicit: the atom must satisfy the chain, residue, and heavy-atom conditions, and it must match the acceptor or donor condition. If you want to inspect only one role, use a.hba or a.hbd on its own.

You can further narrow a selection using element symbols. For example, a.s O selects oxygen atoms, and a.s O, N selects oxygen or nitrogen atoms. Element filters can help when you want a quick visual check of particular atom types, but they are not substitutes for the donor and acceptor attributes: an element alone does not tell you which hydrogen-bond role an atom has.

Use structure records carefully

For structures with alternate atom locations, a.alt A selects atoms labeled with alternate location A. Chain IDs are also available as integers through a.ci, which is distinct from the character-based chain attribute a.c. If the structure contains multiple chains or alternate locations, adding these filters can help make the selection more specific.

Occupancy is another available filter. For example, a.oc < 0.3 matches atoms with occupancy below 0.3. Occupancy is a recorded structural attribute; use it as a filter when it is relevant to your analysis, rather than treating it as a universal measure of whether an atom is reliable.

A simple troubleshooting checklist

• Start with one condition, then add chain, residue, element, or role filters one at a time.
• Check whether you need a chain character (a.c) or a chain ID integer (a.ci).
• Use a.nonH when the task is easier to inspect without hydrogens; keep in mind that hydrogen atoms may matter for other analyses.
• Use a.hba and a.hbd to filter by assigned donor or acceptor properties, not to infer a completed interaction.
• Remember that some attributes require prior assignment or computation. For example, NSL’s geometry and hybridization attributes only help when those properties have been computed or assigned.

The benefit of composing filters is that each part of the expression has a clear purpose: location, atom type, or chemical role. You can adjust one condition without rebuilding the selection from scratch, and the resulting expression can be reused or shared with collaborators.

For the full attribute reference and more examples, see the SAMSON NSL atom attributes documentation.

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