Selecting nodes#

In SAMSON, to do some operations (inspect, edit, move, simulate, etc) with nodes (atoms, residues, molecules) it is necessary to select them.

In Python Scripting, you can select nodes in several ways:

See also

User Guide: Selecting

User Guide: Node types

User Guide: Node Specification Language

Select using actions#

You can use run actions/commands available in SAMSON by their names visible in SAMSON (see Running actions). For that, you can use the SAMSON.runCommand() function that gets a name of an action, or a hierarchical path to it, and returns whether such action was found and triggered.

Run a SAMSON action#
# run the 'Receptor' command that selects receptors from the current selection
# or from the active document if the current selection is empty
if SAMSON.runCommand("Receptors") == False:
    print("Could not find the command")

This will also search for actions within sub-menus of other actions/commands. So, for example, you can run the Residues > Terminal residues command as follows

SAMSON.runCommand("Terminal residues")

In case if there is an ambiguity, e.g. there are multiple actions with the same name, then provide a path to it separating hierarchical levels with >, e.g.: Parent action name > Action name

Run a SAMSON command that is in a sub-menu#
SAMSON.runCommand("Residues > Terminal residues")

See also

Running actions

Select using NSL#

SAMSON has a powerful Node Specification Language (NSL) that may be used to select data graph nodes based on their types and other various properties.

If you want to just select nodes based on an NSL expression, then you can use the SAMSON.runCommand() function to perform selections. For that, supply an NSL expression prefixed with 'nsl: ', e.g. 'nsl: n.t a' to select all atoms.

Select using NSL string and runCommand#
# select receptors and ligands
SAMSON.runCommand("nsl: n.c receptor or n.c ligand")

Note

When performing a selection with SAMSON.runCommand() and NSL, SAMSON will automatically make the selection action undoable.

Select via nodes#

Each node has a selectionFlag property that you can modify to make the node selected or not.

Selecting a node#
# get the first node in the active document
node = SAMSON.getActiveDocument().getChildren()[0]

# make the operation undoable
SAMSON.beginHolding('Select node')

node.selectionFlag = True

# stop holding the undoable operation
SAMSON.endHolding()

Often it is necessary to select nodes based on their hierarchy, attributes, or perform more complex selections. For that, you can use getNodes functions that return a node indexer (SBNodeIndexer, basically a list of nodes) based on the provided NSL string:

  • 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.

# get a node indexer with all nodes in the active document
# named "CA" (i.e., alpha Carbons) that are within 5 angstroms of any sulfur atom
nodeIndexer = SAMSON.getNodes('"CA" within 5A of S')

# make the operation undoable
SAMSON.beginHolding('Select nodes')

# clear the selection in the active document
# note: if you want to add to the current selection then don't invoke this function
SAMSON.getActiveDocument().clearSelection()

# loop over the nodes
for node in nodeIndexer:
    # select nodes by setting the selectionFlag to True for them
    node.selectionFlag = True

# stop holding the undoable operation
SAMSON.endHolding()

Please refer to the Getting nodes section for more information and examples.

Clear selection#

To clear selection in the active document:

# make the operation undoable
SAMSON.beginHolding('Clear selection')

# clear the selection in the active document
SAMSON.getActiveDocument().clearSelection()

# stop holding the undoable operation
SAMSON.endHolding()

If you are working not with an active document but with another document or some temporary nodes outside of a document then you can use getNodes functions with NSL string to obtain only the selected nodes and change their selectionFlag property.

Clear selection flag of nodes#
# get nodes descendant from a structuralModel node that have selectionFlag set to True
nodeIndexer = structuralModel.getNodes('node.selectionFlag true')

# loop over the nodes
for node in nodeIndexer:
    # deselect nodes by setting the selectionFlag to False for them
    node.selectionFlag = False

Selection examples#

The example below shows how to select bonds which center lies in between of two planes: z_min and z_max. If you want to select bonds which center lies on a specific plane, just set z_min=z_max.

Select bonds based on the bond center location#
# get an indexer of all bonds in the active document.
# Here we use the Node Specification Language to get only bonds
bondIndexer = SAMSON.getNodes('node.type bond')

# two planes: 1.5A and 3.5A
z_min = SBQuantity.angstrom(1.5)
z_max = SBQuantity.angstrom(3.5)

# an indexer in which we will be adding the desired bonds
selectionIndexer = SBNodeIndexer()

# loop over all the bonds
for bond in bondIndexer:
    # get the z-coordinate of the bond's mid point
    bondMidPointZ = bond.getMidPoint()[2]
    # check whether the bond lies in between of desired planes
    if bondMidPointZ >= z_min and bondMidPointZ <= z_max:
        # Add the bond to the selection indexer.
        # We can set the selectionFlag to True for the bond here,
        # but, for the sake of the example, we add the selected bonds in an indexer
        # which can be used later.
        selectionIndexer.addNode(bond)

# make the operation undoable
SAMSON.beginHolding("Select bonds")

# Clear the selection in the active document
SAMSON.getActiveDocument().clearSelection()

# loop over the desired bonds
for bond in selectionIndexer:
    # select these bonds by setting the selectionFlag to True for them
    bond.selectionFlag = True

# stop holding the undoable operation
SAMSON.endHolding()