Find the labels that matter: a practical guide to NSL label attributes

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 la prefix when querying label attributes.
  • Check the attribute: distinguish selected from selectionFlag, and visible from visibilityFlag.
  • Check the value format: the name attribute takes quoted strings; Boolean attributes are documented with true and false values.
  • Try a negated condition: the reference shows forms such as not la.h and not la.v when you want the opposite condition.
  • Use short names when they help readability: for example, la.h, la.n, la.sf, la.vf, and la.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.

Comments are closed.