A molecular structure can contain thousands of residues, and the one you need may be defined by more than its name. You might want to find every lysine, isolate residues in a helix, identify nonstandard residue names, or locate residues with a particular charge. Repeatedly scanning the structure by eye is slow—and it is easy to miss something.
SAMSON’s Node Specification Language (NSL) lets you describe residue properties as searchable expressions. The useful trick is to choose the attribute that matches the question you are asking, then be clear about whether you want residues or atoms inside those residues.
Start with the residue type
For a familiar amino acid, use the type attribute. Its short form is r.t. For example, r.t LYS matches lysine residues, while r.t LYS, PRO matches lysines and prolines. The accepted types include standard three-letter amino acid codes, some less common amino acid codes, and nucleic acid codes such as A and DA.
This is handy when the residue identity is the whole requirement. If you are trying to find a chemical or structural category instead, a more specific attribute can make the intent clearer.
Filter by chemistry, not just by name
Use r.c to search amino acid residues by side-chain charge. For example, r.c neg matches residues with negatively charged side chains, and r.c neu, pos matches those with neutral or positive side-chain charge. The longer names—negative, neutral, and positive—are available too.
For side-chain polarity, use r.p. The expression r.p polar matches residues with polar side chains; r.p acidic, basic matches residues with acidic or basic side chains. These attributes describe amino acid residue categories, so they are more directly useful for questions about amino acid chemistry than a raw atom count.
You can also search by hydrophobicity or dissociation constants. For instance, r.hydrophobicity < 0 selects amino acid residues with negative hydrophobicity values, and r.pI < 6.0 selects residues with an isoelectric-point value below 6.0. A numeric interval is another option: r.pKa1 1.5:2.0 matches values in that range. These attributes can help narrow a search when a residue label alone is not enough.
Use structure context
Residue identity does not tell you where a residue sits in the structure. The r.ss attribute searches secondary structure: r.ss h matches alpha-helical residues, and r.ss a, b matches residues in alpha helices or beta strands. The aliases make the expressions compact, but the full terms—such as helix and beta—are also supported.
Other context-specific attributes include r.ter for terminal residues, r.caab for residues with a complete amino acid backbone, and r.id for residue sequence numbers. For example, r.id 1:10, 20:30 searches two sequence-number ranges. Sequence numbers are useful when you already know which sections of a chain you want to inspect.
Residue matches versus atom matches
A common source of confusion is the difference between finding a residue and finding atoms that belong to it. Expressions such as r.t VAL describe valine residues. If you need the alpha-carbon atoms in those residues, use "CA" in r.t VAL. Similarly, n.t a in r.aa matches atoms in amino acid residues, rather than returning only the residue objects themselves.
This distinction matters when the next step in your workflow acts on atoms—for example, when you want to work with a particular named atom—or when you simply need to identify whole residues. Before running a query, ask: “Am I looking for a residue, or for atoms contained in matching residues?”
A practical way to build a search
-
Write down the property you need: identity, charge, polarity, secondary structure, sequence number, or another attribute.
-
Choose the matching residue attribute and begin with a small, readable expression, such as
r.t HISorr.ss helix. -
Check whether the result should be residues or atoms. If you need atoms by name, use the documented “in” form, as in
"CA" in r.t VAL. -
Use ranges and alternatives where they fit the question:
r.id 1:10, 20:30searches multiple sequence ranges, andr.c neutral, positivesearches multiple charge categories.
Residue attributes also inherit useful properties from the node and structural-group attribute spaces. For example, residue searches can use attributes such as hidden, visible, numberOfAtoms, and partialCharge. The reference page lists their short names and examples, along with the full residue-specific attribute set.
For the complete syntax and additional examples, see the SAMSON residue attributes reference.
Note: SAMSON and all SAMSON Extensions are free for non-commercial use. Get SAMSON.