From molecular haystack to useful shortlist: residue queries in SAMSON

Finding the residues you care about in a large molecular structure can be surprisingly tedious. A residue may be important because of its identity, position in the sequence, secondary structure, charge, or polarity—and those properties are not always obvious from a crowded 3D view. In SAMSON, the Node Specification Language (NSL) lets you describe those criteria as queries instead of searching residue by residue.

This guide focuses on a practical question: how can you narrow a structure to residues with a property you can name? The examples use the residue attribute space, written as residue, res, or r. Residue queries match residue nodes. If you need atoms belonging to a matching kind of residue, NSL also supports expressions such as node.type atom in residue.aminoAcid.

Start with identity, not appearance

When you know the residue type, query it directly. For example, r.t HIS finds histidines, while r.t LYS, PRO matches lysines and prolines. This is useful when a structural question names specific amino acids but the corresponding residues are difficult to locate visually.

Some tasks call for a broader category rather than a particular residue. Use r.aa for amino acid residues, r.na for nucleic acid residues, or r.dna and r.rna to distinguish DNA from RNA. To find atoms within amino acid residues, use the documented form n.t a in r.aa.

Use structure when the question is structural

Residue sequence numbers provide a direct route to a known region. r.id == 42 matches the residue with sequence number 42. A set of ranges can be expressed as r.id 1:10, 20:30. This can help you revisit a region identified in a paper, structure annotation, or analysis without manually counting along a chain.

Secondary structure is another useful filter. r.ss h matches alpha-helical residues, and r.ss a, b matches residues in alpha helices or beta sheets. The aliases make expressions compact: h means helix, while b means beta strand. For a terminal residue, use r.ter; to identify alpha-carbon atoms in terminal residues, the documented expression is "CA" in r.ter.

Distinguish charge, polarity, and formal charge

These attributes sound similar, but they answer different questions. The r.c attribute describes amino-acid side-chain charge: r.c neg matches negative side chains, and r.c neu, pos matches neutral or positive ones. The r.p attribute describes side-chain polarity. For example, r.p polar selects polar side chains, while r.p acidic, basic matches acidic or basic side chains.

By contrast, r.fc refers to a residue’s total formal charge. For instance, r.fc > 1 selects residues with formal charge greater than 1. Keeping these terms separate helps prevent a common interpretation error: side-chain classification is not the same as total formal charge.

Turn a property into a range

Many residue attributes accept numeric comparisons or ranges. For example, r.nC < 10 matches residues with fewer than 10 carbon atoms, and r.pc 1.5:2.0 searches for partial charge values in that interval. Amino-acid properties can also be queried numerically: r.pI < 6.0 matches residues with an isoelectric point below 6.0, while r.hydrophobicity < 0 selects residues below zero on the documented hydrophobicity scale.

Numeric ranges are especially useful when the scientific question is approximate rather than tied to one exact value. Instead of inspecting each residue’s property individually, state the interval you want and use the result as a focused shortlist for your next step.

A small workflow that saves repeated searching

  1. Name the property. Is the target a residue type, sequence number, secondary structure, or chemical classification?
  2. Choose the matching attribute. For example, use r.t for type, r.id for sequence number, r.ss for secondary structure, and r.p for polarity.
  3. Use the simplest exact expression. Start with a single documented criterion, such as r.t HIS or r.ss h, so the meaning of the selection stays clear.
  4. Check the level you are matching. A residue query finds residues; an expression using in can target atoms belonging to residues with a specified property.

These queries do not replace scientific judgment: they make the search criteria explicit and repeatable, so you can spend less time locating candidates and more time evaluating whether they matter to your model.

For the complete residue attribute reference and additional examples, see the SAMSON residue attributes documentation.

Note: SAMSON and all SAMSON Extensions are free for non-commercial use. Get SAMSON.

Comments are closed.