A molecular structure can contain thousands of residues, but many modeling tasks begin with a much smaller question: Which residues belong to a particular secondary structure, have a certain charge, or fall within a sequence-number range? Finding the right subset by clicking through a complex model is slow—and it is easy to miss something.
SAMSON’s Node Specification Language (NSL) lets you describe the subset you want with a compact query. This guide focuses on residue attributes: practical ways to narrow a structure down, understand what each query matches, and avoid a common mix-up between selecting residues and selecting atoms.
Start with the residue property you know
Residue queries use the residue attribute space. Its short prefixes are res and r, so you can write expressions such as residue.type ALA or the shorter r.t ALA. The short form is handy when you are iterating on a query; the full form can be easier to read when sharing it with someone else.
For example, to find residues in alpha helices, use r.ss h. The documented aliases include alpha, a, helix, and h. To match beta strands, use r.ss b; for unstructured regions, use r.ss l (also written u or loop).
If you know the amino-acid identity, query by residue type: r.t HIS finds histidines, while r.t LYS, PRO matches lysines or prolines. For nucleic acids, the listed residue types include one-letter codes such as A, C, G, and U, as well as DNA codes such as DA and DT.
Use chemistry to narrow the search
When the question is about side-chain behavior rather than residue identity, charge and polarity can be more useful. For negatively charged amino-acid side chains, try r.c neg; for neutral or positive side chains, use r.c neu, pos. The full values are negative, neutral, and positive. The documentation also lists undefined for residues whose side-chain charge is not defined.
Polarity has its own attribute. For instance, r.p polar matches amino-acid residues with polar side chains, and r.p acidic, basic matches residues with acidic or basic side chains. These attributes are described as properties of amino-acid residues, so they are not general-purpose labels for every kind of residue in a structure.
Hydrophobicity can be used as a numeric criterion. The reference gives r.hydrophobicity < 0 as an example for identifying amino-acid residues below zero on the documented scale. Dissociation-related values are also available: for example, r.pI < 6.0 selects amino-acid residues with an isoelectric-point pH below 6.0. These can help turn a broad visual inspection into a repeatable filter.
Pinpoint positions and inspect model completeness
If you are tracking a known location in a structure, use the residue sequence number attribute: r.id == 42 matches sequence number 42. Ranges can be written as r.id 1:10, 20:30. The documentation identifies this as the residue sequence number (structure ID), which is useful when you already have a residue number from your structure or analysis notes.
For a quick completeness check, r.caab matches residues with complete amino-acid backbones. To distinguish standard PDB residue names from nonstandard ones, use r.srn and r.nsrn, respectively. These can help you focus an inspection on residues that may need special attention, without assuming that a nonstandard name is necessarily an error.
Residues and atoms are different targets
A useful detail: a residue query matches residues, not automatically the individual atoms inside them. If your next step concerns atoms, NSL examples show how to express that relationship. For example, n.t a in r.aa matches atoms in amino-acid residues. To find alpha-carbon atoms in valines, use "CA" in r.t VAL. This distinction helps prevent a query that identifies the right residues from being mistaken for one that directly returns the specific atoms you need.
A practical workflow is to begin with the clearest criterion—such as secondary structure, residue type, or sequence number—then inspect the returned set and refine it using chemistry or completeness attributes. Keeping each question explicit makes a selection easier to reproduce and communicate.
For the full attribute list, value aliases, and additional examples, see the SAMSON residue attributes reference.
Note: SAMSON and all SAMSON Extensions are free for non-commercial use. Get SAMSON.