When a structure contains thousands of atoms, finding the handful you need can become a task of repeated clicking: isolate a chain, check an element, exclude hydrogens, and then try to locate a particular chemical feature. SAMSON’s Node Specification Language (NSL) lets you express these criteria as a readable query instead. The payoff is not just speed: a selection written as a query is easier to inspect, adjust, and reuse.
Atom attributes live in the atom attribute space. You can write the full form, such as atom.symbol O, or use the shorter form, a.s O. These attributes match atom nodes only.
Start with the chemical question
A useful query begins with the distinction you actually need—not with a long list of atoms to click. For example, to find oxygen atoms, use:
|
1 |
a.s O |
To narrow that to oxygen atoms marked as water, combine the element and water attributes:
|
1 |
a.s O and a.w |
This kind of combination is valuable when a structure includes solvent: you can ask for a specific element and a structural flag, rather than treating every oxygen as equivalent. Similarly, a.s C and a.ar matches aromatic carbon atoms.
Make broad selections manageable
For many inspection and preparation tasks, hydrogens add visual clutter. The heavy attribute provides a direct way to select non-hydrogen atoms:
|
1 |
a.heavy |
You can combine it with backbone membership. For example, a.aabb matches heavy atoms belonging to an amino-acid backbone, while a.nabb matches heavy atoms belonging to a nucleic-acid backbone. These queries can help focus a crowded model on its structural framework.
When you need atoms that are not carbon or hydrogen, the documentation gives this query:
|
1 |
node.type atom and not (atom.symbol H, C) |
The comma-separated symbols mean hydrogen or carbon; not excludes both. This illustrates a practical pattern: use and to narrow a selection, commas to list alternatives for an attribute, and not to remove unwanted matches. Parentheses make the excluded group explicit.
Use structure and location as filters
Chemical identity is only one way to describe a useful selection. To select atoms from chain A, use a.c A. To select atoms whose residue sequence numbers fall from 40 to 50, use a.resi 40:50. These filters can be combined with element or backbone criteria to focus on a particular part of a macromolecule.
Coordinates are also searchable. For instance, a.x 1nm:10nm selects atoms whose x coordinate is in that interval. To require both x and y coordinates to be greater than 10 angstroms, use:
|
1 |
a.x > 10 A and a.y > 10 A |
Coordinate queries are handy when you already know the region of interest, but remember that they describe positions in the current coordinate frame. A spatial cutoff is not the same as a chemical relationship such as bonding.
Check what a query depends on
Some attributes describe stored or computed properties rather than simple element identity. Geometry must be computed before using a.g, and hybridization must be assigned before using a.hy; hybridization may not be specified by default. For example, after the relevant property is available, a.g tet can match tetrahedral geometry and a.hy sp2 can match SP2 hybridization. A query cannot return meaningful matches for a property that has not been prepared.
A practical habit is to build a selection in stages: begin with a broad attribute, add one criterion at a time, and check whether each addition narrows the result as expected. For example, start with a.s O, then add and a.w if you want only water-flagged oxygen atoms. This makes it easier to spot an overly restrictive condition or a property that has not been assigned.
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.
