A molecular structure can contain thousands of residues. When you need to inspect only the charged side chains, identify a helix, or find a particular residue by its sequence number, clicking through the structure one residue at a time is slow and easy to get wrong. SAMSON’s Node Specification Language (NSL) lets you describe the residues you want with searchable attributes instead.
The key is to start with the question you are trying to answer. Are you looking for a residue by identity, location in the sequence, structural role, or a chemical property? The residue attribute space—also written res or r—provides ways to express each of these kinds of criteria.
Start with residue identity
If you know the three-letter residue name, use r.t. For example, r.t HIS matches histidines, and r.t LYS, PRO matches lysines and prolines. The available types also include standard amino acids, several ambiguous amino-acid codes, and nucleic-acid residue codes such as A, U, and DA.
This is useful when a modeling task is tied to specific residues—for example, when you want to focus on histidines before inspecting their local environment. If you need the alpha-carbon atoms rather than the residues themselves, the documented expression "CA" in r.t VAL matches alpha carbons in valine residues. That distinction matters: a residue query finds residue nodes, while an expression using in can target nodes contained in matching residues.
Use sequence numbers carefully
To locate a residue by its structure ID, use r.id. The expression r.id == 42 selects the residue with sequence number 42. You can also specify ranges, as in r.id 1:10, 20:30, to match residues numbered 1 through 10 and 20 through 30.
This is a practical way to return to a region you have already identified. Keep in mind that this attribute is described as the residue sequence number, or structure ID. It is not a description of chemical identity: use r.t when the residue type is what matters.
Separate charge from formal charge
“Charge” can mean more than one thing in a structure, and NSL distinguishes two useful attributes. r.c classifies amino-acid residues by the charge of their side chain: r.c neg finds negatively charged side chains, while r.c neu, pos finds neutral or positively charged ones. The full values include negative, neutral, positive, and undefined.
By contrast, r.fc searches by a residue’s total formal charge, using integer values. For example, r.fc 1 matches residues with formal charge equal to 1. These attributes answer different questions; choosing the right one prevents a side-chain classification from being confused with a total formal-charge value.
Filter by structure and chemistry
For secondary structure, use r.ss: r.ss h matches alpha-helical residues, and r.ss a, b matches alpha helices and beta strands. The aliases are handy: helix and alpha refer to the same category, as do strand and beta. Loops are represented by unstructured, with aliases including loop and l.
For a chemical-property search, r.p describes amino-acid side-chain polarity. For instance, r.p polar matches polar side chains, while r.p acidic, basic matches acidic or basic side chains. Hydrophobicity is available as a floating-point attribute; the documented example r.hydrophobicity < 0 selects residues below zero on the cited scale.
A simple way to build a useful query
First decide what you want to select: a residue type, a numbered region, a structural feature, or a chemical category. Then choose the matching attribute and test a focused expression—for example, r.t LYS, r.id 20:30, or r.ss beta. If you need atoms within matching residues, use a documented containment expression such as "CA" in r.t VAL. Keeping each question explicit makes it easier to understand what a selection means and to revise it when your analysis changes.
For the complete residue attribute reference and additional examples, see the SAMSON residue attributes documentation.
Note: SAMSON and all SAMSON Extensions are free for non-commercial use. Get SAMSON.
