When a molecular structure contains many residues, finding the side chains relevant to a question can become a tedious cycle of clicking, inspecting, and deselecting. Are you looking for groups with a particular name, a charge threshold, or a specific elemental makeup? SAMSON’s Node Specification Language (NSL) lets you express these criteria as filters, so you can focus on the side-chain nodes that meet them.
This guide focuses on a useful, self-contained part of NSL: side-chain attributes. The examples below show how to search by identity, composition, and charge, and how to interpret the attribute shorthand so you can adapt the expressions to your own structure.
Start with the side-chain attribute space
Side-chain attributes are defined in the sideChain attribute space. The documentation uses sc in its example expressions, such as sc.nC < 10. That prefix matters: it specifies that the attribute you’re testing belongs to a side-chain node. The side-chain attribute space matches only side-chain nodes, helping keep a search focused on the structural groups you mean to examine.
Attributes can have a full name and a shorter form. For example, numberOfCarbons has the short name nC, and partialCharge has the short name pc. The examples use these short forms, which make expressions more compact. You can consult the attribute table when you need to check a shorthand or the expected value type.
Filter by elemental composition
Composition is a useful first pass when you want to narrow a structure to side chains with a certain number of atoms of an element. The available count attributes include carbon (nC), hydrogen (nH), nitrogen (nN), oxygen (nO), and sulfur (nS). For example:
sc.nC < 10checks for fewer than 10 carbons.sc.nN 10:20uses a numeric range for the number of nitrogens.sc.nat < 1000checks the total number of atoms.
These examples illustrate two common ways to express numeric criteria: comparisons such as <, and ranges written with a colon. The same pattern is shown for other integer-valued attributes, including total atoms, coarse-grained atoms, and formal charge. If your selection feels too broad, a more specific threshold or range can help you define a smaller set of candidates.
Use charge as a search criterion
Charge is often the property that makes a side chain relevant to an interaction or analysis. NSL exposes both formalCharge (short name fc) and partialCharge (short name pc). Formal charge takes integer values, while partial charge takes floating-point values. The documented examples include sc.fc > 1 and sc.pc 1.5:2.0.
Keep the distinction in mind when choosing a filter: the two attributes have different value types, so an integer criterion for formal charge is not interchangeable with a decimal range for partial charge. Start with the property that matches the question you are asking, then adjust the threshold to suit your analysis.
Search by name or state
If you already know a side-chain name or want to focus on a particular node state, inherited node attributes can help. The name attribute accepts strings in quotes; the documentation shows sc.n "A" and sc.n "L*" as examples. Visibility and selection are also available as Boolean attributes: for instance, sc.v checks visible side chains, while not sc.selected checks side chains that are not selected.
There is one easy-to-miss shorthand detail: selected does not have the short name s in this attribute space. Use sc.selected as shown, rather than assuming every attribute has an abbreviated form.
A practical way to work
Choose the attribute that corresponds to your immediate question, use its documented value type, and begin with a simple expression. For composition or charge, try a threshold or range; for identity or visibility, use the appropriate name or Boolean attribute. The examples here are individual expressions, so treat each as a starting point for a targeted search rather than assuming a combined expression or workflow not described here.
For the complete list of side-chain attributes and their inherited definitions, see the SAMSON side-chain NSL reference.
Note: SAMSON and all SAMSON Extensions are free for non-commercial use. Get SAMSON.