A large molecular scene can contain many molecules, from small ligands to long chains and multi-part structures. When you need to find a particular kind of molecule, browsing the structure one item at a time can become tedious. SAMSON’s Node Specification Language (NSL) offers another approach: describe a molecule by one of its attributes, such as atom count, residue count, or number of chains.
The key detail is the attribute space. Molecule attributes use the molecule space, shortened to mol, and match molecule nodes. That lets you ask targeted questions about molecules rather than inspecting every node by name. For example, mol.nat < 1000 matches molecules with fewer than 1,000 atoms.
Start with the kind of structure you need
Different counts answer different questions. A molecule’s atom count can help you distinguish smaller structures from larger ones. Its residue count can help identify larger biological structures, while chain and segment counts describe different aspects of how a molecule is organized. These measures are not interchangeable: choose the attribute that reflects what you actually want to find.
mol.nat 100:200looks for molecules with an atom count between 100 and 200.mol.nr > 100looks for molecules with more than 100 residues.mol.nc < 3looks for molecules with fewer than three chains.mol.ns 2:4looks for molecules with between two and four segments.
The longer attribute names are available too: for example, molecule.numberOfResidues > 100 is the long form of mol.nr > 100. Short forms are convenient when writing queries; full names can be easier to recognize when you are learning the attribute vocabulary.
Use composition to narrow the search
Atom totals can be too broad when several molecules have similar sizes. The molecule attribute space also inherits composition-related counts from the structural-group attribute space. You can look for molecules with a particular number of carbon, hydrogen, nitrogen, oxygen, or sulfur atoms. For instance, mol.nO 10:20 matches molecules with between 10 and 20 oxygen atoms, and mol.nC < 10 matches molecules with fewer than 10 carbon atoms.
Charge attributes offer another useful way to describe a molecule. mol.fc > 1 tests formal charge, while mol.pc > 1.5 tests partial charge. The documentation lists formal charge as an integer attribute and partial charge as a floating-point attribute. Keep that distinction in mind when choosing a comparison or range.
Remember what the query is measuring
These expressions describe molecule-level properties. A query such as mol.nat 100:200 is not asking for individual atoms in that range; it matches molecules whose number of atoms falls in that range. Likewise, residue, chain, segment, and structural-group counts refer to counts associated with the molecule. This distinction helps avoid a common source of confusion when moving between atom-level and molecule-level searches.
NSL also exposes inherited node attributes, including molecule name, visibility, hidden state, and selection state. For example, mol.n "A" checks a molecule’s name, and mol.v matches visible molecules. The selected attribute is written as mol.selected; unlike some inherited attributes, it has no short name in this attribute space.
A practical way to begin is to choose one property that separates the target from the rest of the scene, write the corresponding expression, and then adjust the value if the result is too broad or too narrow. For example, start with atom count to find a size class, or use residue count when the number of residues is the more meaningful measure. The attribute tables on the reference page provide the available names, abbreviations, value types, and additional examples.
For the complete attribute reference, see Molecule attributes in the SAMSON documentation.
Note: SAMSON and all SAMSON Extensions are free for non-commercial use. Get SAMSON.
