When a SAMSON document contains several structural models, finding the one you need by eye can become slow: one model may be a small ligand, another a large complex, and several may look similar at a glance. Structural model attributes in the Node Specification Language (NSL) offer a more deliberate first pass. You can describe a model by its size, composition, chain or residue counts, and charge, then use those expressions to identify candidates.
The key is to treat the query as a screening question. Start with the property that best separates the models, rather than trying to remember names or inspect every structure. Structural model expressions use the sm prefix. For instance, sm.nat < 1000 matches models with fewer than 1,000 atoms, while sm.nat 100:200 looks for models whose atom count is between 100 and 200.
Begin with scale
Atom count is often the most useful first discriminator when a scene contains structures of very different sizes. Use sm.nat to set a threshold or inspect a range. If you are looking for a larger protein-like model, the residue count may be more meaningful: sm.nr > 100 matches models with more than 100 residues. For a narrower range, try sm.nr 100:120.
Other counts help describe organization. sm.nc < 3 selects models with fewer than three chains, and sm.nm 2:4 matches models with between two and four molecules. The segment count is available as sm.ns, and the structural-group count as sm.nsg. These measures answer different questions: total atoms describes overall size, while chains, molecules, segments, and structural groups describe aspects of how a model is organized.
Use composition to distinguish candidates
When two models have similar sizes, elemental counts can provide a useful second clue. The short names are compact: sm.nC for carbon atoms, sm.nH for hydrogen, sm.nN for nitrogen, sm.nO for oxygen, and sm.nS for sulfur. For example, sm.nO 10:20 describes models with 10 to 20 oxygen atoms; sm.nC < 10 describes models with fewer than 10 carbon atoms. Coarse-grained atom counts are available through sm.ncga.
These counts are especially handy as a way to make a search more specific. First narrow by overall atom count, then use one or more composition-related attributes to separate candidates. The expressions shown here are individual examples from the NSL reference; use the attribute that corresponds to the question you are trying to answer.
Keep the two kinds of charge separate
Formal charge and partial charge are not interchangeable filters. The formal-charge attribute, sm.fc, accepts integer values: sm.fc 1 matches a model with formal charge 1, and sm.fc 6:8 matches a range. The partial-charge attribute, sm.pc, accepts real values: sm.pc 1.5:2.0 matches models with total partial charge in that range. Choose the one that matches the charge quantity you intend to inspect.
A practical filtering sequence
- Decide what makes the target distinctive. Is it unusually large, has a known residue count, or contains a characteristic number of a particular element?
- Choose the matching attribute. For example, use
sm.natfor atom count,sm.nrfor residues, orsm.nOfor oxygen count. - Use a threshold or range. Comparisons such as
>and<express cutoffs; a range such as100:200expresses an interval. - Check the candidate in context. Counts help narrow a search, but they do not by themselves establish a model’s identity or biological role.
Structural models also inherit general node attributes. For example, sm.n "A" searches by name, sm.v tests visibility, and sm.selected tests selection state. These can complement composition and size when you need to distinguish or manage models in a busy document.
For the complete attribute list and additional examples, see the SAMSON structural model attributes reference.
Note: SAMSON and all SAMSON Extensions are free for non-commercial use. Get SAMSON.