Find the Labels You Mean: A Practical Guide to Label Filters in SAMSON

A crowded molecular scene is hard to inspect when labels get in the way. The tricky part is often not the molecular structure itself, but finding the right labels among many nodes without confusing a label’s visibility, hidden state, or selection state. SAMSON’s Node Specification Language (NSL) provides a focused way to describe label nodes and their attributes.

This guide concentrates on a small, useful part of NSL: label filters for visibility, hidden state, selection, and name. The expressions below are examples from the label attribute reference. They can help you make a query more readable and avoid applying a label-specific condition to the wrong kind of node.

Start with the label attribute space

Label attributes live in the label attribute space, whose short name is la. This space matches only label nodes. That scope matters: when the question is about labels, begin with la rather than assuming a general node expression is label-specific.

For example, la.v is the short form shown for the visible attribute, and not la.v is its negated example. If you want to express the opposite condition, negation makes that intent explicit. The same pattern is shown for hidden state: la.h and not la.h.

Visible and hidden are separate attributes

It can be tempting to treat “visible” and “not hidden” as interchangeable. The reference lists visible and hidden as distinct attributes, each with true and false as possible values. For precise queries, use the attribute that describes the condition you actually want to express:

  • la.v or not la.v for the label’s visible attribute.
  • la.h or not la.h for the label’s hidden attribute.

This small distinction makes a filter easier to understand later, especially when you return to a scene after changing what you are inspecting. Rather than relying on an informal idea of “on” or “off,” the expression names the attribute directly.

Use names to narrow the search

When visibility alone is not enough, the name attribute can help describe which labels you mean. The reference gives la.n as the short form and shows examples such as la.n "A" and la.n "L*". Quoted strings make the value being compared visible in the expression. If you are building a filter, begin with a recognizable name pattern from your own labeling scheme and check that it identifies the intended labels.

A practical way to think about this is to build the query around one question at a time: first, “Is this a label?” (the la space already sets that scope); then, “Which name or state matters?” This keeps the expression tied to the problem you are trying to solve instead of combining unrelated conditions prematurely.

Be explicit about selection

Label nodes also inherit the selected attribute. For labels, its expression is la.selected or not la.selected; unlike some inherited node attributes, this attribute has no short name in the label reference. That is a useful detail to remember when reading or writing compact NSL expressions: not every attribute has a short form.

The reference also lists selectionFlag (short name sf) and visibilityFlag (short name vf), with examples such as la.sf false and la.vf false. These are separate attributes from selected and visible. If you need one of them, use its own name or documented short form rather than substituting a similarly named attribute.

A quick checklist

  • Use la when your target is specifically label nodes.
  • Choose visible or hidden deliberately; the reference lists them separately.
  • Use la.n with a quoted name value when label names are the useful clue.
  • Write la.selected in full; the label reference does not provide a short name for it.
  • Keep selectionFlag and visibilityFlag distinct from selected and visible.

These are small pieces of syntax, but they make label-focused queries clearer and easier to revisit. For the complete attribute list and additional details, see the SAMSON label attributes reference.

Note: SAMSON and all SAMSON Extensions are free for non-commercial use. Get SAMSON.

Comments are closed.