When a molecular structure is large, locating the residues relevant to a question can become a task of its own. You may need to inspect only histidines, identify residues in helices, or find residues with a particular side-chain charge. Clicking through the structure one residue at a time is slow—and visual appearance alone does not tell you every property.
SAMSON’s Node Specification Language (NSL) lets you describe residue properties in compact expressions. The practical trick is to start with the question you want to answer, then choose the attribute that expresses it. Residue attributes use the residue space, commonly shortened to r.
Start with residue identity
To locate a particular amino acid type, use the type attribute. For example, r.t HIS matches histidine residues, while r.t LYS, PRO matches lysines and prolines. The full attribute name works too: residue.type ALA matches alanines.
This is useful when a question starts with “where are the…”: where are the histidines, which residues are lysines, or where are valines located? NSL also provides standard three-letter amino-acid codes and nucleotide residue codes, so the same attribute can describe different residue types listed in the reference.
Filter by structural context
Residue identity is only one part of the picture. To find residues assigned to a secondary-structure category, use r.ss. The documented values include alpha (also a, helix, or h), beta (also b, strand, or s), and unstructured (also u, loop, or l).
r.ss hmatches residues in alpha helices.r.ss a, bmatches residues in alpha helices or beta sheets.
These aliases make expressions shorter, but the full words can be easier to read when you return to a query later. Choose the spelling that makes your working expression clearest.
Use charge and polarity to narrow a question
For amino-acid side-chain charge, use r.c. The accepted categories are negative, neutral, positive, and undefined; shorter forms include neg, neu, pos, and un. For example, r.c neg matches amino acid residues with negatively charged side chains, and r.c neu, pos matches those with neutral or positive side-chain charge.
Polarity is a separate attribute, not another spelling of charge. Use r.p to query categories such as polar, nonpolar, acidic, and basic. For example, r.p polar matches residues with polar side chains. Keeping these two questions distinct helps avoid treating chemical classifications as interchangeable.
Know what a query matches
A small but important detail: r.t HIS describes residue nodes. If you need the alpha-carbon atoms in valine residues, the documentation gives an atom-level expression: "CA" in r.t VAL. Likewise, "CA" in r.ter matches alpha carbons in terminal residues. This distinction matters when you want to work with a whole residue versus a particular atom within it.
Residue attributes also describe different kinds of information. Some depend on the residue in its structure or system context, such as sequence number (r.id) and secondary structure (r.ss). Others depend on residue type, such as amino-acid classification (r.aa), charge, polarity, and hydrophobicity. For numeric attributes, NSL supports comparisons and ranges: examples include r.id 1:10 for sequence numbers from 1 to 10 and r.pI < 6.0 for residues with isoelectric-point values below 6.0.
A useful habit is to write the narrow question first—identity, structure, chemistry, or numbering—then use the matching attribute and check whether your target is a residue or an atom. That simple distinction makes residue searches easier to read and reduces accidental mismatches.
For the complete attribute list and additional examples, see the SAMSON residue attributes reference.
Note: SAMSON and all SAMSON Extensions are free for non-commercial use. Get SAMSON.