How to Efficiently Search and Filter Molecular Files in SAMSON Using NSL

When working with large molecular systems or projects involving multiple molecular files, it’s easy to lose time looking for relevant data within complex models. Fortunately, SAMSON’s Node Specification Language (NSL) offers a clean, expressive way to query and filter elements in your molecular documents—especially when dealing with file nodes.

This post introduces how to use NSL to work more efficiently with file nodes, saving you time and helping you better organize your molecular data in SAMSON.

What are File Nodes?

In SAMSON, models and simulations are made up of nodes. A file node is a node that represents imported content—such as a PDB or MOL2 file—and is a gateway to structured data. Managing these file nodes is much easier when you can filter them by name, selection state, or internal flags.

Using the file Attribute Space

In NSL, file (or abbreviated as fi) targets file nodes specifically. Here’s a breakdown of a few properties that help you filter them efficiently:

1. Name Matching

Use fi.n to search by file name. This is very useful when your workspace includes multiple files and you need to pick one out quickly.

This query matches all file nodes with names starting with “Ligand”. You can also use exact names like:

2. Selected Status

You can check whether a file node is currently selected using:

And to find all unselected file nodes:

This comes in handy when preparing a subset of files for export or editing and you want to isolate those that haven’t been targeted yet.

3. Selection Flags (selectionFlag)

This is an additional internal flag you can use to mark file nodes arbitrarily. For example, if you’re using scripts or interactive selections to batch-process data, selectionFlag is a useful property to keep track of custom states.

Which returns all file nodes with the selection flag set.

Combining Attributes

The real strength lies in combining these attributes. For example, to find all selected file nodes whose name contains “Receptor”:

Or all file nodes marked with a selectionFlag that are not yet selected:

Why It Matters

Whether you’re modeling protein-ligand interactions, working with large compound libraries, or organizing simulation results, being able to quickly find, mark, and organize file nodes can save you significant time. NSL provides a readable and powerful mechanism to do just that.

To dive deeper into the properties available for file nodes and how they connect with other node types in SAMSON’s architecture, read the official documentation here: File Node Attributes in NSL.

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