Running actions

SAMSON interface (SAMSON) provides the SAMSON.runCommand() function to easily trigger actions/commands available in SAMSON by their names visible in SAMSON.

Note

We use words action and command interchangeably.

Running actions by name

The SAMSON.runCommand() function gets a name of an action or a hierarchical path to it, and it 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("Receptor") == False:
    print("Could not find the command")

This will also search 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")

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.: 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 document.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 via the internal use of SAMSON.beginHolding() and SAMSON.endHolding(). But for some you might need wrap them into SAMSON.beginHolding() and SAMSON.endHolding(). See the Making operations undoable section 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 bindings 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.

Running actions by UUID

Since the names of actions might in some cases be ambiguous, i.e. there might be several actions named the same (the use of the full action path should help here), 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")