Visualizing#

SAMSON provides a handful of visual models (SBVisualModel) by default that help you visualize molecular systems.

Here is the list of the main visual models available by default in SAMSON:

Atomistic visual models:
- Ball and stick
- Licorice
- Lines
- Van der Waals
Surfaces:
- Gaussian surface
- Solvent accessible surface
- Solvent excluded surface
Secondary structure visual models:
- Cartoon
- Ribbons
- Tubes
Glycans - 3D-SNFG for depicting glycans

You can add more visual models from the SAMSON Connect - Marketplace.

See also

samson.SBVisualModel

Colorizing nodes

Applying visual models#

There are several ways to apply visual models using Python API.

Apply visual models via commands#

You can apply a visual model to nodes in the active document via actions using SAMSON.runCommand() first by selecting nodes and then invoking commands associated to visual models by their name (if nothing is selected, then a visual model will be applied to the whole document).

Note

When using the SAMSON.runCommand() function to add a visual model, it will be applied to the current selection or to the whole active document if nothing is selected.

In the example below, we apply the Ribbons visual model to receptors and the Licorice visual model to ligands and hide their default structural representation

Apply visual models via commands#

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

# 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')

In this case, a visual model is added automatically in the active document and the action is made undoable automatically.

See also

Running actions

You can get an indexer of visual models in the active document as follows:

Get an indexer of visual models in the active document#

# the short version of the NSL expression: 'n.t vm'
visualModelIndexer = SAMSON.getActiveDocument().getNodes("node.type visualModel")
print(f"Number of visual models: {len(visualModelIndexer)}")

Apply visual models via proxies#

A visual model can also be created using the SAMSON.makeVisualModel() function. This function requires a node indexer and either a public name of the visual model or its proxy information (the class name and the extension UUID).

Note

For the list of available visual models and their public names see: List of visual models.

See also

Getting nodes

Apply a visual model to a node indexer#

# get a node indexer, e.g. residues
# the short version of the NSL expression: 'n.t r'
nodeIndexer = SAMSON.getNodes("node.type residue")

# create an instance of the Ribbons visual model applied to the nodeIndexer
visualModel = SAMSON.makeVisualModel(nodeIndexer, "Ribbons")

if visualModel:
  # make the operation undoable
  SAMSON.beginHolding("Add visual model")

  # hold the node to make it creation undoable
  SAMSON.hold(visualModel)
  # create the node
  visualModel.create()

  # add the visual model to the active document
  SAMSON.getActiveDocument().addChild(visualModel)

  # stop holding the undoable operation
  SAMSON.endHolding()

List of visual models#

The following public names of visual models are available, by default in SAMSON:

‘Ball and stick’
‘Cartoon’
‘Gaussian surface’
‘Glycans’
‘Licorice’
‘Lines’
‘Ribbons’
‘Solvent accessible surface’
‘Solvent excluded surface’
‘Tubes’
‘Van der Waals’

This is not a full list. There might be more visual models available in your SAMSON depending on the extensions you have. And you can add more visual models from the SAMSON Connect - Marketplace. For example, here are some other visual models:

‘Pathline of the center of mass’
‘Polyhedra’

You can get the list of available visual models with their proxy informations as follows:

Get the list of available visual models#

visual_model_proxies = SAMSON.getProxyIndexer(SBClass.VisualModel)
for proxy in visual_model_proxies:
  print(proxy) # this should also print the public name

You can get the public name from a proxy via proxy.publicName.

Or you can get a dictionary of available public names of visual models and their proxies (not all visual models have public names):

Get a dictionary of available public names of visual models and their proxies#

visual_model_proxy_map = SAMSON.getVisualModelProxyMap()
for public_name, proxy in visual_model_proxy_map.items():
  # print the public name
  print(public_name)
  # print the proxy information
  #print(f"Name: {public_name}\tClass name: {proxy.name},\tExtension UUID: {proxy.elementUUID}")

You can also find a list of the exposed visual model classes available in SAMSON using the Exposed functionality viewer extension. Simply search for VisualModel in it.

Applying visual presets#

Visual presets (SBVisualPreset) provide an efficient way to apply visual representations and color schemes simultaneously to complex molecular systems.

Visual presets can be combined into visual preset groups (SBVisualPresetGroup) to apply multiple visual representations at once.

See also

User Guide: Visual presets

Colorizing nodes

SAMSON provides a set of default visual preset groups that you can access using the SBVisualPresetGroup.getDefaultVisualPresetGroups() function. Below we print all available default visual preset groups

Print all available visual presets#

# get all default visual preset groups
defaultVisualPresetGroups = SBVisualPresetGroup.getDefaultVisualPresetGroups()

# print names of default visual preset groups
for defaultVisualPresetGroup in defaultVisualPresetGroups:
    print(defaultVisualPresetGroup.name)

You can use default visual preset groups simply by accessing them and calling the SBVisualPresetGroup.apply() function:

Apply a default visual preset group#

# get an indexer of all structural models
# the short version of the NSL expression: 'n.t sm'
structuralModelIndexer = SAMSON.getNodes("node.type structuralModel")

# get all default visual preset groups
defaultVisualPresetGroups = SBVisualPresetGroup.getDefaultVisualPresetGroups()

if len(defaultVisualPresetGroups):
    # apply the first default visual preset group
    defaultVisualPresetGroups[0].apply(structuralModelIndexer)

Note

Materials (and, hence, color schemes that are part of materials) take precedence based on hierarchy: if the node has a material applied directly to it, then it will be colorized based on this material’s color scheme, else it will be colorized based on a color scheme of its parent node’s material. If none of the node’s parents has a material with a color scheme then a default colorization will be applied, e.g. CPK colors for atoms.

To remove materials from a node and its descendants call the SBNode.removeMaterialsFromDescendants() function on the node.

You can create you own visual presets - a visual preset gets several arguments (some of them are optional):

A selection: a Node Specification Language (NSL) expression and an arbitrary name for the selection which will be used for naming the visual model if one should be created.
Visual model information: a name of the visual model or a name of the visual model class and its extension’s UUID.
Color scheme information: a name of the color scheme or a name of the color scheme class and its extension’s UUID.
A color (SBColor) for a constant color scheme or a color palette (SBPalette) for a per-attribute color scheme.
A boolean flag indicating whether structural nodes corresponding to the selection should be hidden or shown.

Create and apply a visual preset#

# get an indexer of all structural models
structuralModelIndexer = SAMSON.getNodes("n.t sm")

# create a visual preset
visualPreset = SBVisualPreset(
    # selection
    selectionFilterString = "n.c receptor",
    selectionFilterName = "Receptor",
    # visual model: Ribbons
    visualModelName = "Ribbons",
    # hiding structural nodes
    hideStructureFlag = False)

# apply the visual preset
visualPreset.apply(structuralModelIndexer)

You can combine visual presets in a visual preset group to create more complex visualizations.

Create and apply a visual preset group#

# get an indexer of all structural models
structuralModelIndexer = SAMSON.getNodes("n.t sm")

# create a visual preset
visualPresetGroup = SBVisualPresetGroup("Receptor-ligand interaction",
  [
    SBVisualPreset(
      selectionFilterString = "n.c receptor",
      selectionFilterName = "Receptor",
      visualModelName = "Ribbons",
      colorSchemeName = "Constant",
      color = SBColor.white),
    SBVisualPreset(
      selectionFilterString = "n.c ligand",
      selectionFilterName = "Ligand",
      visualModelName = "Licorice"),
    SBVisualPreset(
      selectionFilterString = "a.s C in (n.t r within 5A of n.c ligand)",
      selectionFilterName = "Carbons in residues with at least one atom within 5A of ligands",
      visualModelName = "",
      colorSchemeName = "Constant",
      color = SBColor.white),
    SBVisualPreset(
      selectionFilterString = "n.c heavyAtomsWithLinkingBonds in (n.t r within 5A of n.c ligand)",
      selectionFilterName = "Residues (heavy atoms) with at least one atom within 5A of ligands",
      visualModelName = "Licorice"),
    SBVisualPreset(
      selectionFilterString = "n.c water",
      selectionFilterName = "Water",
      hideStructureFlag = True),
    SBVisualPreset(
      selectionFilterString = "a.s O in n.c water",
      selectionFilterName = "Water oxygen",
      visualModelName = "Licorice"),
    SBVisualPreset(
      selectionFilterString = "n.c monatomicIon",
      selectionFilterName = "Monatomic ions",
      visualModelName = "Van der Waals")
  ]
)

# apply the visual preset
visualPresetGroup.apply(structuralModelIndexer)

Visualizing

Contents

Visualizing#

Applying visual models#

Apply visual models via commands#

Apply visual models via proxies#

List of visual models#

Applying visual presets#