Find the backbone groups that matter: a practical guide to NSL filters

When a molecular structure contains many backbone groups, finding the ones relevant to a question can be surprisingly tedious. Are you looking for groups with a particular formal charge, a limited number of atoms, or a specific elemental composition? In SAMSON, the Node Specification Language (NSL) lets you express these criteria as attribute-based filters instead of relying on visual inspection alone.

This guide focuses on a useful, self-contained part of the backbone attribute reference: filtering backbone nodes by charge and composition, plus checking their names and visibility. The examples use bb as the backbone qualifier, as shown in the documentation. Backbone attributes also inherit properties from the node and structuralGroup attribute spaces.

Start with the kind of question you have

A helpful first step is to turn a vague search into a measurable condition. “Find a small backbone group” might mean fewer than a certain number of atoms. “Find a charged group” might mean a formal charge above or below a chosen value. NSL provides separate attributes for these measurements, so choose the one that matches the question rather than treating them as interchangeable.

  • Overall size: bb.nat < 1000 checks the number of atoms, while bb.nat 100:200 specifies an example range.
  • Element counts: use bb.nC, bb.nH, bb.nN, bb.nO, or bb.nS for the number of carbons, hydrogens, nitrogens, oxygens, or sulfurs. For example, bb.nO 10:20 describes an oxygen-count range.
  • Formal charge: bb.fc > 1 selects by formal charge, and bb.fc 6:8 illustrates a range.
  • Partial charge: bb.pc > 1.5 and bb.pc 1.5:2.0 show comparison and range examples for partial charge.

Formal charge and partial charge answer different questions. The reference lists formal charge as an integer-valued attribute and partial charge as a floating-point attribute. If your criterion is expressed as an overall formal charge, use fc; if it concerns a partial-charge value, use pc. Choosing deliberately helps prevent a plausible-looking filter from answering the wrong question.

Use composition filters to narrow the search

Element-count attributes are useful when the feature you care about is compositional. For instance, bb.nN < 10 expresses an upper-bound example for nitrogen count, while bb.nC 10:20 expresses a carbon-count interval. The page also documents bb.ncga for the number of coarse-grained atoms, which is distinct from the total atom count represented by bb.nat.

These examples are starting points, not universal cutoffs. Set the threshold or range to match the structure and the question you are investigating. When exploring unfamiliar data, it can be useful to begin with a broad range and then make the criterion more specific.

Keep naming and display state separate from chemistry

Some backbone attributes describe the node rather than its chemical composition. For a name-based match, the reference shows bb.n "A" and bb.n "L*"; names are supplied as quoted strings. The inherited node attributes also include visibility and selection-related checks: bb.v tests visibility, not bb.v tests its opposite, and bb.selected or not bb.selected checks selection state.

This separation is useful when troubleshooting a filter. A name, visibility, or selection condition is not a substitute for an atom-count or charge condition. Likewise, the reference notes that selected has no short name in this attribute space, so write it out as bb.selected rather than trying to abbreviate it.

A simple way to build a reliable filter

  1. Decide what you want to identify: charge, total size, a particular element count, name, or display state.
  2. Choose the matching attribute, such as fc, nat, nO, or n.
  3. Start from one documented comparison or range example and adjust its value to suit your structure.
  4. Check that the condition describes the intended property—for example, total atoms versus coarse-grained atoms, or formal versus partial charge.

Backbone filters are most useful when they make the selection criterion explicit. Instead of scanning a crowded model and guessing which groups qualify, you can state the property you care about and refine the threshold as needed. For the complete list of backbone attributes and inherited properties, see the SAMSON backbone attribute reference.

Note: SAMSON and all SAMSON Extensions are free for non-commercial use. Get SAMSON.

Comments are closed.