Find the Notes That Matter: A Practical Guide to NSL Note Filters

As a molecular model grows, notes can become hard to manage alongside the structures and other objects in the scene. A useful first step is to narrow the set of notes you are working with: for example, by name, visibility, or selection state. In SAMSON, the Node Specification Language (NSL) provides a dedicated attribute space for this.

The note attribute space uses the prefix nt and matches only note nodes. That prefix is important: it makes your intent explicit and helps keep a query focused on notes rather than other kinds of nodes. The attributes listed for notes are inherited from the general node attribute space, so their names and behavior are shared with node attributes unless the note reference says otherwise.

Start with the question you want to answer

Before writing an expression, decide what you want to find. Are you looking for a note with a particular name? Notes that are hidden? Notes that are visible? Or notes with a particular selection or visibility flag? Choosing the relevant attribute first makes it easier to read and check the expression later.

  • Find notes by name: use nt.n, the short name for name. For example, nt.n "A" is an example of a name expression, and nt.n "L*" is another example shown in the reference.
  • Check hidden state: nt.h refers to hidden. The documented examples include nt.h and not nt.h.
  • Check visible state: nt.v is the short form of visible. The reference gives nt.v and not nt.v as examples.
  • Check selection state: use nt.selected or not nt.selected. Unlike some other inherited attributes, selected has no short name in the note attribute space.

Keep similar-looking attributes distinct

Some attributes have names that sound related, but the reference lists them separately. visible and visibilityFlag are distinct attributes; likewise, selected and selectionFlag are distinct. If your question is about a flag, use the flag attribute rather than assuming the state attribute means the same thing.

The short names for the flags are vf for visibilityFlag and sf for selectionFlag. The documented forms include nt.vf false, nt.vf, nt.sf false, and nt.sf. When you are unsure which attribute fits your task, spelling out the full attribute name can make an expression easier for collaborators to understand.

A small, repeatable filtering routine

  1. Begin with the note prefix: nt.
  2. Add the attribute that describes the criterion: for example, nt.n for a name or nt.v for visibility.
  3. For a Boolean condition, decide whether you want the attribute itself or its negation, as in nt.h versus not nt.h.
  4. For names, keep the value in quotation marks, as in nt.n "A".
  5. Check that you chose the state attribute or flag attribute intentionally.

This approach is useful because it turns an ambiguous instruction—“show me the relevant notes”—into a precise criterion that can be inspected and adjusted. It also makes expressions easier to revisit later: the prefix identifies the node type, while the attribute explains what is being tested.

For the full list of note attributes and their examples, see the SAMSON note attribute reference.

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

Comments are closed.