Code documentation

The plugin functionality is split in two files:

  1. yapycon.py

    • For the actual code of the plugin.

  2. yasara_kernel.py

    • For all YASARA functionality available within YaPyCon.

yapycon.py

Note

The description of the yapycon plugin code in the following parts of the documentation, might show up as a random collection of MainMenu, PullDownMenu, etc, statements.

It is not.

YASARA uses the docstring of a plugin to determine where in its menu hierarchy to position the option to run the plugin, whether the plugin needs to be launched over a particular selection and other parameters that are passed to it when YASARA launches it.

For more details about how this works and why the docstring of yapycon looks the way it does here, please see the following sections:

MainMenu: Window
PullDownMenu after Update frequency: Python Console

Request: YaPyCon

class yapycon.yapycon.RpcServerThread(*args, **kwargs)

Maintains the rpyc thread which allows the console process to interface with the context of the originating process.

run()

Launches the RPC ThreadedServer.

class yapycon.yapycon.YasaraContextRelayService(connection_info=None)

An rpyc service that establishes a “bridge” between the YaPyConsole plugin and subsequent processes.

Notes:

  • This object is basically a “proxy” between data in the context of the plugin process and the context of subsequent processes.

  • Although this object is entirely “visible” through the console, it is not meant to be used directly.

yapycon.yapycon.yapycon_launch_plugin(plugin_request)

Handles the initialisation and launching of the YaPyCon plugin.

Parameters

plugin_request (str) – The request string sent by YASARA when the plugin is launched.

yapycon.yapycon.yapycon_plugin_check_if_disabled()

Checks if YaPyCon can launch.

Notes:

  • This function checks if it was possible for YaPyCon to load certain pre-requisite modules.

  • If these modules were not found, this function will signal this to YASARA (by returning a 1) and subsequently, YaPyCon’s menu option (“Python Console”) will not be available in YASARA.

Returns

Either 0 or 1 to signal Success or Failure to launch respectively.

Return type

int

yasara_kernel.py

YASARA functionality available to YaPyCon.

Notes:

  • This module is largely based on the original yasara.py module by Elmar Krieger, that can be found in a typical YASARA installation.

  • yasara_kernel.py is almost identical to yasara.py.

  • The key differences are:

    1. yasara_kernel excludes certain YASARA functions that could bring YASARA and / or YaPyCon in an indeterminate state (for example: StopPlugin(), Exit()).

    2. yasara_kernel.py includes certain convenience functions that reformat the output of certain YASARA commands (such as: ListAtom(), ListBond()). Any additional functions provided by YaPyCon are prefixed with yapycon_ and are very easy to browse through.

    3. yasara_kernel.py includes typical docstrings in the Sphinx docstring format, for:

      • All of its own functions (i.e. the plugin code and yapycon_ prefixed functions from yasara_kernel.py)

      • All of the yasara.py functions that have been modified (e.g. SavePNG()).

      • Selected yasara.py functions to demonstrate the usefulness of this feature more generally.

    4. yasara_kernel.py skips all of the initialisation that yasara.py carries out typically when it is loaded. Instead, it re-uses the RPC proxied objects to initialise its own global variables such as: plugin, request, opsys, version, serialnumber, stage, owner, permissions, workdir, selection, com.

    5. yasara_kernel.py is more up to date with Python3 (to the extent that this is possible and practical).

author

Athanasios Anastasiou

date

Nov 2021

yapycon.yasara_kernel.ListAtom(selection1, format=None, compress=None)

Returns an array of atoms within a particular selection.

Notes:

  • By default, only the YASARA atom IDs are returned. To change the amount of information returned for each at, see the in-program help by running a Help Label from the YASARA console.

  • See also yapycon_reformat_bondinfo_returned() for a convenience function to handle the return value of List functions.

  • For more details on the parameters please do a Help ListAtom from within the YASARA console.

Parameters

  • selection1 (str) – A YASARA query expression.

  • format (str) – A string containing specific attribute names to return. Returned values will conform to this string as strictly as possible. For example, "ATOMNUM,    ATOMELEMENT" will result in a return value of 128,    O (notice the exact number of spaces). For more information about the attributes accepted in format please run a Help Label from the YASARA console. The attributes supported as of version 21.8.26 are: OBJNAME, OBJNUM, COMPOUND, MOLNAME, SEGNAME, RES, RESNAME, RESName, RESNAME1, RESNUM, RESNUMWIC, ATOMNAME, ATOMNAMEPDB, ATOMNAMEPDB3, ATOMNAMEIUPAC, ATOMNAMEXPLOR, ATOMNUM, ATOMELEMENT, ATOMElement, ATOMTYPE, CHARGE, CHIRALITYLD

  • compress (str) – Either “Yes” or “No”, whether to apply a type of run-length compression to the returned results. For more detailed information, please run a Help ListAtom from the YASARA console.

yapycon.yasara_kernel.LoadPDB(filename, center=None, correct=None, model=None, download=None, seqres=None)

Loads a PDB file into YASARA.

For much more detailed information, run Help LoadPDB in the YASARA console.

Parameters

  • filename (str) – Filename of the PDB file or molecule ID if downloading from internet (see download parameter)

  • center (str) – Either “Yes” or “No”, aligns the center of the loaded molecule to the local coordinate system.

  • correct (str) – Either “Yes” or “No”, whether to attempt to correct errors after loading the model

  • model (int) – An integer denoting how many models to load from the provided filename.

  • download (str) – Either “No”, “Yes”, “Latest”, “PDBRedo”, “Best” to determine whether and where to download from, for more information about this please see the detailed help in YASARA.

  • seqres (str) – Either “Yes” or “no”, determines whether to read the protein sequence from the PDB file.

yapycon.yasara_kernel.LoadPNG(filename, transcol, selection1)

Loads a PNG file WITHIN YASARA.

Notes:

  • For much more detailed information, run Help LoadPNG in the YASARA console.

  • See also SavePNG

Parameters

  • filename (str(path)) – The fileame of the image to load, relative to the current working directory of YASARA

  • transcol (str(colour name, RGBHex, ...)) – A colour specification that YASARA will turn to transparent, for more information please see Help LoadPNG.

  • selection1 (int) – An object selection number by which the image will be known to YASARA (please see help for more information.

yapycon.yasara_kernel.RayTrace(filename, x=None, y=None, zoom=None, atoms=None, labelshadow=None, secalpha=None, display=None, outline=None, background=None)

Creates a raytraced screenshot of the current YASARA scene via POVRay.

Notes:

  • More details about POVRay are available here

  • The side effect of this command is very similar to SavePNG(), only that the “screenshot” is produced via a different means.

  • Similarly to SavePNG(), the raytraced image is returned in YaPyCon as a numpy array.

Parameters

  • filename (str(path)) – The filename to save the screenshot to (relative to workdir).

  • x (int) – The desired width of the raytraced image

  • y (int) – The desired height of the raytraced image

  • zoom (float) – The “ball zoom” factor (Please see Help Raytrace from the YASARA Console)

  • atoms (str) – Either “Balls” or “Blobs”, what sort of POVRay primitive to use to represent the atoms.

  • labelshadow (str) – Either “Yes” or “No”, determines whether text elements cast shadows.

  • secalpha (float) – The secondary structure alpha blending factor as a percentage (%).

  • display – Either “On” or “Off”, determines whether to show the POVRay window during raytracing or not.

  • outline (float) – Radius of “comic outline” in Angstrom

  • background (str) – Either “On” or “Off”, determines whether to leave the background transparent or not.

yapycon.yasara_kernel.SavePNG(filename, menu=None, depthmap=None)

Saves a simple screenshot of the current state of YASARA.

Notes:

  • SavePNG Does not work if YASARA runs in text or console mode, for more information please run a Help SavePNG and read the in-program documentation.

  • If Matplotlib is installed on the activated environment, the yasara_kernel function returns the image as a numpy array.

Parameters

  • filename (str(path)) – Filename to save the screenshot at. By default, the current working directory is in variable workdir

  • menu (str) – Either “Yes” or “No”, whether to include the menu and status bars in the screenshot.

  • depthmap (str) – Either “Yes” or “No”, saves a grayscale image that represents the depth map of the current scene.

Returns

Numpy array if matplotlib available or the response from YASARA.

yapycon.yasara_kernel.ShowMessage(text)

Displays a simple message to the user within YASARA.

Parameters

text (str) –

yapycon.yasara_kernel.yapycon_access_image_returned(filename, current_retval=None)

Opens and returns an image as a numpy array

Notes:

  • This function is used throughout yasara_kernel wherever YASARA commands are returning images so that it is easier to plot them in a Jupyter control.

Parameters

  • filename (str(path)) – The graphics file that a particular command (e.g. SavePNG, RayTrace) produces

  • current_retval (list) – The result of runretval for the command that produces the output.This guarantess that the image will have been saved and simplifies the re-usability of the function.

Returns

A numpy array if Matplotlib is available and the file could be located or None otherwise

Return type

numpy | None

yapycon.yasara_kernel.yapycon_get_connection_info()

Returns the connection info for the existing kernel.

Notes:

  • This is useful information when trying to connect to an existing kernel.

yapycon.yasara_kernel.yapycon_reformat_atominfo_returned(atom_info, format, delim=',')

Reformats a list of atom information returned from certain YASARA’s List… functions, taking into account the requested format.

Notes:

  • This is a convenience function that re-packages the strings that are returned from YASARA to dictionaries with the attribute names as keys and the return value marshaled to the right data type too.

Parameters

  • atom_info (list) – A list of strings just as returned from a List command. For more information on attribute names run a “Help ListAtom” from within YASARA.

  • format (str) – A delimited string with field names defining the returned format. As of YASARA version 21.8.26, the marshalled attributes are RESNUMWIC, ATOMNUM, CHARGE. For more information on the complete list please run a “Help Label” from within YASARA.

  • delim (str) – The delimiter used to delimit attributes in format, the default is ,.

Returns

A list of dictionaries enabling fast lookups to the returned information.

Return type

list[dict[attr, value]]

Raises

TypeError if atom_info is not a list or if format is not a str, ValueError if format contains duplicate attribute names.

yapycon.yasara_kernel.yapycon_reformat_bondinfo_returned(bond_info, num_of_results)

Reformats a list of (covalent) bond information returned from YASARA taking into account the requested format.

Notes:

  • Similar functionality can be provided to “decode” (or “repackage”) the output of the rest of the List... YASARA functions.

Parameters

  • bond_info (list) – The raw output from ListBond()

  • num_of_results (int) – The number of results that was passed to ListBond(), which determines the structure of the returned results.

Returns

A list of dictionaries whose keys are determined by num_of_results. The keys are: atomnum_sel1, atomnum_sel2, bond_order, bond_length. This means that if num_of_results=2, the returned dictionaries will have a length of two and contain the first two keys (i.e. atomnum_sel1, atomnum_sel2). Similarly for 1<=num_of_results<=4.

Return type

list[dict[str, num]]

Raises

TypeError if bond_info is not a list, if num_of_results is not int and ValueError if num_of_results is out of the interval [1,4].