Large molecular structures can make a simple modeling task feel like a search problem: locate a particular residue, inspect a region of a chain, or focus on residues with a specific structural or chemical property. SAMSON’s Node Specification Language (NSL) lets you describe those targets with residue attributes, so you can filter by identity, sequence number, secondary structure, charge, and more.
The useful shift is to start with the residue you care about, rather than trying to identify every atom individually. In residue queries, the attribute space can be written as residue, res, or r. The shorter form is convenient for repeated searches.
Start with residue identity
To find a particular amino acid type, use the residue type attribute. For example, r.t HIS matches histidines, while r.t LYS, PRO matches lysines or prolines. The comma-separated values in these examples let you ask for more than one type in the same query.
Sequence numbering is another direct way to navigate a structure. Use r.id == 42 to match residue number 42. To target two intervals, use r.id 1:10, 20:30. This is helpful when you know the structure IDs you want to inspect, though the numbers refer to residue sequence numbers—not a guarantee that every structure uses an uninterrupted numbering scheme.
Use structure to narrow the search
If you are checking a secondary-structure region, r.ss h matches alpha-helical residues. The aliases alpha, a, helix, and h are equivalent values. For beta strands, use r.ss b; for unstructured regions, use r.ss u. You can request both helices and strands with r.ss a, b.
Two other structural checks can be useful when inspecting a model. r.caab matches residues with a complete amino-acid backbone, and r.ter matches terminal residues. These attributes can help focus attention on backbone completeness or chain ends before you continue with a more detailed inspection.
Filter by residue chemistry
For amino-acid side-chain properties, r.c describes charge and r.p describes polarity. For instance, r.c neg matches residues with negatively charged side chains, while r.c neu, pos matches neutral or positively charged side chains. To find polar residues, use r.p polar; r.p acidic, basic selects residues with acidic or basic side chains.
Hydrophobicity and dissociation-related values can also be queried numerically. For example, r.hydrophobicity < 0 selects amino-acid residues below zero on the documented Kyte–Doolittle-based scale. r.pI < 6.0 matches residues with an isoelectric point below 6.0, and r.pKa1 1.5:2.0 matches the stated pKa1 interval. These are residue-type properties, so they are shared by residues of the same type.
When you need atoms, query through residues
A residue-level search does not mean you have to stop at the residue. The documentation shows how to match atoms by name within a residue type: "CA" in r.t VAL matches alpha carbons in valines. Similarly, "CA" in r.ter matches alpha carbons in terminal residues. This distinction is useful when the modeling task concerns a specific atom, but the reliable way to find it is through the residue it belongs to.
In practice, begin with the clearest property you know—identity, sequence number, structure, or chemistry—then use the result to guide your next inspection. The residue attribute reference includes inherited attributes such as visibility and selection, as well as the complete list of available residue filters and examples. Learn more in the SAMSON residue attributes documentation.
Note: SAMSON and all SAMSON Extensions are free for non-commercial use. Get SAMSON.