A crowded molecular scene can make a simple task surprisingly slow: finding the molecule with the right size, composition, or organization. Scrolling through a structure tree and checking entries one at a time is tedious—and it is easy to select the wrong thing when molecules have similar names.
SAMSON’s Node Specification Language (NSL) lets you describe a molecule by its attributes instead. The molecule attribute space matches molecule nodes, so its queries are useful when your target is a whole molecule rather than an individual atom or residue. You can filter by properties such as atom counts, chain counts, residue counts, and name.
Start with the scale of the molecule
If you want to narrow a scene by size, use numberOfAtoms, abbreviated nat. For example, mol.nat < 1000 matches molecules with fewer than 1,000 atoms, while mol.nat 100:200 matches those between 100 and 200 atoms. The range form is a practical way to define a window when “small” or “large” is too vague.
For protein-sized structures, residue counts may be more useful than raw atom counts. Try mol.nr > 100 to match molecules with more than 100 residues, or mol.nr 100:120 to look for a narrower size range. These are separate queries; choose the one that fits the question you are asking.
Check structural organization
Two molecules can have similar sizes but very different organization. The molecule attributes nc, ns, and nsg refer to numbers of chains, segments, and structural groups, respectively.
mol.nc < 3finds molecules with fewer than three chains;mol.nc 2:4looks for two to four.mol.ns > 2finds molecules with more than two segments.mol.nsg > 10finds molecules with more than ten structural groups.
These counts can help distinguish a compact single-chain entry from a larger assembly, or identify structures whose organization deserves closer inspection. They describe counts, though—not biological function or whether a structure is complete—so treat them as ways to narrow your search, not as conclusions about the molecule.
Use composition when size is not enough
For a quick composition-based filter, NSL includes inherited structural-group attributes such as numbers of carbon, hydrogen, nitrogen, oxygen, and sulfur atoms. For example, mol.nO < 10 selects molecules with fewer than ten oxygen atoms, and mol.nN 10:20 selects molecules with 10 to 20 nitrogen atoms. You can also inspect formal charge with mol.fc > 1, or partial charge with mol.pc > 1.5.
Names can be useful when you already know part of an entry’s label. For example, mol.n "A" matches a molecule named “A”; the documented example mol.n "L*" illustrates using a wildcard-style name pattern. If a name query does not narrow the scene enough, counts and composition offer other ways to describe the target.
Remember inherited attributes
Not every attribute listed for molecules is unique to molecules. Some are inherited from the general node or structural-group attribute spaces. For example, mol.v checks visibility, mol.selected checks selection, and mol.fc refers to formal charge. Knowing that these are inherited helps make sense of the attribute list: molecule queries combine molecule-specific properties with properties shared by other node types.
A useful habit is to translate your goal into one measurable question: “How many residues?”, “How many chains?”, or “How many oxygens?” Then use the full attribute name or its short form to express that question. The short forms—such as mol.nr and mol.nc—make repeated queries quicker to type, while the full names can be easier to remember when you are learning.
For the complete attribute reference and additional examples, see the SAMSON molecule attributes documentation.
Note: SAMSON and all SAMSON Extensions are free for non-commercial use. Get SAMSON.