More docs on the ARB website.
See also index of helppages.
Last update on 04. Mar 2022 .
Main topics:
Related topics:

    Customizing GDE menus


    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.


    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


    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).


    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
            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:

    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!
                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.
    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.
    Whole arg will be inaccessible in ARBs novice mode

    The keywords for phase three are as follows:

    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
    Write data to this file for input to this function. Currently support values are Genbank, and flat.
    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
    Do not remove this file after running the external function. This is useful for functions put in the background.
    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
    The data in the output file will be in this format. Currently support values are colormask, Genbank, and flat.
    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)

    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]' <INPUT > 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.


    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:



    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.