A molecular model can contain atoms, residues, chains, ligands, and many other kinds of nodes. That hierarchy is useful, but it can make a simple question surprisingly tricky: which exact things will this search select? A broad query may match parent groups as well as atoms, while a negative condition can return unrelated node types. The Node Specification Language (NSL) helps you be specific—provided you describe both what you want and what kind of node should be returned.
Here’s a practical way to build more reliable selections in SAMSON, especially when you’re exploring a structure or narrowing down atoms around a region of interest.
Start with the node type
In SAMSON, you can enter an NSL expression in Select > Find, or use it in the Document view’s filter box. Find selects matching nodes in the active document; the Document view lets you inspect the filtered hierarchy and select matches by pressing Enter.
Before adding a detailed condition, decide whether the result should contain atoms, residues, or another node type. For example, node.type atom (short form: n.t a) limits the result to atoms. This small step can prevent a common surprise: a query can match a group because one of its contents meets the condition.
To see the workflow in context, the documentation includes this Find-command image:
Build the query in layers
Think of an NSL expression as a set of filters. First specify the kind of node, then add the property or relationship that matters. For instance, node.type residue and not residue.type ALA asks for residues and excludes alanine. The type condition matters: not residue.type ALA by itself can also match nodes that are not residues, such as folders. In other words, “not alanine” does not automatically mean “a residue other than alanine.”
The same idea applies to distance searches. To find atoms within five angstroms of a named group, use node.type atom within 5A of "GLN 2". The atom-type condition makes the intended result clear. Note that this query also includes atoms belonging to GLN 2. If you want nearby atoms outside that group, add an exclusion: node.type atom within 5A of "GLN 2" out of "GLN 2".
That distinction is useful when examining a binding site or local environment: “near this residue” and “near this residue, but not part of it” are different selection tasks.
Use names and shortcuts carefully
Names containing spaces should be enclosed in quotes, as in "GLN 2". Quoted names can match exactly, or use simple wildcards: "ALA*" can match names beginning with ALA, while "*Backbone" can match names ending in Backbone. For more complex patterns, NSL supports regular expressions prefixed with re.
Once the full expression is clear, short forms make repeated queries quicker. For example, node.type atom can be written n.t a, and within 5A of can be shortened to w 5A of. If you’re unsure what a name begins with, type its opening characters in Find and press Tab to see context-sensitive completions.
A quick check before you trust a selection
- Check the result type: include a node-type condition when you need only atoms, residues, or another specific kind of node.
- Check exclusions: pair
notwith a type condition when the result should stay within one class of nodes. - Check distance boundaries: decide whether the reference group itself should be included, and use
out ofwhen it should not. - Inspect before continuing: use the Document view filter to review the matching hierarchy, or refine the expression in Find.
These habits turn a search from a plausible-looking string into a selection whose scope you can reason about. For the full syntax, examples, and attribute references, read the NSL documentation.
Note: SAMSON and all SAMSON Extensions are free for non-commercial use. Get SAMSON.