Finding the right atoms in a molecular model can feel harder than the analysis that comes next. A search for a residue name may return its backbone, side chain, and residue node; a broad distance query can even match a parent node because some of its atoms are nearby. The Node Specification Language (NSL) helps you describe what you actually want—and, just as importantly, limit the result to the right kind of node.
NSL expressions work in Select > Find and in the filter box of the Document view. Find is useful for search-driven selections; the Document view lets you filter the hierarchy and select matching nodes by pressing Enter. Here is the Find command in action:
Start with the type of thing you want
A good habit is to specify the node type before adding the finer condition. For example, node.type residue and not residue.type ALA means “residue nodes, except alanine residues.” The short form is n.t r and not r.t ALA.
That type restriction matters because not applies across nodes, not just the type you have in mind. A query such as not r.t CYS can match folders and other nodes that are not cysteine residues. If the goal is a list of non-cysteine residues, use n.t r and not r.t CYS. In other words: first say what kind of node you want, then say which ones to include or exclude.
Make name searches predictable
Put a node name in quotation marks. "ALA 22" matches that full name exactly. For a simple pattern, use glob wildcards: * matches zero or more characters, and ? matches one character. For instance, "*Backbone" finds names ending in “Backbone,” while "C?" can match names such as CA or CB.
Use a regular expression when a simple wildcard cannot express the pattern you need. Prefix the quoted expression with re; for example, re"^[A-Z]{3}$" matches names made of exactly three uppercase letters. For an unfamiliar model, autocomplete can save time: in Find, type an opening quote and part of a name—such as "ALA—then press Tab to see matching names from the active document.
Use distance queries without catching parent nodes
Suppose you want atoms near a named residue. A distance condition alone may return a structural parent as well as individual atoms. Restrict the result to atoms with n.t a within 5A of "GLN 2". This includes atoms belonging to GLN 2 itself. To exclude that residue and keep nearby atoms outside it, add out of "GLN 2":
n.t a within 5A of "GLN 2" out of "GLN 2"
The same principle applies to other operators: the result is a set of nodes, and a parent node may satisfy a condition through nodes it contains. Explicitly naming the desired node type makes the selection easier to interpret.
Useful starting queries
C or H— carbon or hydrogen atoms.node.category ligand, receptor— ligand and receptor nodes.residue.id 20:40, 50:60— residues in either ID range."CA" within 5A of S— nodes named CA within five angstroms of sulfur atoms.H linking O— hydrogens bonded to oxygen atoms.
These are starting points, not a substitute for checking what a query returns in your document. If you are unsure, begin with a narrow condition, inspect the selection, and then add another constraint. In the Document view, the filter expression n.t sg is a quick example of filtering for structural groups.
For the complete syntax and attribute references, see the NSL documentation.
Note: SAMSON and all SAMSON Extensions are free for non-commercial use. Get SAMSON.