Getting nodes

Often you need to work on specific nodes, pass them to other functions, or perform more precise selections than the built-in actions provide (see Selecting nodes). For that, you can use the getNodes functions, which return a node indexer (SBNodeIndexer, essentially a list-like collection of nodes) based on a Node Specification Language (NSL) expression:

• SAMSON.getNodes from the SAMSON interface, returns a node indexer for the active document.

• SBNode.getNodes applied to a specific node, returns a node indexer with nodes descending from this node.

Use SAMSON.getNodes() when you need nodes in Python. Use SAMSON.runCommand() with an nsl: prefix when your goal is to change the visible selection in SAMSON.

See also

User Guide: Node types

User Guide: Node Specification Language

Python scripting mental model

Note

Getting nodes does not by itself select them in SAMSON. To select retrieved nodes, set their selectionFlag in an undoable operation, as shown in Select via nodes.

Getting nodes using NSL

# get a node indexer with all hydrogens in the active document
nodeIndexer1 = SAMSON.getNodes('Hydrogen')
# add in this node indexer all carbons in the active document
SAMSON.getNodes(nodeIndexer1, 'Carbon')

# get a node indexer with all hydrogens bonded to oxygens in the active document
nodeIndexer2 = SAMSON.getNodes('H linking O')

# get a node indexer with all nodes named "CA" that are within 5 angstrom of any sulfur atom
# in the active document
nodeIndexer3 = SAMSON.getNodes('"CA" within 5A of S')

# get a node indexer with all molecule nodes in the active document
nodeIndexer4 = SAMSON.getNodes('node.type molecule')

if len(nodeIndexer4):
    # get a node indexer with all atoms within the first molecule
    nodeIndexer5 = nodeIndexer4[0].getNodes('node.type atom')

# populate a node indexer with all residues within the molecules from nodeIndexer4
nodeIndexer6 = SBNodeIndexer()
for node in nodeIndexer4:
    node.getNodes(nodeIndexer6, 'node.type residue')

You can iterate over a node indexer much like a Python list:

# get a node indexer with all atoms in the active document
nodeIndexer = SAMSON.getNodes('node.type atom')

# print the size of the node indexer
print(len(nodeIndexer))

if len(nodeIndexer):
    # prints information on the last node (atom) in the node indexer
    print(nodeIndexer[-1])

for node in nodeIndexer:
    # do something, e.g. print info on the node
    print(node)

# usage of list comprehensions:
# construct a list of x-coordinates of atoms in nanometers
atomXCoords = [atom.getX().nm for atom in nodeIndexer]

You can delete or add a node from the indexer, or check if it is present in it:

# get a node indexer with all atoms in the active document
nodeIndexer = SAMSON.getNodes('node.type atom')

if len(nodeIndexer):
    # get the 1st atom from the node indexer
    atom = nodeIndexer[0]
    # remove the atom from the node indexer
    nodeIndexer.removeNode(atom)
    # check if the node indexer has the atom
    print(nodeIndexer.hasNode(atom))
    # add atom back to the node indexer
    nodeIndexer.addNode(atom)

The next example shows a simple use of the NSL, node indexers, and how to make changes to node attributes.

# get a node indexer with all molecule nodes in the active document
moleculeIndexer = SAMSON.getNodes('node.type molecule')

if len(moleculeIndexer):
    # print info on the 1st molecule
    print(moleculeIndexer[0])
    # get atoms that are in this molecule
    atomIndexer = moleculeIndexer[0].getNodes('node.type atom')

    if len(atomIndexer):
        # get the 1st atom in node indexer
        atom = atomIndexer[0]
        # print the atom type
        print(atom.type)
        # print the atom information
        print(atom)
        # return the atom's atomic weight
        print(atom.atomicWeight)
        # select the atom: it will be highlighted
        atom.selectionFlag = True
        # get the atom's position
        atom.getPosition()
        # shift the position of the chosen atom by 100 picometers (pm) in x-direction
        atom.setX(atom.getX() + SBQuantity.pm(100))

Common mistakes

• Assuming an indexer is non-empty before indexing it. Check len(nodeIndexer) first.

• Confusing node retrieval with selection. Retrieval gives Python a list-like object; selection changes what is highlighted in SAMSON.

• Changing node properties from a retrieved indexer without SAMSON.holding when undo is expected.