Molstar (Mol*)

Molstar is the molecular visualizer bundled with Horus. Mol* is an open source molecular visualizer written in TypeScript and WebGL. You can find tutorials, documentation and the source code of Mol* at https://molstar.org.

In order to control Mol* from Horus, we use the MolstarAPI, a bridge built for communicating Blocks with the molecular visualizer.

MolstarAPI

MolstarAPI is a library for creating and manipulating molecular structures in the embedded Mol* visualizer inside Horus. It is designed to be used within Blocks in order to add, visualize or edit molecular structures.

In order to control the molecular visualizer within a Block action, you need to import the MolstarAPI class and use the desired methods.

from HorusAPI import MolstarAPI

# Loading a structure is simple
my_pdb_file = "/path/to/1crn.pdb"
molecule_name = "1crn crystal structure"

MolstarAPI().addPDB(my_pdb_file, molecule_name)

# So is loading a trajectory
my_topology = "/path/to/topology"
trajectory = "/path/to/trajectory"

MolstarAPI().loadTrajectory(my_topology, trajectory)

Mol* actions will be stored in the flow and applied to the canvas in the order they were invoked. If a flow is not yet open, the actions will queue and execute once it opens. The flow is then saved with the updated Mol* state.

Selections and Theming

MolstarAPI provides advanced selection and theming options through the following models and enums.

Selection Types

Selections can be made using different languages such as VMD, PyMOL, Jmol, or MolScript:

selection = MolecularSelection(script="resid 50 to 100", language=SelectionLanguage.VMD)

You can also use structured selections:

selection = MolecularSelection(chain="A", residue_range={"start": 50, "end": 100})

Themes

Example: Apply a cartoon representation colored by chain ID and with uniform sizing:

theme = MolstarThemeOptions(
    representation=MolRepresentations.CARTOON,
    color=ColorTheme.chain_id,
    size=SizeTheme.uniform
)

Proximity Selections

Select all atoms within a certain distance from another selection:

near_ligand = MolecularSelection(
    within_distance={
        "radius": 5.0,
        "target": MolecularSelection(residue=150)
    }
)

Examples

from horus.api import MolstarAPI
from horus.extensions.molstar.model import (
    MolstarThemeOptions,
    MolRepresentations,
    MolecularSelection,
    ColorTheme,
    SizeTheme,
)

# Load a molecule using cartoon representation
label = "1abc"
filePath = "/path/to/1abc.pdb"
MolstarAPI().addMolecule(
    filePath,
    label=label,
    theme=MolstarThemeOptions(
        representation=MolRepresentations.CARTOON,
    ),
)

# Highlight a specific residue using ball-and-stick representation
MolstarAPI().addComponent(
    label,
    "Very cool residue",
    selection=MolecularSelection(chain_and_residue={"chain": "A", "residue": 25}),
    theme=MolstarThemeOptions(
        representation=MolRepresentations.BALL_AND_STICK,
        color=ColorTheme.uniform,
        colorParams={
            "value": "red" # You can set X11 color names (yellow, red, blue, aliceblue...) or use a HEX color (i.e. #FF0000)
        },
        size=SizeTheme.physical,
        sizeParams={"scale": 2},
    ),
)

# Highlight a residue range with a surface representation and uncertainty coloring
MolstarAPI().addComponent(
    label,
    "A range of cool residues",
    selection=MolecularSelection(script="resid 10 to 22", language=SelectionLanguage.VMD),
    theme=MolstarThemeOptions(
        representation=MolRepresentations.MOLECULAR_SURFACE,
        color=ColorTheme.uncertainty,
        colorParams={"domain": [-15, 15]},
        size=SizeTheme.physical,
        sizeParams={"scale": 1.5},
    ),
)

API Methods

The MolstarAPI module

class ColorTheme(value)

A list of the color themes available in Mol*

atom_id = 'atom-id'

carbohydrate_symbol = 'carbohydrate-symbol'

cartoon = 'cartoon'

chain_id = 'chain-id'

default = 'default'

element_index = 'element-index'

element_symbol = 'element-symbol'

entity_id = 'entity-id'

entity_source = 'entity-source'

external_structure = 'external-structure'

external_volume = 'external-volume'

formal_charge = 'formal-charge'

hydrophobicity = 'hydrophobicity'

illustrative = 'illustrative'

model_index = 'model-index'

molecule_type = 'molecule-type'

occupancy = 'occupancy'

operator_hkl = 'operator-hkl'

operator_name = 'operator-name'

partial_charge = 'partial-charge'

polymer_id = 'polymer-id'

polymer_index = 'polymer-index'

residue_name = 'residue-name'

secondary_structure = 'secondary-structure'

sequence_id = 'sequence-id'

shape_group = 'shape-group'

structure_index = 'structure-index'

trajectory_index = 'trajectory-index'

uncertainty = 'uncertainty'

uniform = 'uniform'

unit_index = 'unit-index'

volume_segment = 'volume-segment'

volume_value = 'volume-value'

class MolRepresentations(value)

Available molstar representations

BACKBONE = 'backbone'

BALL_AND_STICK = 'ball-and-stick'

CARBOHYDRATE = 'carbohydrate'

CARTOON = 'cartoon'

ELLIPSOID = 'ellipsoid'

GAUSSIAN_SURFACE = 'gaussian-surface'

GAUSSIAN_VOLUME = 'gaussian-volume'

LABEL = 'label'

LINE = 'line'

MOLECULAR_SURFACE = 'molecular-surface'

ORIENTATION = 'orientation'

PLANE = 'plane'

POINT = 'point'

PUTTY = 'putty'

SPACEFILL = 'spacefill'

class MolecularSelection(*, script: str | None = None, language: SelectionLanguage | None = SelectionLanguage.VMD, chain: str | None = None, auth_chain: str | None = None, entity: str | None = None, residue: int | None = None, auth_residue: int | None = None, residue_range: dict | None = None, auth_residue_range: dict | None = None, atom_name: str | None = None, auth_atom_name: str | None = None, element_symbol: str | None = None, atom_id: int | None = None, atom_index: int | None = None, insertion_code: str | None = None, chain_and_residue: dict | None = None, auth_chain_and_residue: dict | None = None, secondary_structure: Literal['helix', 'sheet', 'coil'] | None = None, type: Literal['all', 'polymer', 'protein', 'nucleic', 'water', 'ion', 'lipid', 'branched', 'ligand', 'non-standard', 'coarse'] | None = None, within_distance: dict | None = None)

Comprehensive molecular selection model supporting all Mol* selection types

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

atom_id: int | None

atom_index: int | None

atom_name: str | None

auth_atom_name: str | None

auth_chain: str | None

auth_chain_and_residue: dict | None

auth_residue: int | None

auth_residue_range: dict | None

chain: str | None

chain_and_residue: dict | None

element_symbol: str | None

entity: str | None

insertion_code: str | None

language: SelectionLanguage | None

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

residue: int | None

residue_range: dict | None

script: str | None

secondary_structure: Literal['helix', 'sheet', 'coil'] | None

type: Literal['all', 'polymer', 'protein', 'nucleic', 'water', 'ion', 'lipid', 'branched', 'ligand', 'non-standard', 'coarse'] | None

within_distance: dict | None

class MolstarAPI(*args, **kwargs)

API for interacting with Mol* visualizer inside Horus

addBox(center: list[float], sides: list[float] | None = None, lineSize: float = 1, color: str | None = None, opacity: float = 1) → None

Adds a box to the scene.

Parameters:

• center – The x, y and z coordinates of the center of the box as a list of [x, y ,z]

• sides – The a, b and c lengths of the box as a list of [a, b ,c].

Defaults to [1, 1, 1] :param lineSize: The width of the lines. Defaults to 1. :param color: The color of the box as an RGB hex string (i.e. #0000FF) Defaults to random color. :param opacity: The opacity of the box (0.0 - 1.0). Defaults to 1.

addComponent(label: str, selectionLabel: str, selection: MolecularSelection, theme: MolstarThemeOptions | None = None)

Adds a component to an existing structure given the label and a selection.

Parameters:

• label – The loaded structure to which apply the component

• selectionLabel – The new component label

• selection – The specific selection of the structure provided in the label

• theme – Custom theme to apply to the selection

addMolecule(filePath: str, label: str | None = None, theme: MolstarThemeOptions | None = None) → None

Adds the given Molecule file to Mol*

Parameters:

• filePath – The path to the molecule file

• label – The label for the molecule. Optional. Defaults to the filename

addSphere(center: list[float], radius: float, color: str | None = None, opacity: float = 1) → None

Adds a sphere to the scene.

Parameters:

• x – The x coordinate of the sphere in Angstroms

• y – The y coordinate of the sphere in Angstroms

• z – The z coordinate of the sphere in Angstroms

• radius – The radius of the sphere in Angstroms

• color – The color of the sphere as an RGB hex string (i.e. #0000FF)

• opacity – The opacity of the sphere (0.0 - 1.0)

focusResidue(residue: int, structureLabel: str | None = None, chain: str | None = None, nearRadius: int = 5) → None

Focuses on the given residue

Parameters:

• residue – The sequence number of the residue to focus

• structureLabel – The label of the structure to focus

• chain – The chain ID of the residue to focus

• nearRadius – The radius around the residue to display nearby residues

loadTrajectory(topology: str, trajectory: str, label: str | None = None) → None

Adds the given trajectory file to Mol*

Parameters:

• topology – The path to the topology file

• trajectory – The path to the trajectory file

• label – The label for the trajectory. Optional. Defaults to the filename

reset() → None

Resets the visualizer

setBackgroundColor(color: str) → None

Sets the background color of the scene

Parameters:

color – The color to set the background to as an RGB hex string (i.e. #0000FF)

setSpin(speed: float = 1) → None

Sets the spin of the molecule.

Parameters:

speed – The rotation speed. Defaults to 1. To stop it, set the speed to 0

class MolstarThemeOptions(*, representation: MolRepresentations = MolRepresentations.CARTOON, representationParams: dict[str, Any] | None = None, color: ColorTheme | str | None = None, colorParams: dict[str, Any] | None = None, size: SizeTheme | str | None = None, sizeParams: Dict[str, Any] | None = None)

Options for updating a model’s theme

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

class Config

use_enum_values = True

color: ColorTheme | str | None

colorParams: dict[str, Any] | None

model_config: ClassVar[ConfigDict] = {'use_enum_values': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

representation: MolRepresentations

representationParams: dict[str, Any] | None

size: SizeTheme | str | None

sizeParams: Dict[str, Any] | None

class SelectionLanguage(value)

Selection language types supported by Mol*

JMOL = 'jmol'

MOL_SCRIPT = 'mol-script'

PYMOL = 'pymol'

VMD = 'vmd'

class SizeTheme(value)

A list of the size themes available in Mol*

default = 'default'

physical = 'physical'

shape_group = 'shape-group'

uncertainty = 'uncertainty'

uniform = 'uniform'

volume_value = 'volume-value'