Find the Notes That Matter: A Practical NSL Checklist

Notes can be easy to overlook in a busy molecular scene. A note may be present but hidden, or you may need to narrow your search to notes with a particular name. Rather than inspecting every note one by one, use SAMSON’s Node Specification Language (NSL) to describe the note attributes you want to match.

The key detail is the attribute space: note attributes use the prefix nt, and that space matches only note nodes. This makes note-specific searches easier to read and helps keep the intent of an expression clear. For example, nt.n "A" is a name-based expression for notes, while nt.v uses the note’s visible attribute.

Start with the problem you are solving

If you are checking visibility, the documented expressions include nt.v and not nt.v. These let you express the two sides of a visibility check: notes matching visible, and notes that do not match it. If you need to inspect the hidden attribute instead, use nt.h or not nt.h. Both attributes are available in the note space.

It is useful to keep hidden and visible as separate attribute names in your queries. The reference lists each independently, with its own short name: h for hidden and v for visible. Choose the attribute that matches the question you are asking, rather than assuming the two names are interchangeable.

Use names to narrow the search

When the issue is locating a particular note, the name attribute is a more direct starting point than visibility. The documented examples are nt.n "A" and nt.n "L*". The short form for name is n, and values are written in quotes. Keeping the value quoted makes the expression easy to scan and helps distinguish the attribute from the name you are searching for.

Keep selection attributes straight

The note attribute space also inherits selected and selectionFlag. These are listed as distinct attributes, so use the exact one that fits your task. The documented expressions include nt.selected and not nt.selected for selection state, and nt.sf or nt.sf false for selectionFlag. One small but useful detail: unlike the inherited node attribute, selected has no short name in the note space. Writing nt.selected avoids guessing at an abbreviation.

There is a similar pair for visibilityFlag: its short name is vf, and examples include nt.vf and nt.vf false. Treat the flag and the visible attribute as separate choices in your expression. The reference documents both, but does not make them synonyms.

A simple troubleshooting sequence

  1. Decide whether you are searching by note name, visibility, hidden state, selection, or a flag.

  2. Use the note prefix nt so the expression targets note nodes.

  3. Choose the full attribute name or its documented short name. For example, use nt.n for name or nt.v for visible.

  4. For a Boolean attribute, compare the positive expression with its documented negated form where available, such as nt.v and not nt.v.

This small vocabulary can turn a vague “where did that note go?” moment into a targeted check. For the complete list of note attributes and examples, see the SAMSON note attributes reference.

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

Comments are closed.