When a molecular structure contains hundreds or thousands of residues, finding the few relevant to a question can become a tedious search. You might need to inspect a particular amino acid, trace a sequence range, or distinguish charged side chains from residues with a particular formal charge. SAMSON’s Node Specification Language (NSL) lets you describe those targets with residue attributes instead of relying on manual browsing.
The useful first step is to think about what kind of property you need. NSL’s residue attributes include properties inherited from nodes and structural groups, properties that depend on the current structure, and properties determined by residue type. That distinction helps prevent a common mix-up: two attributes that sound related may answer different questions.
Start with residue identity
To find residues by their three-letter type, use r.t. For example, r.t ALA matches alanines, while r.t LYS, PRO matches lysines and prolines. This is useful when you already know which residue names you want to inspect.
You can also use a residue query to describe atoms within matching residues. The expression "CA" in r.t VAL matches alpha carbons named CA in valines. This illustrates an important practical idea: the residue can define the context, while the name identifies a particular atom within that context.
Find residues by structural role
If your question is about protein shape rather than sequence identity, use r.ss for secondary structure. The values include alpha (also helix or h), beta (also strand or s), and unstructured (also loop or l). For example, r.ss h matches residues in alpha helices, and r.ss a, b matches residues in alpha helices or beta sheets.
For sequence-based inspection, r.id refers to the residue sequence number, also described as the structure ID. A query such as r.id 1:10, 20:30 matches residues in either of those number ranges. This can help when you want to focus attention on selected stretches rather than scan an entire chain. The documentation also shows equality syntax, as in r.id == 42.
Be precise about charge and polarity
Charge and formal charge are not interchangeable in this reference. r.c describes amino-acid side-chain charge, with values such as negative, neutral, and positive. For instance, r.c neg matches amino-acid residues with negatively charged side chains.
By contrast, r.fc refers to a residue’s total formal charge and accepts integer comparisons or ranges, such as r.fc > 1 or r.fc 6:8. If you are investigating side-chain chemistry, use the charge attribute; if you mean total formal charge, use formal charge. Checking which question you are asking before writing the query can save time and avoid misleading selections.
Polarity is another type-based filter. r.p polar matches amino acids with polar side chains, while r.p acidic, basic matches residues with acidic or basic side chains. For hydrophobicity, the documentation provides the expression r.hydrophobicity < 0; the attribute is based on the Kyte–Doolittle hydrophobicity scale.
A small checklist for useful queries
- Use
r.twhen the residue name is the key fact. - Use
r.sswhen you are grouping residues by secondary structure. - Use
r.idwhen you want specific sequence-number ranges. - Choose between
r.candr.fcbased on whether you mean side-chain charge or total formal charge. - Use full attribute names or their short forms; the short names make repeated queries more compact.
These attributes give you a more deliberate way to narrow a structure to the residues relevant to your analysis. For the complete list of residue attributes, possible values, and examples, see the SAMSON residue attributes reference.
Note: SAMSON and all SAMSON Extensions are free for non-commercial use. Get SAMSON at www.samson-connect.net.