A molecular structure can contain thousands of atoms, while a modeling task may concern only a small subset: aromatic carbons, backbone atoms, water oxygens, or atoms in a particular region. Picking atoms one by one is slow and hard to repeat. SAMSON’s Node Specification Language (NSL) lets you describe the atoms you want with attribute-based expressions—and refine the selection as your question becomes more specific.
Start with a chemical feature
Atom attributes can describe an element, a structural role, or a property such as aromaticity. For example, this expression matches aromatic carbon atoms:
|
1 |
a.s C and a.ar |
a.s is the short name for the atom symbol attribute, and a.ar is the short name for aromaticity. The expression combines them with and, so an atom must satisfy both conditions. To look for atoms that are hydrogen-bond acceptors, use a.hba; for donors, use a.hbd. These can be combined with element filters too, such as a.s O and a.hba, when you want to narrow a selection to oxygen acceptors.
Use structural context to narrow the search
Chemical identity alone may not distinguish the atoms you need. Add context such as chain, residue, or backbone membership. For example, a.c A and a.aabb combines chain A with the amino-acid backbone attribute. The documentation defines a.aabb as matching heavy atoms that belong to an amino-acid backbone, so this is a way to focus on that structural subset without including backbone hydrogens.
For nucleic acids, the corresponding backbone attribute is a.nabb. It also matches heavy backbone atoms. Chain and residue sequence number can be useful together: a.c A and a.resi 40:50 describes atoms in chain A whose residue sequence number falls in the 40–50 range.
Make a spatial selection with coordinates
When the area of interest is defined by position rather than chemistry, coordinate attributes can help. For example, a.x 1nm:10nm matches atoms whose x coordinate is between 1 and 10 nanometers. You can combine coordinate conditions to describe a rectangular region:
|
1 |
a.x > 10A and a.y > 10A |
This example places lower bounds on x and y; it does not, by itself, define a complete three-dimensional box. Add the relevant limits for the remaining coordinates or directions when you need a more constrained region. Coordinate attributes accept length units, so keep units explicit when writing and comparing ranges.
Separate water from other oxygen atoms
An oxygen symbol alone can match many chemically different atoms. If you specifically want oxygen atoms carrying the water flag, use a.s O and a.w. The documentation also gives a.s O in wat as a way to match oxygen atoms in water. This illustrates a useful habit: combine an element filter with a structural or category attribute when a broad element match would include too much.
Check what an attribute actually means
Some similar-sounding attributes answer different questions. a.het identifies atoms whose structure record is HETATM in the PDB file format; it is not simply a general test for “not carbon or hydrogen.” The documentation shows n.t a and not (a.s H, C) as a separate example for matching atom nodes that are not hydrogen or carbon. Likewise, a.f matches fixed atoms, while the older a.mo mobile attribute is deprecated; use a.f when asking about fixed status.
Build queries in small steps
A practical way to work is to begin with one clear criterion, then add another only when needed. Start with an element, inspect whether the result is too broad, and then add a property such as aromaticity, a chain, or a residue range. For numerical attributes—such as occupancy, temperature factor, partial charge, or the number of bonded atoms—you can use comparisons and ranges. For instance, a.oc < 0.3 selects atoms with occupancy below 0.3, while a.nba > 2 selects atoms with more than two bonded atoms.
Not every attribute is ready to query immediately. The documentation notes that geometry must be computed before using a.g, and hybridization must be assigned before using a.hy; hybridization may not be specified by default. If a query returns fewer atoms than expected, check whether the relevant property has been calculated or assigned, as well as whether the attribute matches the kind of node you intend to select.
For the full attribute list, syntax details, and additional examples, see the SAMSON atom attributes reference.
Note: SAMSON and all SAMSON Extensions are free for non-commercial use. Get SAMSON.