When a molecular structure is large, finding the residues you need by clicking through the model can be slow—and easy to get wrong. You might be looking for every lysine, a particular stretch of residue numbers, or residues in a helix. SAMSON’s Node Specification Language (NSL) lets you describe those targets as queries instead.
Residue queries use the residue attribute space. Its short names are res and r, so a query can use a readable full attribute name or a compact form such as r.t. Here are practical ways to turn common modeling questions into selections.
Start with residue identity
If you want to find a residue by its three-letter type, use r.t. For example, r.t LYS matches lysines, while r.t LYS, PRO matches lysines and prolines. The comma-separated values let you ask for several residue types in one query.
The documented type values include standard amino acid names such as ALA, GLY, and TRP, as well as nucleic acid codes such as A, DA, and DT. If you are checking a structure with modified or unusual residues, r.srn matches residues with standard PDB residue names; r.nsrn matches residues without them.
Find a sequence position—or a set of positions
Residue sequence numbers are available through r.id. To locate residue 42, use r.id == 42. To query more than one interval, use r.id 1:10, 20:30. This is useful when you know the relevant sequence regions but do not want to select each residue individually.
Remember that this attribute refers to the residue sequence number, also described as the structure ID. If the numbering in your structure is discontinuous or differs from the sequence numbering you expected, use the numbering shown by the structure rather than assuming it starts at one.
Filter by structural or chemical properties
For secondary structure, r.ss h finds residues in alpha helices. The aliases a, helix, and h refer to alpha structure; b, strand, and s refer to beta structure; and u, loop, and l refer to unstructured regions. For example, r.ss a, b asks for residues in alpha helices or beta sheets.
For amino acid side-chain properties, r.c neg matches residues with negative side-chain charge. r.c neu, pos matches neutral or positively charged side chains. Polarity has its own attribute: r.p polar selects polar side chains, while r.p acidic, basic selects acidic or basic side chains. These properties are defined for amino acid residues, so they are especially useful when narrowing a protein-focused search.
Other filters can help check structural completeness or chemistry. r.caab matches residues with complete amino acid backbones. Integer and floating-point attributes can be compared or given ranges: for instance, r.nat < 1000 tests the number of atoms, and r.pc 1.5:2.0 specifies a partial-charge range. The documentation also lists residue-level pKa and isoelectric-point attributes, such as r.pI < 6.0.
Be clear about what the query returns
A residue query and an atom query are not always the same thing. r.t VAL matches valine residues. By contrast, "CA" in r.t VAL matches alpha-carbon atoms, identified by the atom name CA, within valine residues. Likewise, n.t a in r.aa matches atoms in amino acid residues. This distinction matters when a later operation needs atoms rather than whole residues.
A simple way to work is to turn one modeling question into one query, then check whether the result is at the level you intended: residues, or atoms belonging to those residues. Use residue type and sequence number for identity and location; add structural, charge, or polarity properties when those are the real criteria. That makes selections easier to inspect, repeat, and share with collaborators.
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.