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