When a molecular structure contains many backbone nodes, finding the ones relevant to a particular task can take longer than expected. You may need to narrow the view to backbones with a certain atom count, identify candidates with a particular charge, or simply distinguish visible from hidden nodes. SAMSON’s Node Specification Language (NSL) provides attributes for expressing these kinds of searches.
This guide focuses on a practical subset of the backbone attribute space: node state, composition counts, and charge. The examples use the bb prefix shown on the documentation page. They are intended as a starting point for exploring and refining backbone searches.
Start with the kind of information you need
Backbone attributes include properties inherited from both the general node space and the structuralGroup space. That distinction helps when choosing a filter: node attributes describe things such as visibility and names, while structural-group attributes include atom counts and charges.
For a quick check of display or selection state, use boolean attributes. For example, bb.v matches visible backbones, while not bb.v matches those that are not visible. Similarly, bb.selected and not bb.selected let you query selection state. The longer attribute names are available too: visible and selected. Note that the documentation specifically says selected has no short name in this attribute space.
Names can also be queried using quoted strings. The documented examples include bb.n "A" and bb.n "L*", where n is the short name for name. Use the full name, bb.name, if that is clearer to you.
Use counts to narrow structural candidates
If the challenge is finding a backbone of a manageable size, filter by the total number of atoms. For example, bb.nat < 1000 selects backbones with fewer than 1,000 atoms, while bb.nat 100:200 specifies a range. Here, nat is the short name for numberOfAtoms.
Element-specific counts can help when total size alone is not informative. The available attributes include nC for carbons, nH for hydrogens, nN for nitrogens, nO for oxygens, and nS for sulfurs. For example, bb.nO < 10 queries backbones with fewer than ten oxygen atoms, and bb.nC 10:20 specifies a carbon-count range. The reference also lists ncga, the short name for the number of coarse-grained atoms.
These filters are useful for turning a broad structural search into a more focused one. A good habit is to begin with a simple, measurable criterion—such as a count range—and then adjust the values to suit the structures in your current model.
Don’t confuse the two charge measures
NSL lists both formalCharge (fc) and partialCharge (pc). They are separate attributes, so choose the one that corresponds to the quantity you want to inspect. The documented examples show integer comparisons and ranges for formal charge, such as bb.fc > 1 and bb.fc 6:8. For partial charge, the examples use floating-point values: bb.pc > 1.5 and bb.pc 1.5:2.0.
That difference in value type matters when writing a query: formal charge is listed as integers, while partial charge is listed as floats. If a result seems unexpected, check that you are querying the intended charge attribute and using a value format appropriate to it.
A small checklist for building a query
- Pick the property: visibility, name, atom count, elemental count, or charge.
- Choose the attribute: for example,
numberOfAtomsor its short namenat. - Set a useful condition: the reference demonstrates comparisons such as
<and>, as well as ranges such as100:200. - Check the target: backbone attributes apply to backbone nodes, rather than serving as a general query for every node type.
Keeping each search tied to a clear attribute makes it easier to understand what a query is testing and to revise it when the structural context changes. For the complete attribute list and additional details, see the SAMSON backbone attributes reference.
Note: SAMSON and all SAMSON Extensions are free for non-commercial use. Get SAMSON.