When a molecular project contains many files, a small search mistake can make it harder to focus on the structure or data you actually need. SAMSON’s Node Specification Language (NSL) provides a compact way to describe file nodes by name and selection state. The useful first step is knowing which attributes belong to files—and what each expression checks.
Start with the file attribute space
File attributes live in the file attribute space, abbreviated fi. An expression beginning with fi is therefore aimed at file nodes, rather than being a general query for every kind of node. This distinction helps keep a search focused when a document contains different types of objects.
The reference lists three relevant attributes:
name, with the short namen, checks a file node’s name. Values are written as strings in quotes.selectedchecks whether the file node is selected. In the file attribute space, it has no short name.selectionFlag, with the short namesf, checks the selection flag and acceptstrueorfalse.
Use names to narrow the search
If you are trying to locate a file node by name, the documented examples are fi.n "A" and fi.n "L*". The longer form, fi.name "A", uses the full attribute name. Both forms make the attribute being checked explicit: this is a file name, not a name on an unspecified node type.
The example with "L*" shows that a pattern-like string can appear in a name expression. When preparing a query, use the examples as a guide to the expression’s shape; consult the NSL reference for details about matching behavior rather than assuming what a particular pattern will match.
Check selection state deliberately
To test the selected state, the reference gives fi.selected. To express the opposite condition, it gives not fi.selected. These two forms are useful when you need to describe file nodes by whether they are currently selected, instead of by their names.
There is also selectionFlag, which can be written as fi.selectionFlag or shortened to fi.sf. The examples include fi.sf and fi.sf false. Although selected and selectionFlag both use Boolean values, they are separate attributes in the reference. Use the attribute that matches the condition you intend to express; do not treat the two names as interchangeable.
A quick query checklist
- Begin with
fiwhen your target is a file node. - Choose
nornameto check a name, and put the value in quotes. - Choose
selectedto test selected state, orsf/selectionFlagto test the selection flag. - Use
notwhen you need to express the inverse offi.selected.
Keeping these distinctions in mind makes file-node queries easier to read and reduces the chance of filtering on the wrong attribute. For the complete attribute reference and additional context, see the SAMSON file attributes documentation.
Note: SAMSON and all SAMSON Extensions are free for non-commercial use. Get SAMSON.
