A molecular structure can contain hundreds or thousands of residues. When you need to inspect a particular class—say, every beta-strand residue, a specific residue type, or residues with a certain sequence number—finding them by eye is slow and easy to get wrong. SAMSON’s Node Specification Language (NSL) lets you describe those targets as queries, so you can make the selection criteria explicit and repeatable.
Residue queries use the residue attribute space. Its short forms are res and r, so an expression such as r.t ALA asks for alanine residues. The practical advantage is that you can search by several different kinds of information: residue identity, sequence number, secondary structure, or chemical properties.
Start with identity and structure
For a quick search by amino-acid type, use the residue’s three-letter code:
r.t HISfinds histidines.r.t LYS, PROfinds lysines and prolines.r.id 1:10, 20:30finds residues whose sequence numbers fall in either of the specified ranges.
Sequence numbers are useful when you already know which part of a structure you want to inspect. Remember that this attribute refers to the residue sequence number, also described as the structure ID. It is a different way to identify a residue than its chemical type: two residues can have the same type but different sequence numbers.
To find residues by their secondary structure, use r.ss. For example, r.ss h matches alpha-helix residues, while r.ss a, b matches residues in alpha helices or beta sheets. The aliases are handy when writing queries: alpha helix can also be written as alpha or helix, and beta strand as beta or strand. Unstructured regions can be queried with r.ss loop or r.ss u.
Be clear about what “charged” means
Two attributes that sound similar answer different questions. r.c describes the side-chain charge category of amino-acid residues. For example, r.c neg selects residues with negative side-chain charge, and r.c neu, pos selects those with neutral or positive side-chain charge.
By contrast, r.fc refers to the residue’s total formal charge. A query such as r.fc 6:8 asks for residues with formal charge between 6 and 8. If your scientific question is about side-chain behavior, use the charge category; if it is about total formal charge, use r.fc. Choosing the right attribute prevents a common source of confusing results.
You can also search by polarity with r.p. For instance, r.p polar matches amino-acid residues with polar side chains, while r.p acidic, basic covers acidic or basic side chains. These categories describe residue-type properties, rather than the residue’s position or secondary structure.
Target atoms through a residue query
Sometimes the task concerns an atom, but the criterion belongs to its parent residue. NSL supports that kind of query too. "CA" in r.t VAL matches alpha carbons by name in valine residues. Similarly, "CA" in r.ter matches alpha carbons in terminal residues. This is useful when you want an atom-level target while keeping the selection rule tied to residue identity or context.
Make queries easier to reuse
A good query states the biological criterion directly. Use a residue type when the target is defined by identity, r.id when it is defined by sequence numbering, r.ss for secondary structure, and the charge or polarity attributes for side-chain properties. Short names make repeated expressions compact, while the full attribute names can be easier to read when you are first building a query.
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.