Source code#

Plugins#

Variables#

class PluginVariable(id: str, name: str, description: str, type: VariableTypes | str, defaultValue: Any | None = None, allowedValues: List[Any] | None = None, category: str | None = None, disabled: bool = False, required: bool = False, placeholder: str | None = None)#

Class that defines a variable that can be used in a PluginBlock.

Parameters:

  • name – The name of the variable.

  • description – A description of the variable.

  • type – The type of the variable. Assign it using the VariableTypes class.

  • defaultValue – The default value of the variable.

  • id – The ID of the variable.

  • allowedValues – A list of allowed values for the variable.

  • disabled – Whether the variable is disabled or not

  • required – Whether the variable is required or not.

This will show the variable in orange when not connected. :param placeholder: The placeholder of the input field.

class VariableGroup(id: str, name: str, description: str, variables: List[PluginVariable], allowedValues: List[Any] | None = None, category: str | None = None, disabled: bool = False, required: bool = False)#

A group of varaibles to be used together as input.

Initialize a VariableGroup

Parameters:

  • id – The ID of the variable group (must be unique).

  • name – The name of the variable group.

  • description – A description of the variable group.

  • variables – The list of variables in the group.

  • allowedValues – In this case, the allowed values will indicate in

the GUI which groups can be connected (with the same allowedValues) :param disabled: This will set all the variables under the group as disabled

class VariableTypes(value)#

The types of variables.

ANY = 'any'#

Any type of variable.

This type of variable will not render anything, as it is meant to be used as a connection between blocks.

ATOM = 'atom'#

An atom to be selected from a loaded structure.

Will enable ball-and-stick visualization in Mol* to select the atom.

BOOLEAN = 'boolean'#

A boolean value. True or False.

Will render as a checkbox.

BOX = 'box'#

A box to be rendered in Mol*.

Will render as an interactive box viewer. The user can select the center and the size of each side of the box.

This variable will return a dictionary with the following keys:

{
    "metrics": {
        "x0": 0,
        "x1": 5,
        "x2": 0,
        "x3": 0,
        "y0": 0,
        "y1": 0,
        "y2": 5,
        "y3": 0,
        "z0": 0,
        "z1": 0,
        "z2": 0,
        "z3": 5
    },
    "radialSegments": 2,
    "radiusScale": 5,
}
CHAIN = 'chain'#

A chain to be selected from a loaded structure.

Will render as a dropdown with the list of chains. The type of the variable will be a dictionary with the following keys:

  • index: The index of the chain in the structure.

  • name: The name of the chain.

  • residues: The list of residues in the chain.

  • structure: The structure object variable where the atom is located.

This last variable contains the properties of the STRUCTURE variable.

CHECKBOX = 'checkbox'#

A checkbox variable. It will render as a list of checkboxes. Multiple can be selected at the same time.

Setup the allowedValues parameter to define the list of options such as [“A”, “B”, “C”].

CODE = 'code'#

A code variable. This will be rendered as a code editor. The resulting value will be a code snippet as a string.

You can select the language of the code with the allowedValues parameter. For example, for python:

allowedValues = [“python”]

CONSTRAINED_NUMBER_RANGE = '[number, number, number, constrain]'#

A range of numbers like 1-10.

Can be made an Integer range or a Float range depending on the step.

Will render as a slider with tho dragging handles. Used to define a range between to points. Use allowedValues to define: [min, max, step].

  • The first number in the list is the minimum value.

  • The second number in the list is the maximum value.

  • The third number in the list is the step.

Will return two numbers, one for each handle.

CUSTOM = 'custom'#

A custom variable. It can contain any type of data but allows connections only from other custom variables that contain the same strings inside the allowedValues list. Just like ANY, it will not render any input field.

For example, a custom variable with allowedValues = [“A”, “B”, “C”] can be connected to another custom variable with allowedValues = [“B”]

FILE = 'file'#

A file.

  • On the server: Will open the server file explorer.

  • On the desktop: Will render as a system file picker.

FLOAT = 'float'#

A floating point number like 1.0, 2.5, 3.1415…

Will render as a number input with increment/decrement buttons. Accepts only floats.

FOLDER = 'folder'#

A folder.

  • On the server: Will open the server file explorer.

  • On the desktop: Will render as a system folder picker.

HETERORES = 'heterores'#

A hetero residue to be selected from a loaded structure.

Will render as a list of hetero residues. The type of the variable will be a dictionary with the following keys:

  • index: The index of the residue in the structure.

  • name: The name of the residue.

  • atoms: The list of atoms in the residue.

  • structure: The structure object variable where the atom is located.

This last variable contains the properties of the STRUCTURE variable.

INTEGER = 'integer'#

An integer number like 1, 2, 3…

Will render as a number input with increment/decrement buttons. Accepts only integers.

LIST = 'list'#

VariableList will be automatically converted to a list of variables.

Will render as a table with an input field and an add button.

MULTIPLE_STRUCTURE = 'multiple_structure'#

Multiple molecular structures to be selected from Mol*.

Will render as a list of checkboxes with the list of loaded structures. The type of the variable will be a list of dicts with the following data:

  • id: The ID of the structure.

  • name: The name of the structure.

  • type: The type of the structure (CIF, PDB…).

  • structure: The structure file contents (CIF, PDB… string)

NUMBER = 'number'#

A number like 1, 2.5, 3.1415…

Will render as a number input with increment/decrement buttons.

NUMBER_LIST = 'number[]'#

A list of numbers like [1, 2.4, 3.1415].

Will render as a dropdown.

NUMBER_RANGE = '[number, number, number]'#

A range of numbers like 1-10.

Can be made an Integer range or a Float range depending on the step.

Will render as a slider. Use allowedValues to define: [min, max, step].

  • The first number in the list is the minimum value.

  • The second number in the list is the maximum value.

  • The third number in the list is the step.

OBJECT = 'object'#

An object variable. This will be rendered as a code editor. The resulting value will be a python dictionary. Must be JSON serializable.

RADIO = 'radio'#

A radio variable. It will render as a list of radio buttons. Only one can be selected at a time.

Setup the allowedValues parameter to define the list of options such as [“A”, “B”, “C”].

RESIDUE = 'residue'#

A residue to be selected from a loaded structure. Either a standard or non-standard residue.

SMILES = 'smiles'#

A list of molecule SMILES strings.

Will use the loaded molecules in the JSME viewer (https://jsme-editor.github.io/)

SPHERE = 'sphere'#

A sphere to be rendered in Mol*.

Will render as an interactive sphere viewer. The user can select the center and the radius of the sphere. The type of the variable will be a dictionary with the following keys:

  • center: The center of the sphere as a list of floats [x, y, z].

  • radius: The radius of the sphere as a float.

STDRES = 'stdres'#

A standard residue to be selected from a loaded structure.

Will render as a dropdown with the list of standard residues. The type of the variable will be a dictionary with the following keys:

  • index: The index of the residue in the structure.

  • name: The name of the residue.

  • atoms: The list of atoms in the residue.

  • structure: The structure object variable where the atom is located.

This last variable contains the properties of the STRUCTURE variable.

STRING = 'string'#

A regular string like “Hello world”.

Will render as a text input.

STRING_LIST = 'string[]'#

A list of strings like [“Hello”, “World”].

Will render as a dropdown.

STRUCTURE = 'structure'#

A single molecular structure to be selected from Mol*.

Will render as a list of radio buttons with the list of loaded structures. The type of the variable will be a dict with the following data:

  • id: The ID of the structure.

  • name: The name of the structure.

  • type: The type of the structure (CIF, PDB…).

  • structure: The structure file contents (CIF, PDB… string)

TEXT_AREA = 'text_area'#

A large text like a paragraph, can contain multiple lines.

"Hello world \n Hello planet".

Will render as a text input.

static getTypes()#

Returns a list of all the available types.

Blocks#

class PluginBlock(name: str, description: str, action: Callable | None = None, variables: List[PluginVariable] = [], inputs: List[PluginVariable] = [], inputGroups: List[VariableGroup] = [], outputs: List[PluginVariable] = [], blockType: PluginBlockTypes = PluginBlockTypes.BASE, id: str | None = None, externalURL: str | None = None, category: str | None = None)#

Bases: object

The base block class for Horus blocks. Not to be used directly.

Initialize a PluginBlock.

TYPE: PluginBlockTypes#

The type of the block. Internal use only.

action#

The action that the block performs.

blockLogs: str = ''#

The logs of the block.

category: Union[None, str] = None#

The category of the block inside the plugin. None by default.

config: dict = {}#

The configuration of the plugin that hosts this block.

copy()#

Returns a deep copy of the block in order to not modify the original reference.

description#

A description of the block.

dirty: bool = False#

Whether the block is dirty or not. When running for the first time, the block is not dirty. When the flow is reset, the block is not dirty. The block will be dirty on subsequent runs without a reset.

error: bool = False#

Whether the block has an error or not.

externalURL#

The external URL of the block for documentation purposes.

extraData: Dict[str, Any] = {}#

Extra data that the block can store.

This data can be used to store any extra information that the block may need to store. For example, the folder of a remote job to be downloaded in the finalAction of a SlurmBlock.

flow: Flow#

The current flow where the block is placed and being executed.

This value is only defined withing the execution of action function of the block.

Some properties of the flow are: - name: The name of the flow. - path: The path to the flow. - savedID: The unique ID of the flow. - blocks: The list of blocks in the flow.

id: str#

The id of the block. It is composed by the plugin id and the id/name of the block. The addBlock() method of the Plugin class will automatically assign the plugi id part to the block id.

property inputs: dict#

The inputs assigned to the block.

Returns:

A dictionary with the inputs of the block with key

the input ID and value the input value.

name#

The name of the block.

property outputs: dict#

The outputs assigned to the block.

Returns:

A dictionary with the outputs of the block with key

the output ID and value the output value.

pluginDir: str#

The path in the local machine to the plugin installation. Useful for finding scripts and tools embedded with the plugin.

remote: PluginRemote#

The RemoteAPI for the block.

selectedInputGroup: str = 'default'#

The ID of the selected input group. This gets updated when the user selects a different input group in the frontend.

selectedRemote: str = 'Local'#

The name of the selected remote.

setOutput(id: str, value: Any)#

blockJson.get Sets the value of an output variable.

Parameters:

  • id – The id of the output variable.

  • value – The value to set.

time: float = 0#

The time that the block took to run.

property variables: dict#

The variables assigned to the block.

Returns:

A dictionary with the variables of the block with key

the variable ID and value the variable value.

class InputBlock(name, description, variable: PluginVariable, output: PluginVariable | None = None, action: Callable | None = None, id: str | None = None, externalURL: str | None = None, category: str | None = None)#

Bases: PluginBlock

The InputBlock class is a special type of block that is used to get input from the user. It works as a regular PluginBlock but only shows its PluginVariable. Its output will be automatically set to the value the variable has if it does not have a defined action.

When only the variable parameter is defined, the block will output directly the value of the variable.

If parsing of the variable is needed, the action parameter can be used to define a function that will parse the value of the variable and return the parsed value. In that case, use the output parameter to define the output variable of the block.

Parameters:

  • name – The name of the block.

  • description – The description of the block.

  • variable – The variable of the block.

  • output – The output of the block.

  • action – The action of the block. Will be run when storing the config.

  • id – The id of the block.

  • externalURL – The external URL of the block for documentation purposes.

  • category – The category of the block inside the plugin.

class SlurmBlock(name: str, description: str, initialAction: Callable, finalAction: Callable, variables: List[PluginVariable] = [], inputs: List[PluginVariable] = [], inputGroups: List[VariableGroup] = [], outputs: List[PluginVariable] = [], id: str | None = None, failOnSlurmError: bool = True, externalURL: str | None = None, category: str | None = None)#

Bases: PluginBlock

The SlurmBlock class is a special type of block that is used to run an action in a remote server. It works as a regular PluginBlock but it has two actions, one before the job is submitted and one after the job is completed.

Parameters:

  • name – The name of the block.

  • description – The description of the block.

  • initialAction – The action of the block before the job is submitted.

  • finalAction – The action of the block after the job is completed.

  • variables – The variables of the block.

  • inputs – The inputs of the block.

  • inputGroups – The input groups of the block.

  • outputs – The outputs of the block.

  • id – The id of the block.

  • failOnSlurmError – Whether to fail the block if the slurm job fails.

  • externalURL – The external URL of the block for documentation purposes.

Plugin#

class Plugin(id: str | None = None, noMetaLoad: bool = False)#

Base class for all plugins.

Initializes the plugin.

Parameters:

id – The id of the plugin.

actions: List[Callable] | None#

Functions that can be called from the GUI. WIP

addBlock(block: PluginBlock)#

Adds a PluginBlock to the plugin.

addConfig(config: PluginConfig)#

Adds a PluginConfig to the plugin.

addPage(page: PluginPage)#

Adds a PluginPage to the plugin.

property blocks#

Returns a list of all the blocks in the plugin.

property config: dict#

A dictionary with the configs of the block

default: bool = False#

Whether the plugin is a default plugin or not.

getBlock(id)#

Returns a block by its ID.

Parameters:

id – The ID of the block.

getBlocks()#

Returns a list of all the blocks in the plugin.

getPage(id)#

Returns a page by its ID.

Parameters:

id – The ID of the page.

getPages()#

Returns a list of all the pages in the plugin.

id: str#

The unique id of the plugin. Will be automatically assigned when loading the plugin from the plugin.meta file.

loadPluginMeta()#

Loads the information about the plugin from the plugin.meta file.

  • name: The name of the plugin

  • version: The version of the plugin

  • author: The author of the plugin

  • description: A description of the plugin

  • dependencies: A list of dependencies of the plugin

The path to the logo of the plugin.

property pages#

Returns a list of all the pages in the plugin.

pluginMeta: PluginMetaModel#

The metadata of the plugin.

views#

Views that can be loaded from the GUI. Should be the path to the HTML file.

RemoteAPI#

class PluginRemote(remote: RemotesAPI, block: PluginBlock)#

Remote interface for blocks

cd(path: str)#

Context manager to change directory on the remote.

Works with the command, submitJob and send/get data functions.

command(command: str, timeout: int | None = None, forceLocal: bool = False, mergeStdErr: bool = True)#

Executes a command on the remote. The output of the command will be returned.

Parameters:

  • command – The command to execute.

  • timeout – The timeout in seconds. None for no timeout.

  • forceLocal – If True, the command will be executed locally even if the block has a remote selected.

  • mergeStdErr – If True (default) will append the stdErr of the command to the output.

Returns:

The output of the command.

getData(source: str, destination: str) → str#

Gets a file from the remote. :param file: The path to the file to get.

Returns:

The final absolute path to the downloaded file.

property host: str#

Returns the host adress of the remote.

property isLocal: bool#

Returns whether the remote is local or not

property name: str#

Returns the name of the remote.

remoteCommand(command: str, timeout: int | None = None)#

Deprecated. Use command instead.

sendData(source: str, destination: str) → str#

Sends a file to the remote. :param file: The path to the file to send.

Returns:

The final absolute path to the uploaded file.

submitJob(script: T, changeDir: bool = True) → T#

Submit a slurm job to the queue system of the cluster (SLURM)

Parameters:

script – The absolute path to the script to submit or a list of path to submit more than one at once.

Param:

changeDir: automatically cd to the container folder of the script. Disable this if using the cd context manager or for specific cases.

Returns:

The job ID.

property userHome: str#

Returns the expanded user home directory.

property workDir: str#

Returns the Horus directory on the remote. If on local, returns the flow directory.

MolstarAPI#

class MolstarAPI(*args, **kwargs)#

API for interacting with Mol* visualizer inside Horus

addBox(center: list[float], sides: list[float] = [1, 1, 1], 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]

  • lineSize – The width of the lines. Defaults to 1.

  • color – The color of the box as an RGB hex string (i.e. #0000FF) Defaults to random color.

  • opacity – The opacity of the box (0.0 - 1.0). Defaults to 1.

addMolecule(filePath: str, label: str | 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(x: float, y: float, z: 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

loadMVJS(mvjs: Dict[str, Any], replaceExisting: bool = False) → None#

Loads a molviewspec session into Mol*

Parameters:

mvjs – The molviewspec session to load as a dictionary

(returned by the .get_state() method of molviewspec builder) :param replaceExisting: Whether to replace the existing session or not

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

property mvs#

The molviewspec library. Use it to build complex scenes

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

SmilesAPI#

class SmilesAPI(*args, **kwargs)#

API for interacting with the Smiles Manager inside Horus

addCSV(csv: str, group: str | None = None) → None#

Adds a CSV file to the smiles manager

Parameters:

csv – The CSV file path to add

addSmiles(smiles: str, group: str | None = None) → None#

Add a smiles string to the smiles manager

Parameters:

  • smiles – The smiles string to add

  • group – The group to add the smiles to

addSmilesWithData(smiles: list[dict]) → None#

Adds a list of full SMILES object to the smiles manager

Each object should be in the following keys:

  • smi: string -> SMILES as a string

  • label: string -> Label to display

  • extraInfo: string -> Extra info to display

  • group: string -> Group to add the smiles to

  • props: {key: value, …} -> Properties to add to the molecule (optional)

reset() → None#

Resets the visualizer

ExtensionsAPI#

class Extensions(*args, **kwargs)#
loadCSV(csv: str, title: str, store: bool = True) → None#

Loads the given CSV into the extension.

Parameters:

  • csv – The path to the CSV to load.

  • title – The title of the ‘Result’. This will be displayed on top of the block that produced the CSV.

  • store – Whether to store the CSV as results or to open it inmediately.

loadHTML(html: str, title: str, store: bool = True) → None#

Loads the given HTML into the extension.

Parameters:

  • html – The path to the HTML to load .

  • title – The title of the ‘Result’. This will be displayed on top of the block that produced the HTML.

  • store – Whether to store the HTML as results or to open it inmediately.

  • asString – Whether the passed HTML is a string or an html file.

loadImage(image: str, title: str, store: bool = True) → None#

Loads the given image into the extension.

The image will be stored inside the flow.

Parameters:

  • image – The path to the image to load. Supports png, jpg and gif.

  • title – The title of the ‘Result’. This will be displayed on top of the block that produced the image.

  • store – Whether to store the image as results or to open it inmediately.

loadPDF(pdf: str, title: str, store: bool = True) → None#

Loads the given PDF into the extension.

Parameters:

  • pdf – The path to the PDF to load.

  • title – The title of the ‘Result’. This will be displayed on top of the block that produced the PDF.

  • store – Whether to store the PDF as results or to open it inmediately.

loadPlot(plotCSV: str, title: str, store: bool = True) → None#

Loads the given CSV as a Plot into the extension.

Parameters:

  • csv – The path to the CSV to load as plot.

  • title – The title of the plot. This will be displayed on top of the block that produced the Plot.

  • store – Whether to store the Plot as results or to open it inmediately.

loadText(text: str, title: str, store: bool = True) → None#

Loads the given text into the extension.

Parameters:

  • text – The text to load.

  • title – The title of the ‘Result’. This will be displayed on top of the block that produced the text.

  • store – Whether to store the text as results or to open it inmediately.

open(pluginID: str, pageID: str, data: Dict[str, Any] | None = None, title: str = 'Extension') → None#

Opens the given extension (PluginPage) and passes the given data to it.

Parameters:

  • pluginID – The ID of the plugin that contains the desired PluginPage (Extension).

  • pageID – The ID of the PluginPage that represents the extension.

  • data – The data to pass to the extension.

storeExtensionResults(pluginID: str, pageID: str, data: Dict[str, Any] | None = None, title: str = 'Results') → None#

Stores the results of the extension in the flow to be opened at any time.

Parameters:

  • pluginID – The ID of the plugin that contains the desired PluginPage (Extension).

  • pageID – The ID of the PluginPage that represents the extension.

  • data – The results of the extension.

  • title – The title of the results. This will be displayed on top of the block that produced the results.

Utils#

exception ResetRemoteException#

Exception raised when the remote server is reset.

class SingletonMeta#

This is a thread-safe implementation of Singleton.

Intened for internal use only.

class TempFile(name: str, folder: str | None = None)#

Temporary file class used to store temporary files in user dirs

  • Name: The name of the file.

  • Folder: The folder where the file will be stored. If None, the file will bestored in the tmp folder.

delete()#

Delete the file.

deleteTmpFolder()#

Deletes the tmp folder.

read()#

Read the content of the file

Returns:

The content of the file as a string.

write(content: str)#

Write content to the file

  • content: The content to write to the file.

initPlugin()#

This function will create the basic folder structure for building a Horus plugin.