Find the Right Files Before You Touch the Model

When a molecular project contains many files, a small selection mistake can send you searching through the wrong part of the document—or applying a later operation to the wrong nodes. A useful first step is to be precise about what you are querying: file attributes match file nodes, not every kind of node in the molecular structure.

SAMSON’s Node Specification Language (NSL) gives file attributes their own attribute space: file, with the short name fi. That prefix makes a query’s scope easier to read at a glance. For example, fi.n "A" asks for file nodes by name. It is a small distinction, but one that helps prevent a common source of confusion: expecting a file-level query to describe atoms, residues, or other objects inside a file.

Start with the file name

The file attribute name is inherited from the general node attribute space. Its short name is n, and its values are strings in quotes. The documentation gives two examples:

  • fi.n "A"
  • fi.n "L*"

These examples show the file prefix, the short form of the name attribute, and quoted string values in one compact expression. The second example includes an asterisk, so it can be a useful pattern to test when working with names that share a recognizable beginning. If exact matching or pattern behavior matters for your task, check the NSL matching rules before relying on it.

Using the short form is optional in the sense that the attribute also has the full name name; the table identifies n as its short name. Whichever form you use, keep the fi scope visible when you mean to target files specifically.

Know which “selection” you mean

File nodes inherit two boolean attributes that are easy to conflate: selected and selectionFlag. Both can be used to express true or false conditions, but they are separate attributes in the reference. The examples include:

  • fi.selected
  • not fi.selected
  • fi.sf false
  • fi.sf

Here, selected has no short name in the file attribute space. In particular, the short name s available for node.selected is not available for file nodes. So use fi.selected rather than assuming fi.s will work.

selectionFlag, on the other hand, does have the short name sf. That gives you a compact way to refer to it, as in fi.sf or fi.sf false. The documentation lists both attributes independently; don’t assume that one is simply another spelling of the other. If a query’s results depend on selection state, make sure you have chosen the attribute that matches your intent.

A quick troubleshooting checklist

  1. Check the node type. Use the fi prefix when the target is a file node.
  2. Check the attribute spelling. For file names, use name or n. For the selection flag, use selectionFlag or sf.
  3. Keep string values quoted. The reference specifies quoted strings for names, as in fi.n "A".
  4. Don’t substitute shortcuts across attribute spaces. File nodes inherit attributes from node, but the file reference explicitly notes that selected does not use the node short name s.
  5. Test the smallest useful expression first. Start with a name or a single boolean condition, then add complexity only after confirming the intended file nodes are being matched.

This simple distinction—file scope, inherited name, and two separately named selection attributes—can make an NSL query easier to inspect and debug. For the complete attribute reference, see the SAMSON file attributes documentation.

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

Comments are closed.