° 

Plugins

-

Extend YASARA with your own functions

°	Plugins can be written in Yanaconda or Python

°	Python can be downloaded from www.python.org

°	Plugins must stick to format conventions

°  The header identifies a plugin The first line of a YASARA Python plugin must always read '# YASARA PLUGIN'. Adapt the remaining fields to describe your plugin. This information will be used if you decide to add it to the YASARA plugin repository at www.yasara.org/plugins in return for YASARA thank-you credits. Go to www.yasara.org/contribute to submit your plugin. # YASARA PLUGIN # TOPIC: Database interfaces # TITLE: Retrieve a PDB file by FTP # AUTHOR: Elmar Krieger # LICENSE: GPL (www.gnu.org) # DESCRIPTION: This plugin asks for a PDB ID and retrieves the file by FTP # °  The menu structure is enclosed in a triple-quote comment After the header, the plugin specifies where to add which entries to YASARA's user interface to make selections and run the plugin. These definitions will be read when YASARA registers the plugin during startup and must be enclosed in triple quotes ("""), so that Python ignores them. If you make changes here, you must restart YASARA. The indentation has to be a multiple of two spaces, Tabs are not allowed. Here is an example: """ MainMenu: File PullDownMenu after Load: _G_et by FTP TextInputMenu1: Retrieve a PDB file by FTP Text: Please input the four letter PDB ID code Text: _P_DB ID Request: GetByFTP """ The example above tells YASARA to: Enter the main menu, search for entry 'File' (add it if not found). Enter a pull down menu, search for entry 'Get by FTP' right after entry 'Load' (add it if not found). Add a text input menu with 1 input field and the header 'Retrieve a PDB file by FTP'. Within the text input menu, print the text 'Please input the four letter PDB ID code'. On top of the first (and only) text input box, print the text 'PDB ID' with the 'P' underlined. Run the plugin with the request 'GetByFTP' The tripple quote comment may contain the following keywords to identify certain menu types: °  MainMenu - Add an option to the top menu line The indentation level for this keyword must be 0. You can use 'after' and 'before' to specify the location of the new option. Underscores surround underlined characters. Examples: MainMenu: File MainMenu after Effects: A_n_imations MainMenu before Analyze: _T_ools °  AtomContextMenu - Add an option to the atom context menu The atom context menu appears when you click on a marked atom with the right mouse button, the indentation level for this keyword must be 0. You can use 'after' and 'before' as known from MainMenu. Example: AtomContextMenu: _Q_uery mutation effects °  ResidueContextMenu - Add an option to the residue context menu The residue context menu appears when you click on a residue in the sequence selector with the right mouse button, the indentation level for this keyword must be 0. You can use 'after' and 'before' as known from MainMenu. Example: ResidueContextMenu before Label: _Q_uery mutation effects °  PullDownMenu - Add an option to a pull-down menu This keyword must only be used after MainMenu with an indentation level of 1. Example: MainMenu: File PullDownMenu after Load: _G_et by FTP °  PopUpMenu - Add an option to a pop-up menu Pop-up menus are little windows popping up on the side of pull-down menus or context menus. This keyword must therefore only be used after PullDownMenu, AtomContextMenu or ResidueContextMenu, with an indentation level of 1 or 2. Example: MainMenu: View PullDownMenu: Color PopUpMenu: by properties °  ObjectSelectionMenu - Add a menu allowing to select objects This keyword adds a standard object selection menu, the selections are passed to the Python plugin via object descriptors. The specified text appears as the window header. Yanaconda plugins can currently not access these selections. The jth object descriptor in the ith selection window can be accessed as yasara.selection[i].object[j] (see below). Example: MainMenu: Analyze PullDownMenu: _M_CSIS mutations ObjectSelectionMenu: Select objects to map mutations stored in the MCSIS Request: MapMutations °  MoleculeSelectionMenu - Add a menu allowing to select molecules This keyword adds a standard molecule selection menu, the selections are passed to the plugin via molecule descriptors. See ObjectSelectionMenu above for an example. The jth molecule descriptor in the ith selection window can be accessed as yasara.selection[i].molecule[j] (see below). Example: MainMenu: Analyze PullDownMenu: _C_ompare amino acid sequence of two molecules MoleculeSelectionMenu: Select first molecule to compare sequence MoleculeSelectionMenu: Select second molecule to compare sequence Request: CompareSequence °  ResidueSelectionMenu - Add a menu allowing to select residues Not surprisingly, this keyword adds a residue selection menu, the selections are passed to the plugin via residue descriptors . See ObjectSelectionMenu above for an example. The jth residue descriptor in the ith selection window can be accessed as yasara.selection[i].residue[j] (see below). Example: MainMenu: Analyze PullDownMenu: _P_roscan ResidueSelectionMenu: Select residues for ProScan Request: Proscan °  AtomSelectionMenu - Add a menu allowing to select atoms The last keyword of this type adds an atom selection menu, the selections are passed to the plugin via atom descriptors. See ObjectSelectionMenu above for an example. The jth atom descriptor in the ith selection window can be accessed as yasara.selection[i].atom[j] (see below). Example: MainMenu: View PullDownMenu: Color PopUpMenu: by force AtomSelectionMenu: Select atoms to color by force Request: ColorByForce °  TextInputMenu[1-4] - Add a menu allowing to input 1 to 4 text strings This keyword adds a window with one to four text input boxes. In addition to the window header, you must specify a general explanation for the user and then one header for each text input box. The content of the jth text input box in the ith selection window can be accessed by the Python plugin as yasara.selection[i].text[j] (see below). Example for a window with two text input boxes: MainMenu: Options PullDownMenu: _R_eport error TextInputMenu2: Send an error report by e-mail Text: Please give a brief description of the problem: Text: _D_escription part 1 (header for the first input box) Text: _D_escription part 2 (header for the second input box) °  NumberInputMenu[1-6] - Add a menu allowing to input 1 to 6 numbers This keyword adds a window with one to six number input boxes. In addition to the window header, you must specify a general explanation text and then one descriptor for each number input box. A number descriptor contains four elements, separated by commas: the title of the number box, the default value, the minimum allowed value and the maximum allowed value. The content of the jth number input box in the ith selection window can be accessed by the Python plugin as yasara.selection[i].number[j] (see below). Example for a window with one number input box: MainMenu: Edit PullDownMenu after Build: Sample PopUpMenu: _O_bject ObjectSelectionMenu: Select protein to sample conformational space with CONCOORD NumberInputMenu1: Select ensemble size Text: Number of structures in the CONCOORD ensemble: Number: _S_tructures,10,1,98 Request: SampleObj °  SwitchBoxMenu[1-5] - Add a menu allowing to switch between 1 to 5 options This keyword adds a window with one to five switch boxes, where exactly one box can be selected. This allows to choose between up to five exclusive options, you must specify a general explanation for the user and then one additional text for every switch box. The number of the hooked box in the ith selection menu can be accessed by the Python plugin as yasara.selection[i].switchbox (see below). Example for a menu with two switch boxes: MainMenu: Options PullDownMenu: _R_eport error SwitchBoxMenu2: Concretize the error Text: Did the problem occur right now? Text: _Y_es, I did not exit YASARA since then. Text: _N_o, just before, I had to restart YASARA to get here. °  CheckBoxMenu[1-5] - Add a menu allowing to toggle 1 to 5 options This keyword adds a window with one to five check boxes, that can be activated individually. This allows to toggle up to five independent options, you must specify a general explanation for the user and then one additional text for every check box. The state of the jth check box in the ith selection menu can be accessed by the Python plugin as yasara.selection[i].checkbox[j] (see below). Example for a menu with two check boxes: MainMenu: NMR PullDownMenu: _L_ist restraints CheckBoxMenu2: List distance and dihedral angle restraints Text: Select the type of restraints to list Text: Distance restraints Text: Dihedral restraints (Checked) By default, all boxes are unchecked. To check a box, add the text '(Checked)' at the end as in the example above. °  ListMenu - Add a menu allowing to select from a list This keyword adds a window with a list of options. Set the 'MultipleSelections' flag to 'Yes' if the user is allowed to select more than one list entry and to 'No' otherwise. The first text is displayed above the list, the other texts are the actual list entries. The jth selected list entry in the ith selection menu can be accessed by the Python plugin as yasara.selection[i].listentry[j] (see below). Example: MainMenu: Analyze PullDownMenu: _P_DBFinder2 properties ResidueSelectionMenu: Select residues to color by PDBFinder2 properties ListMenu: Select PDBFinder2 properties MultipleSelections: Yes Text: Select more than one list entry to color by the average value Text: Nalign - Number of HSSP alignments Text: Nindel - Number of insertions and deletions Text: Entropy - HSSP sequence entropy Request: ColorResidues °  FileSelectionMenu - Add a menu allowing to select files This keyword adds a window with a file browser. Set the 'MultipleSelections' flag to 'Yes' if the user is allowed to select more than one list entry and to 'No' otherwise. The Filename keyword specifies a wildcard with the initial path. Use forward slashes also under Windows. The jth selected filename in the ith selection menu can be accessed by the Python plugin as yasara.selection[i].filename[j] (see below). Example: MainMenu: File PullDownMenu: Load PopUpMenu after PDB file: _N_MR ensemble FileSelectionMenu: Select a PDB file containing an NMR ensemble MultipleSelections: No Filename: pdb/*.pdb Request: LoadEnsemble °  The layout for the remaining plugin differs between Python and Yanaconda When using Yanaconda, the rest of the plugin is a straightforward macro. The variable 'Request' contains the specified request, e.g. 'GetByFTP' and can be used to execute different parts of the macro. Selections can currently not be accessed. When using Python, the first command must be import yasara Immediately afterwards, you can access the data passed to the plugin as well as call YASARA functions. The predefined variables are listed below, the most important one is yasara.request, a string indentifying the user's request. In the above example, there is only one possible request: 'GetByFTP'. When YASARA starts up and registers the plugins, it also sends a 'CheckIfDisabled' request, giving the plugin the possibility to exclude itself from registration. The remaining plugin scaffold therefore looks like that: if (yasara.request=="CheckIfDisabled"): # ASSIGN A 1 TO yasara.plugin.exitcode IF THIS PLUGIN CANNOT WORK AND SHOULD # BE DISABLED (DATA MISSING, WRONG OPERATING SYSTEM ETC.) if (....) yasara.plugin.exitcode=1 elif (yasara.request=="GetByFTP"): # DO THE WORK # END THE PLUGIN, MUST BE THE LAST COMMAND yasara.plugin.end()

°	Plugins can access most YASARA functions

Font Arial,Height=2,Spacing=1.5,Color=Yellow,Depth=5,DepthCol=Red

yasara.Font("Arial",height=2,spacing=1.5,color="Yellow",depth=5,depthcol="Red")

# Load a PDB file and color it red, THIS DOES NOT WORK, JUST FOR FUTURE REFERENCE
obj=yasara.LoadYOb("1crn")
yasara.ColorObj("%d,Red"%obj)

# Load a PDB file and color it red
yasara.run("obj = LoadPDB 1crn")
yasara.ColorObj("(obj),Red")

# Get a list of all residue numbers
yasara.run("reslist() = ListRes all")
# Print it in the YASARA console
yasara.run("for i=1 to count reslist")
yasara.run("  print 'Residue number (i) is (reslist(i))'")
yasara.run("pass")

°	Python plugins can access a number of predefined variables

yasara.request	The request string sent by YASARA to the plugin
yasara.opsys	The current operating system, "Linux", "MacOS" or "Windows"
yasara.version	The YASARA version string X.Y.Z
yasara.serialnumber	YASARA's serial number
yasara.stage	The YASARA stage View, Model, Dynamics or Structure
yasara.plugin.name	The name of the plugin (e.g. ftppdb.py)
yasara.plugin.config	A Python dictionary with the options from the plugin config file *.cnf
yasara.plugin.exitcode	The exit code returned to YASARA when the plugin ends
yasara.owner.firstname	Your first name
yasara.owner.email	Your e-mail address
yasara.selection	A list of selections with one entry for every selection menu you defined
yasara.selection[i].objects	The number of objects selected in the ith selection menu
yasara.selection[i].object[j]	The obj_descriptor (see below) for the jth selected object in the ith selection menu
yasara.selection[i].molecules	The number of molecules selected in the ith selection menu
yasara.selection[i].molecule[j]	The mol_descriptor (see below) for the jth selected molecule in the ith selection menu
yasara.selection[i].residues	The number of residues selected in the ith selection menu
yasara.selection[i].residue[j]	The res_descriptor (see below) for the jth selected residue in the ith selection menu
yasara.selection[i].atoms	The number of atoms selected in the ith selection menu
yasara.selection[i].atom[j]	The atom_descriptor (see below) for the jth selected atom in the ith selection menu
yasara.selection[i].texts	The number of text input boxes in the ith selection menu
yasara.selection[i].text[j]	The text typed into the jth text input box in the ith selection menu
yasara.selection[i].numbers	The number of number input boxes in the ith selection menu
yasara.selection[i].number[j]	The number typed into the jth number input box in the ith selection menu
yasara.selection[i].checkboxes	The number of checkboxes in the ith selection menu
yasara.selection[i].checkbox[j]	The state of the jth checkbox in the ith selection menu (1=hooked, 0=not hooked)
yasara.selection[i].switchbox	The number of the hooked switchbox in the ith selection menu, None if there was no switchbox
yasara.selection[i].listentries	The number of selected list entries in the ith selection menu
yasara.selection[i].listentry[j]	The jth selected list entry in the ith selection menu
yasara.selection[i].filenames	The number of selected filenames in the ith selection menu
yasara.selection[i].filename[j]	The jth selected filename in the ith selection menu

°  Object descriptors identify selected objects Object descriptors are instances of the class obj_descriptor. Typically, you loop over all object descriptors in the ith selection menu: for j in range(yasara.selection[i].objects): object=yasara.selection[i].object[j] And then access various object properties: object.name The name of the object object.number.inyas The unique number/ID of the object in YASARA (a string, starting with 1) object.number.inall The sequential number of the object in the soup (a string, starting with 1) You could then color the object red: yasara.ColorObj(object.number.inyas+",Red") °  Molecule descriptors identify selected molecules Molecule descriptors are instances of the class mol_descriptor. Typically, you loop over all molecule descriptors in the ith selection menu: for j in range(yasara.selection[i].molecules): molecule=yasara.selection[i].molecule[j] And then access various molecule properties: molecule.name The name of the molecule (that's the chain name in the PDB file) molecule.number.inyas The unique number/ID of the molecule in YASARA (a string) molecule.number.inall The sequential number of the molecule in the soup (a string, starting with 1) molecule.number.inobj The sequential number of the molecule in the object (a string, starting with 1) molecule.object The object descriptor for the object the molecule belongs to You could then display the molecule as sticks: yasara.StickMol(molecule.number.inyas) Or delete the entire object containing this molecule: yasara.DelObj(molecule.object.number.inyas) °  Residue descriptors identify selected residues Residue descriptors are instances of the class res_descriptor. Typically, you loop over all residue descriptors in the ith selection menu: for j in range(yasara.selection[i].residues): residue=yasara.selection[i].residue[j] And then access various residue properties: residue.name3 The name of the residue in three letter code. residue.name1 The name of the residue in one letter code. residue.number.inyas The unique number/ID of the residue in YASARA (a string). residue.number.inall The sequential number of the residue in the soup (a string, starting with 1). residue.number.inobj The sequential number of the residue in the object (a string, starting with 1). residue.number.inmol The sequential number of the residue in the molecule (a string, starting with 1). residue.number.inpdb The number of the residue in the PDB file (a string, last character may be the insertion code). residue.object The object descriptor for the object the residue belongs to. residue.molecule The molecule descriptor for the molecule the residue belongs to. You could then color the residue yellow: yasara.ColorRes(residue.number.inyas+",Yellow") Or display a ribbon for the entire molecule containing this residue: yasara.ShowSecMol(residue.molecule.number.inyas,"Ribbon") If you wonder why a '+' is used to combine the arguments in the first case, while a comma ',' is used in the second case, look here . °  Atom descriptors identify selected atoms Atom descriptors are instances of the class atom_descriptor. Typically, you loop over all atom descriptors in the ith selection menu: for j in range(yasara.selection[i].atoms): atom=yasara.selection[i].atom[j] And then access various atom properties: atom.name The name of the atom atom.namespaced The name of the atom including spaces (always four characters) atom.altloc The alternate location indicator of the atom atom.position The position of the atom, a list with three cartesian coordinates atom.occupancy The occupancy field of the atom in the original PDB file atom.bfactor The B-factor of the atom atom.number.inyas The unique number/ID of the atom in YASARA (a string). atom.number.inall The sequential number of the atom in the soup (a string, starting with 1, the same as .inyas). atom.number.inobj The sequential number of the atom in the object (a string, starting with 1, usually the same number as in the PDB file). atom.number.inmol The sequential number of the atom in the molecule (a string, starting with 1). atom.number.inres The sequential number of the atom in the residue (a string, starting with 1). atom.object The object descriptor for the object the atom belongs to. atom.molecule The molecule descriptor for the molecule the atom belongs to. atom.residue The residue descriptor for the residue the atom belongs to. You could then color the atom green: yasara.ColorAtom(atom.number.inyas+",Green") Or delete the entire residue the atom belongs to: yasara.DelRes(atom.residue.number.inyas)

°	Python plugins run in a separate thread

yasara.Finish()

# Log the output of the next command
yasara.LogAs("MyLog")
# List all lysine residues
yasara.ListRes("Lys")
# Finish writing the log file
yasara.Finish()
# Read the log file in Python
log=open("MyLog").readlines()

# DOWNLOAD A PDB FILE FROM THE WEB
pdb=urllib.urlopen(url).readlines()
# SAVE IT TEMPORARILY
open(pdbfilename,"w").writelines(pdb)
# READ IT IN YASARA
yasara.LoadPDB(pdbfilename)
# FINISH READING
yasara.Finish()
# DELETE THE TEMPORARY FILE
os.path.remove(pdbfilename)

# READ IT IN YASARA
yasara.LoadPDB(pdbfilename)
# AND DELETE
yasara.DelFile(pdbfilename)

°	Plugins can be speeded up by switching off the console

yasara.Console("Off")

°	Plugins can be run from the command line and in console mode

# Save a PLugin Input (PLI) File containing a selection of Calpha atoms
# and the request 'MyRequest'
SavePLIAtom CA,MyRequest
# Run the plugin
RunPlugin MyPlugin.py

yasara PathToMyPlugin/MyPlugin.py MyRequest

yasara -con PathToMyPlugin/MyPlugin.py MyRequest

yasara.Exit()

°	Debugging is done by adding temporary print commands

c:\MyPythonInstallationPath\python.exe MyPlugin.py

print "MyMessage"

yasara.write(WhatEver)

class CallWrapper:
  def __init__(self, func, subst, widget):
     self.func = func
     self.subst = subst
     self.widget = widget
  def __call__(self, *args):
     try:
         if self.subst:
             args = self.subst(*args)
         return self.func(*args)
     except SystemExit, msg:
         raise SystemExit, msg
     except:
         self.widget._report_exception()
         raise SystemExit  <<<< Newly added!