A project can accumulate folders containing structures of very different sizes and compositions. When you need to find a folder with, say, a particular atom count or number of chains, inspecting each folder manually is a tedious way to narrow the search. SAMSON’s Node Specification Language (NSL) lets you express those criteria as filters on folder nodes.
The key detail is the attribute space: folder, shortened to f, matches only folder nodes. Its attributes can describe properties of the structures in a folder, such as atom counts, chain counts, residue counts, and total charge. This makes folder filters useful for narrowing down a collection before you inspect individual structures.
Start with the question you need to answer
Translate a practical question into the corresponding folder attribute. For example:
- “Which folders contain structures with more than 100 atoms?” Use
f.nat > 100. The full attribute name isfolder.numberOfAtoms. - “Which folders have between two and four chains?” Use
f.nc 2:4, orfolder.numberOfChains 2:4. - “Which folders have more than 100 residues?” Use
f.nr > 100. - “Which folders have a total formal charge from 6 to 8?” Use
f.fc 6:8. - “Which folders have a total partial charge from 1.5 to 2.0?” Use
f.pc 1.5:2.0.
For integer-valued attributes, the reference uses comparisons such as < and >, as well as colon-separated ranges. Partial charge accepts real values. These examples let you state the criterion directly instead of relying on a folder name to communicate what its contents are.
Use the short names when you want a compact query
The full names are easier to read at first; short names make expressions quicker to type. A few useful pairs are numberOfAtoms / nat, numberOfChains / nc, numberOfResidues / nr, formalCharge / fc, and partialCharge / pc. In folder queries, prefix the short name with f., as in f.nat or f.fc.
Other count attributes can help describe a folder’s contents more specifically. For example, f.nC refers to the number of carbon atoms, f.nH to hydrogen atoms, f.nN to nitrogen atoms, f.nO to oxygen atoms, and f.nS to sulfur atoms. These work in the same way as the number-of-atoms attribute.
Don’t overlook inherited folder attributes
Folders also inherit general node attributes. You can filter by name with f.n "A" or a name pattern such as f.n "L*", and by visibility with f.v or not f.v. The selection state can be checked with f.selected; unlike many other inherited attributes, selected has no short name in the folder attribute space.
A practical approach is to begin with the property that most clearly separates the folders you care about—often atom count, residue count, or chain count—then refine your search using another relevant folder attribute. Keep in mind that these are folder-level filters: the documentation describes them as matching folders with structures having the specified property.
For the complete list of folder attributes and examples, see the SAMSON folder attributes reference.
Note: SAMSON and all SAMSON Extensions are free for non-commercial use. Get SAMSON.
