A molecular structure can contain hundreds or thousands of residues, and the task is often not to inspect every one. You may need to locate a particular residue type, check whether a backbone is complete, or separate terminal residues from the rest. Doing that by eye is slow—and it is easy to miss a residue in a crowded model.
SAMSON’s Node Specification Language (NSL) lets you describe residue-level criteria as searchable expressions. The key is to choose attributes that answer a specific modeling question, then use the results to guide inspection.
Start with residue identity
When you know which residue types you want, the type attribute is a direct starting point. For example, r.t HIS matches histidines, while r.t LYS, PRO matches lysines and prolines. The documented type values also include the standard amino-acid codes, several nucleic-acid codes, and other listed residue names.
This is useful when checking a sequence position, focusing on residues that may be relevant to a specific modeling step, or narrowing a large structure to a manageable set. If you need atoms rather than whole residues, the expression "CA" in r.t VAL matches alpha carbons in valines. That distinction matters: a residue query identifies residue nodes, while the example with in targets atoms belonging to those residues.
Check backbone completeness
Missing atoms can complicate analysis and model preparation. The completeAminoAcidBackbone attribute provides a way to find residues according to whether they have a complete amino-acid backbone. The short form r.caab matches residues with complete backbones; use not r.caab to look for residues that do not meet that condition.
This is a useful first-pass check, not a substitute for reviewing the structure. A query identifies residues based on the attribute; it does not explain why a backbone is incomplete or determine how it should be repaired. Inspect the matches in context before deciding what to do next.
Use structure context
Residue sequence numbers can help you revisit a known location. For example, r.id == 42 matches residue sequence number 42, and r.id 1:10, 20:30 selects the documented ranges. The attribute is described as the residue sequence number (structure ID), so treat it as the numbering used by the structure rather than assuming it is a continuous biological sequence index.
Secondary structure offers another way to organize a search. r.ss h matches residues in alpha helices, while r.ss a, b matches alpha-helix and beta-strand residues. The available aliases include helix for alpha and strand for beta. Unstructured regions can be queried with r.ss loop.
For a quick check of chain ends, r.ter matches terminal residues. To target alpha carbons in all terminal residues, the documented example is "CA" in r.ter.
Flag unusual residue names
Standard and nonstandard residue names can be separated with r.srn and r.nsrn, respectively. This can help you find residues that deserve a closer look—for example, when reviewing a structure that contains modified or otherwise nonstandard components. A nonstandard name is a cue to inspect, not proof that the residue is erroneous.
A practical way to work
- State the question. Are you looking for a residue type, an incomplete backbone, a sequence position, or a structural feature?
- Choose the matching attribute. Use
type,completeAminoAcidBackbone,residueSequenceNumber,secondaryStructure, or another relevant attribute. - Run a focused expression. Start with a simple query such as
r.t HISornot r.caab. - Inspect the matches in context. NSL helps locate candidates; scientific judgment determines whether they need attention.
These examples turn residue searches into repeatable, explicit criteria instead of a visual scavenger hunt. For the complete attribute list and syntax examples, see the SAMSON residue attributes reference.
Note: SAMSON and all SAMSON Extensions are free for non-commercial use. Get SAMSON.
