A large molecular structure can make a simple question surprisingly time-consuming: Where are the lysines? Which residues form helices? Which residues are at a chain end, or belong to a particular sequence-number range? Clicking through residues one at a time is slow, and broad searches can return more than you need.
SAMSON’s Node Specification Language (NSL) lets you describe residue properties as compact queries. The useful shift is to search by the feature you care about—residue identity, secondary structure, sequence number, or classification—rather than trying to find each residue manually. These examples use the residue attribute space, which can be written as residue, res, or r.
Start with residue identity
To find one or more residue types, use the type attribute. For example, r.t LYS matches lysines, while r.t LYS, PRO matches lysines and prolines. The full form, residue.type LYS, spells out the attribute name; the short form is quicker when you already know the NSL abbreviations.
This is handy when investigating a residue of interest across a protein, or when you want to inspect several types together. The documented values include the standard three-letter amino acid names, as well as nucleic-acid residue codes.
Separate backbone structure from sequence position
Residue type answers “what is it?” Secondary structure answers “what shape is this region assigned?” Use r.ss h to match residues in alpha helices; h is an alias for helix or alpha. To include beta strands as well, use r.ss a, b. The available groups also include unstructured regions, which can be queried with r.ss loop or the alias r.ss u.
If the question is about numbering rather than shape, use r.id, the short name for residueSequenceNumber. For example, r.id 1:10, 20:30 matches residues numbered 1–10 and 20–30. This can narrow attention to selected sequence regions without having to list every number individually.
Check the ends and the naming
Terminal residues are matched with r.ter. If you need their alpha-carbon atoms rather than the residues themselves, the documented expression is "CA" in r.ter. This illustrates an important distinction: a residue query can identify a group, while an in expression can select atoms belonging to residues that meet that criterion.
Residue names can also help distinguish standard names from nonstandard ones. r.srn matches residues with standard PDB residue names, and r.nsrn matches those without standard names. These can be useful checks when a structure includes modified or otherwise unusual residues.
Use chemical categories for a more focused search
For amino acids, r.c neg matches residues with negatively charged side chains; r.c neu, pos matches neutral or positively charged side chains. Polarity is available through r.p: for instance, r.p acidic, basic matches acidic or basic side chains, and r.p polar matches polar side chains. These are residue-type properties, so they help organize a search by category rather than by a list of individual amino acid names.
For nucleic acids, r.dna and r.rna match DNA and RNA residues, respectively. To match atoms within amino-acid residues, the documented expression is node.type atom in residue.aminoAcid (short form: n.t a in r.aa).
A practical way to approach a residue search
Begin with the biological question, then choose the matching attribute: r.t for identity, r.ss for secondary structure, r.id for sequence number, r.ter for terminal status, or r.c and r.p for charge and polarity. Use the full attribute names when they are easier to remember, and the short names when you want concise expressions. If you are unsure which values an attribute accepts, check its reference table before constructing a query; for example, secondary-structure values have several aliases, while numeric attributes accept comparisons and ranges.
These queries turn common structure-inspection questions into reusable, readable filters. For the complete list of residue attributes and examples, see the SAMSON residue attributes reference.
Note: SAMSON and all SAMSON Extensions are free for non-commercial use. Get SAMSON.