When a molecular scene contains many labels, the hard part is often not adding another one—it is finding the right labels again. You may need to inspect labels with a particular name, separate hidden labels from visible ones, or check which labels are selected. In SAMSON, the Node Specification Language (NSL) lets you express these searches as attribute queries, so you can focus on the labels you need instead of scanning the scene manually.
This guide focuses on the label attribute space: what it matches, how its attributes are named, and how to avoid mixing up properties that sound similar.
Start with the label attribute space
The label attribute space is written label, with the short name la. It matches label nodes. That prefix is useful because it makes the target of a query explicit: la means you are asking about labels, rather than using an attribute without specifying the node type.
For example, la.h refers to the hidden attribute for labels. Its negated form, not la.h, gives the complementary condition. These are compact ways to ask for labels based on their hidden state.
Search by label name
Labels inherit the name attribute from the node attribute space. The short form is n, so a label-name query can be written with either the full attribute name or the short name. The documentation gives la.n "A" and la.n "L*" as examples.
Putting the name in quotes matters: the documented value type for this attribute is strings in quotes. If you are trying to locate a specific label, begin with the name you expect and check the result. The example with L* is also useful to recognize in existing NSL queries; consult the NSL examples if you need guidance on expression patterns beyond the attribute reference.
Do not confuse “selected” with “selectionFlag”
Two label attributes relate to selection, but they have different names: selected and selectionFlag. The selected attribute has no short name in the label attribute space. Its examples are la.selected and not la.selected. By contrast, selectionFlag has the short name sf, with examples la.sf and la.sf false.
This distinction is helpful when reading or writing a query: la.selected and la.sf are not simply two spellings of the same attribute. They are listed separately in the reference and inherited from separate node attributes. Use the name that corresponds to the property you actually want to inspect.
Visibility has two related attributes, too
The label reference also lists visible and visibilityFlag. The short name for visible is v, so the documented examples are la.v and not la.v. The short name for visibilityFlag is vf, with examples la.vf and la.vf false.
Because these attributes have different names and separate entries in the reference, it is safer to choose deliberately rather than assume they are interchangeable. The same caution applies to hidden and visible: both are available, and the page documents them as distinct attributes. If your search is not returning what you expect, verify which attribute you used before changing the rest of the query.
A simple troubleshooting checklist
- Check the target: use the
laprefix when querying label attributes. - Check the attribute: distinguish
selectedfromselectionFlag, andvisiblefromvisibilityFlag. - Check the value format: the name attribute takes quoted strings; Boolean attributes are documented with
trueandfalsevalues. - Try a negated condition: the reference shows forms such as
not la.handnot la.vwhen you want the opposite condition. - Use short names when they help readability: for example,
la.h,la.n,la.sf,la.vf, andla.v.
These small checks can make label searches easier to read and maintain, especially when you return to a scene after a break or share a query with a collaborator. For the complete attribute table and additional details, see the SAMSON label attributes reference. You can also explore the NSL overview and its examples.
Note: SAMSON and all SAMSON Extensions are free for non-commercial use. Get SAMSON.
