Quickly Find the Right Structural Groups with Smart Attribute Filters in SAMSON

When working on complex molecular systems, molecular modelers often face the tedious task of filtering and selecting just the right parts of a model. Whether you’re preparing data for simulations, cleaning structures before exporting, or simply analyzing specific components, finding and isolating specific structural groups based on meaningful criteria—like atom count, formal charge, or visibility—can save hours of manual work.

Fortunately, SAMSON’s Node Specification Language (NSL) provides a powerful way to target structural groups using attribute-based filters. This blog post introduces you to one of the most helpful—yet often underused—sections of NSL: structural group attributes.

What is a structural group?

In SAMSON, a structural group is a node type that typically represents a logical or functional group of atoms. It could be a ligand, a chain, a fragment, or a custom group you define. Using NSL, structural groups are targeted with the prefix sg (short for structuralGroup).

Why use attribute filters?

Attribute filters allow you to write concise expressions to find exactly what you’re looking for. Need to select all groups with more than 100 atoms? Or groups that are hidden but own material properties? It’s just one line away.

Examples of common use cases

  • Find groups with more than 100 atoms:
    sg.nat > 100
  • Find groups with a partial charge between 1.5 and 2.0:
    sg.pc 1.5:2.0
  • Find structural groups that own materials and are hidden:
    sg.om and sg.h
  • Select groups based on specific naming patterns:
    sg.n "L*" — this matches groups whose name starts with “L”

Such filters can be tremendously helpful in situations where you are dealing with hundreds or thousands of groups. Instead of scrolling endlessly or checking properties manually, NSL gives you a surgical way to pinpoint your data.

Tip: Combine filters for advanced queries

You can use logical operators like and, or, and not to build compound expressions. For example:

This selects structural groups with a formal charge between 1 and 3 that are not hidden.

Behind the scenes: Data types and ranges

Attributes accept different types of values:

  • true or false for visibility, selection, and material-related attributes.
  • Quoted strings (like "A*") for names.
  • Integers and ranges (e.g., 100:200) for counts like numberOfAtoms, numberOfHydrogens, etc.
  • Floating-point numbers for partial charges.

You can find the full list of attributes—including short names for quicker expressions—directly in the documentation. Here’s a selection:

  • sg.nat: Number of atoms
  • sg.nC, sg.nH, sg.nO, etc.: Counts of specific elements
  • sg.fc: Total formal charge
  • sg.h, sg.v: Hidden or visible flags
  • sg.om, sg.hm: Material ownership or presence

Use these wisely and you’ll speed up your workflows significantly.

Next steps

NSL is a compact but powerful way to interrogate and manipulate molecular models. By using these attribute filters, you’re making use of a functionality that’s already integrated into SAMSON to better navigate complexity and focus on your scientific questions.

To learn more and explore all structural group attributes, head over to the full documentation: https://documentation.samson-connect.net/users/latest/nsl/structuralGroup/

SAMSON and all SAMSON Extensions are free for non-commercial use. You can download SAMSON at https://www.samson-connect.net.

Comments are closed.