°  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()