Quickly find and manage notes in large molecular models using NSL

When working with complex biomolecular structures or simulations, it is common for molecular modelers to annotate specific regions using notes. These annotations, often rich in metadata, help track hypotheses, document processes, or highlight specific structural features. However, as models grow in complexity, managing these notes effectively can become a pain point.

SAMSON, the integrative platform for molecular design, provides a powerful solution: the Node Specification Language (NSL). NSL allows advanced querying of nodes—including notes—based on their attributes. In this post, we’ll explore how to use NSL to query note attributes specifically, helping you streamline your workflow when navigating annotated structures.

What is a note node?

In SAMSON, notes are a type of node that can be attached to molecular models. They might indicate measurements, mark mutations, comment on chemical relevance, or summarize observations. Because they are treated as nodes, they can be targeted using NSL queries just like atoms, molecules, or trajectories.

Using the nt attribute space

Note attributes belong to the nt attribute space in NSL. This attribute space matches only note nodes, which makes it easier to isolate and manipulate these annotations without affecting the rest of the model.

Essential note attributes you can use in your queries

Several attributes inherited from generic node attributes are available for notes, and you can use them to search or filter annotations. Here’s a practical overview of key ones:

  • nt.h (hidden): Indicates whether the note is hidden.
    nt.h returns all hidden notes.
    not nt.h returns visible notes only.
  • nt.n (name): Searches for notes with specific names or name patterns using wildcards.
    nt.n "Mutation A123" finds a specific note.
    nt.n "Mut*" finds all notes with names starting with “Mut”.
  • nt.selected: Returns notes that are currently selected. No short name for this attribute.
    nt.selected or not nt.selected.
  • nt.sf (selectionFlag): Finds notes based on their selection flags, a more persistent selection state.
    nt.sf or nt.sf false.
  • nt.vf (visibilityFlag): Find notes with a certain visibility flag state.
    Handy for debug-type annotations.
    nt.vf or nt.vf false.
  • nt.v (visible): Returns notes that are visible in the workspace.
    nt.v or not nt.v.

Why does this matter?

In large molecular models with tens or hundreds of annotations, being able to search through notes by specific properties saves time and reduces visual clutter. For example, quickly toggling the visibility of all notes using nt.v or not nt.v allows you to focus on structure without being distracted by comments. Searching by partial name with nt.n "Hydro*" helps you find all water-related annotations in seconds.

Tip: Combine attributes for precision

You can combine multiple NSL queries for more precise control. For instance, to find visible notes with names that start with “Conf”, you could use:

This is useful when annotating different classes of phenomena, such as conformations, mutations, or experimental constraints.

Conclusion

Using NSL to query note attributes is a straightforward but powerful way to bring order to your annotations. Whether you’re preparing figures, exploring hypotheses, or documenting your workflow, NSL empowers you to manage and interact with your notes efficiently.

To explore all available note attributes, visit the official documentation: SAMSON Note Attributes Documentation.

SAMSON and all SAMSON Extensions are free for non-commercial use. You can download SAMSON at https://www.samson-connect.net.

Comments are closed.