UP arb.hlp UP agde.hlp UP glossary.hlp UP save.hlp TITLE Customizing GDE menus DESCRIPTION ARB uses the GDE menus to plugin external tools This helpfile contains parts of the original GDE helpfile and has been modified to fit to the way GDE menus are used inside ARB. SECTION Description of GDE menus as used in ARB The GDE uses a menu description language to define what external programs it can call, and what parameters and data to pass to each function. This language allows users to customize their own environment to suite individual needs. The following is how the GDE handles external programs when selected from a menu: Each step in this process is described in the file $ARBHOME/lib/gde/arb.menu The directory $ARBHOME/lib/gde also contains other .menu-files for separate external tool integration (e.g. raxml8, sativa). You may integrate any external tool into the ARB interface by adding files with suffix '.menu' either into the global directory '$ARBHOME/lib/gde/' (menus defined there will be available to all users) or into '~/.arb_prop/gde/' (menus defined there will not be available to other users). SECTION GDE menus language The language used in this file describes three phases to an external function call. The first phase describes the menu item as it will appear, and the Unix command line that is actually run when it is selected. The second phase describes how to prompt for the parameters needed by the function. The third phase describes what data needs to be passed as input to the external function, and what data (if any) needs to be read back from its output. The form of the language is a simple keyword/value list delimited by the colon (:) character. The language retains old values until new ones are set. For example, setting the menu name is done once for all items in that menu, and is only reset when the next menu is reached. The keywords for phase one are: menu:menu name Name of current menu menumeta:meta_key Meta key equivalence (quick keys) menumask:expert Whole menu will be inaccessible in ARBs novice mode item:item name Name of current menu item Please do not change 'item name' for cosmetic purposes - doing so will invalidate user-stored-configs! itemmeta:meta_key Meta key equivalence (quick keys) itemhelp:help_file Help file (either full path, or in $ARBHOME/lib/help) itemmethod: Unix command itemmask:expert Whole menu will be inaccessible in ARBs novice mode seqtype:TYPE Known TYPEs: 'A' -> select amino acid sequences 'N' -> select nucleotide sequences '*' -> select ANY sequences '-' (or whole entry missing) -> do not select sequences The itemmethod command is a bit more involved, it is the Unix command that will actually run the external program intended. It is one line long, and can be up to 4096 characters in length. It can have embedded variable names (starting with a '$') that will be replaced with appropriate values later on. It can consist of multiple Unix commands separated by semi-colons (;) and may contain shell scripts and background processes as well as simple command names. If one of the commands needs access to the running ARB, the whole command should be run asynchronously, i.e. be run using '( command ) &'. Otherwise the command may lock. The keywords for phase two are: arg:argument_variable_name Name of this variable. It will appear in the itemmethod: line with a dollar sign ($) in front of it. Please do not change 'argument_variable_name' for cosmetic purposes - doing so will invalidate user-stored-configs! argtype:TYPE The type of graphic object representing this argument. Known types are choice_list choice_menu chooser filename sai slider text tree weights arglabel:descriptive label A short description of what this argument represents argmin:minimum_value (integer) Used for sliders. argmax:maximum_value (integer) Used for sliders. argvalue:default_value It is the numeric value associated with sliders or the default choice in choosers, choice_menus, and choice_lists (the first choice is 0, the second is 1 etc.) argtext:default value text: Default value filename: default extension argchoice:displayed value:passed value Used for choosers and choice_menus. The first value is displayed on screen, and the second value is passed to the itemmethod line. argmask:expert Whole arg will be inaccessible in ARBs novice mode The keywords for phase three are as follows: in:input_file GDE will replace this name with a randomly generated temporary file name. It will then write the selected data out to this file. Convention: always use TmpInputFile as placeholder informat:file_format Write data to this file for input to this function. Currently support values are Genbank, and flat. intyped:DETAILS Whether to save sequence type information. Known DETAILS: basic default; plain sequences exported detailed -> prefix sequence name by IDCHAR Known IDCHARs: '#' RNA / DNA '%' PROTEIN '@' MASK (obsolete) '"' TEXT or unknown insave: Do not remove this file after running the external function. This is useful for functions put in the background. out:output_file GDE will replace this name with a randomly generated temporary file name. It is up to the external function to fill this file with any results that might be read back into the GDE. Convention: always use TmpOutputFile as placeholder outformat:file_format The data in the output file will be in this format. Currently support values are colormask, Genbank, and flat. outaligned:yes GDE assumes external tool is an aligner or similar which only changes the alignment of bases. Sequence data will be re-imported w/o asking questions. Several minor changes in sequence data (by external tool) will be accepted and silently reverted. This includes - changing 'U' into 'T' (or vv) - case changes - gap changes ('.' to '-' or vv) outsave: Do not remove this file after reading. This is useful for background tasks. Here is a sample dialog box, and it's entry in the .GDEmenus file: Using the default parameters given in the dialog box, the executed Unix command line would be: (tr '[a-z]' '[A-Z]' < .gde_001 >.gde_001.tmp ; mv .gde_001.tmp CAPS ; gde CAPS -Wx medium ; rm .gde_001 ) & where .gde_001 is the name of the temporary file generated by the GDE which contains the selected sequences in flat file format. Since the GDE runs this command in the background ('&' at the end) it is necessary to specify the insave: line, and to remove all temporary files manually. There is no output file specific because the data is not loaded back into the current GDE window, but rather a new GDE window is opened on the file. A simpler command that reloads the data after conversion might be: item: All caps itemmethod: tr '[a-z]' '[A-Z]' OUTPUT in: INPUT informat: flat out: OUTPUT outformat: flat In this example, no arguments are specified, and so no dialog box will appear. The command is not run in the background, so the GDE can clean up after itself automatically. The converted sequence is automatically loaded back into the current GDE window. In general, the easiest type of program to integrate into the GDE is a program completely driven from a Unix command line. Interactive programs can be tied in (MFOLD for example), however shell scripts must be used to drive the parameter entry for these programs. Programs of the form: program_name -a1 argument1 -a2 argument2 -f inputfile -er errorfile > outputfile can be specified in the .GDEmenus file directly. As this is the general form of most one Unix commands, these tend to be simpler to implement under the GDE. As functions grow in complexity, they may begin to need a user interface of their own. In these cases, the command line calling arguments are still necessary in order to allow the GDE to hand them the appropriate data, and possible retrieve results after some external manipulation. SECTION Copyright Notice The Genetic Data Environment (GDE) software and documentation are not in the public domain. Portions of this code are owned and copyrighted by the The Board of Trustees of the University of Illinois and by Steven Smith. External functions used by GDE are the proporty of, their respective authors. This release of the GDE program and documentation may not be sold, or incorporated into a commercial product, in whole or in part without the expressed written consent of the University of Illinois and of its author, Steven Smith. All interested parties may redistribute the GDE as long as all copies are accompanied by this documentation, and all copyright notices remain intact. Parties interested in redistribution must do so on a non-profit basis, charging only for cost of media. Modifications to the GDE core editor should be forwarded to the author Steven Smith. External programs used by the GDE are copyright by, and are the property of their respective authors unless otherwise stated. While all attempts have been made to insure the integrity of these programs: SECTION Disclaimer THE UNIVERSITY OF ILLINOIS, HARVARD UNIVERSITY AND THE AUTHOR, STEVEN SMITH GIVE NO WARRANTIES, EXPRESSED OR IMPLIED FOR THE SOFTWARE AND DOCUMENTATION PROVIDED, INCLUDING, BUT NOT LIMITED TO WARRANTY OF MERCHANTABILITY AND WARRANTY OF FITNESS FOR A PARTICULAR PURPOSE. User understands the software is a research tool for which no warranties as to capabilities or accuracy are made, and user accepts the software "as is." User assumes the entire risk as to the results and performance of the software and documentation. The above parties cannot be held liable for any direct, indirect, consequential or incidental damages with respect to any claim by user or any third party on account of, or arising from the use of software and associated materials. This disclaimer covers both the GDE core editor and all external programs used by the GDE.