Find the right structural model before the details get overwhelming

A molecular project can contain structural models that look similar at first glance but differ substantially in size, composition, or charge. When you need to locate a model with a particular profile, checking candidates one by one is tedious—and easy to get wrong. SAMSON’s Node Specification Language (NSL) lets you search structural model nodes by these properties, so you can narrow a large set of candidates using explicit criteria.

Structural model attributes use the structuralModel attribute space, abbreviated sm. That prefix matters: it tells NSL which kind of node the condition is intended to match. For example, sm.nat refers to a structural model’s number of atoms, while sm.nc refers to its number of chains.

Start with scale

If your immediate concern is whether a model is too large or too small for the next step in your workflow, begin with numberOfAtoms (nat). You can set a threshold or specify an interval:

  • sm.nat < 1000 looks for structural models with fewer than 1,000 atoms.
  • sm.nat 100:200 looks for models with an atom count between 100 and 200.

Other count attributes help describe model organization. Use sm.nc for chains, sm.nm for molecules, sm.nr for residues, and sm.ns for segments. For instance, sm.nc 2:4 selects models with between two and four chains, while sm.nr > 130 targets models with more than 130 residues.

These are different measures of scale and organization, not interchangeable shortcuts. A residue count tells you something different from an atom count; choosing the attribute that matches your question makes the search easier to interpret.

Use composition to distinguish candidates

When size alone is not enough, elemental counts can help describe a model’s composition. NSL provides attributes for carbon (nC), hydrogen (nH), nitrogen (nN), oxygen (nO), and sulfur (nS), as well as coarse-grained atoms (ncga). These count attributes accept integer comparisons and ranges. For example, sm.nO 10:20 expresses an oxygen-count interval, and sm.nC < 10 expresses a carbon-count threshold.

The documentation describes these elemental-count attributes as working in a similar way to numberOfAtoms. That gives you a consistent pattern to remember: use the short name after sm., then provide a comparison or a range appropriate to the count.

Keep formal and partial charge separate

Charge can be another useful discriminator, but formal charge and partial charge are distinct attributes. sm.fc searches by total formal charge and takes integer values. For example, sm.fc 6:8 matches models with formal charge between 6 and 8. sm.pc searches by total partial charge and accepts real numbers; sm.pc 1.5:2.0 specifies a partial-charge interval.

Keeping the two attributes separate helps avoid a common search mistake: assuming that a formal-charge condition is equivalent to a partial-charge condition. Choose the one that corresponds to the property you actually need to filter.

A practical narrowing sequence

For a repeatable search, write down the decision you are trying to make, then select the matching attribute: total size (sm.nat), composition (such as sm.nO), organization (sm.nc or sm.nr), or charge (sm.fc or sm.pc). Start with one broad condition, inspect the results, and make the next condition more specific if needed. This keeps each filter understandable and makes it easier to adjust your criteria when the candidate set is unexpectedly empty or broad.

Ranges are particularly handy when you do not need an exact value. A condition such as sm.nm 2:4 describes an acceptable interval, while a comparison such as sm.ns < 3 expresses a simple cutoff. The attribute table also lists longer names and short names, so you can use the form that is easiest to read in your query.

Structural model attributes are one part of NSL’s broader search language. For the complete attribute list and additional examples, see the structural model attributes reference.

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

Comments are closed.