Running actions

The SAMSON interface (SAMSON) provides the SAMSON.runCommand() function to trigger actions and commands by the names you see in the SAMSON interface.

Use commands when you want Python to do the same kind of operation a user can trigger from the SAMSON interface. Use SAMSON.getNodes() instead when you need nodes returned to Python for processing. See Python scripting mental model for a compact decision table.

Note

We use words action and command interchangeably.

Warning

Commands are identified by names shown in the interface. If an action is renamed, unavailable, or ambiguous, a script that runs it by text may need to be updated or use a more specific action path.

Running actions by name

The SAMSON.runCommand() function accepts the name of an action, or a hierarchical path to it, and returns whether that action was found and triggered.

Run a SAMSON action

# run the 'Receptors' 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 also searches for actions within sub-menus of other actions. So, for example, you can run the Residues > Terminal residues command as follows:

SAMSON.runCommand("Terminal residues")

If there is an ambiguity, for example because several actions have the same name, provide the full path with hierarchical levels separated by >, for example Top parent action name > Parent action name > Action name.

Run a SAMSON command that is in a sub-menu

SAMSON.runCommand("Residues > Terminal residues")

You can also get an action (SBAction) using SAMSON.getActionByText() function, check whether it exists, and trigger it:

Find an action by its text and trigger it

action = SAMSON.getActionByText("Terminal residues")
if action:
    print("Found the action")
    action.trigger()
else:
    print("Could not find the action")

You can apply multiple commands one-by-one to create a pipeline of actions.

Apply the Licorice visual model to ligands and hide the default structural representation of ligands

# run the command named 'Ligands' that selects ligands
SAMSON.runCommand('Ligands')
# apply visual models only if something was found (selected)
if SAMSON.getActiveDocument().hasSelectedNodes():
    # apply the Licorice visual model via the command named 'Licorice'
    SAMSON.runCommand('Licorice')
    # hide the current selection
    SAMSON.runCommand('Hide selection')
    # clear the current selection in the active document
    SAMSON.runCommand('Deselect all')

Note

Most of the commands executed via SAMSON.runCommand() are undoable because they internally use SAMSON.beginHolding() and SAMSON.endHolding(). For some actions, however, you may still want to wrap the call in SAMSON.holding. See Making operations undoable for more information.

Selecting nodes using runCommand and NSL

The SAMSON.runCommand() function can also be used to perform selections using Node Specification Language (NSL).

Select using NSL string and runCommand

# select receptors and ligands
SAMSON.runCommand("nsl: receptor or ligand")

Show residues in binding sites as licorice

# clear the current selection
SAMSON.runCommand("Deselect all")

# select residues within 5A of ligands
# short version of NSL: n.t r w 5A of n.c lig
SAMSON.runCommand("nsl: node.type residue within 5A of node.category ligand")

if SAMSON.getActiveDocument().hasSelectedNodes():
    # add Licorice visual model to the current selection
    SAMSON.runCommand("Licorice")
    # clear the current selection
    SAMSON.runCommand("Deselect all")

Please refer to Select using NSL for more information.

Choosing commands, selections, and node retrieval

Goal	Use	Notes
Trigger an interface command	SAMSON.runCommand("Command name")	Returns whether the command was found and triggered.
Select nodes with NSL	SAMSON.runCommand("nsl: ...")	Changes the selection in SAMSON.
Process nodes in Python	SAMSON.getNodes(...)	Returns an SBNodeIndexer and does not by itself select nodes.

Running actions by UUID

Since action names can sometimes be ambiguous, you can also run an action using its UUID (SBUUID):

Run an action by its UUID

if SAMSON.runCommand(actionUUID) == False:
    print("Could not find the command")

You can get an action’s UUID via its UUID property.

You can also get an action (SBAction) by its UUID using SAMSON.getAction() function, check whether it exists, and trigger it:

Find an action by UUID and trigger it

action = SAMSON.getAction(SBUUID(""))
if action:
    print("Found the action")
    action.trigger()
else:
    print("Could not find the action")