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:
using domain-specific selection actions, e.g., the ones you can see in the Select menu,
script selections in Python by combining these methods, utilizing the hierarchical information, relations between nodes and other node properties.
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 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
SAMSON.runCommand("Residues > Terminal residues")
See also
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 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.
# 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 theSAMSON
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.
# 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
.
# 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()