A point of emphasis: bioLegato is a program that runs other programs. Put another way, just about any program on the system, any program at all, can be launched from bioLegato. You can launch a script or a binary. The script could launch other scripts or binaries. If your output is in the form of a table, you could launch a spreadsheet. If the output is sequence, you can launch another bioLegato window! You really have to use bioLegato for awhile to appreciate how powerful this capability is.

There can be an arbitrary number of bioLegato instances. The following table summarizes the relevant files and directories for each instance, as of this writing:

bioLegato instance	script	menu directories
birch - launcher for BIRCH programs	$birch/script/birch	$birch/dat/birch $birch/local/dat/birch
bldna - DNA sequence analysis	$birch/script/bldna	$birch/dat/bldna $birch/local/dat/bldna
blprotein - protein sequence analysis	$birch/script/blprotein	$birch/dat/blprotein $birch/local/dat/blprotein
blmarker - molecular markers	$birch/script/blmarker	$birch/dat/blmarker $birch/local/dat/blmarker
bltree - phylogenetic trees	$birch/script/bltree	$birch/dat/bltree $birch/local/dat/bltree

We will use bl_instance to represent any instance of bioLegato. Each instance (eg. bldna, blprotein, blmarker, bltree and birch) has its own directory in $birch/dat and in $birch/local/dat. For example, when bldna starts, it reads .item files from the subirectories found in $birch/local/dat/bldna, and creates menus based on menu items in those files.  The menu items merged from both the BIRCH core and local biolegato menu items. The following steps describe how to get a program that has been locally-installed to be merged into a biolegato instance.

Creating a menu item is a cyclic process (shown for bldna):

1.4.1 Creating a menu item

Before you start - You really need to have a good idea of how to run your program at the command line before you try to make a bioLegato menu item to run it. Read the manual pages or other documentation. Try it out. It will save you a lot of time and frustration.

A menu item contains a command to be executed to run a program, and parameters that are substituted into that command.

Example:

#--------------- PROT2NUC - Reverse Translation ( 4/10/06) -----------------
item:PROT2NUC - reverse translation
itemmethod: sed "s/[#%]/>/" <in1 | prot2nuc -l$LINLEN -g$GROUP > in1.out; ($GDE_TEXTEDIT in1.out; rm in1*)&
itemhelp: doc/xylem/prot2nuc.txt
itemopen:gde_help_viewer.csh

arg:LINLEN
arglabel:CODONS PER LINE
argtype:slider
argmin:5
argmax:100
argvalue:25

arg:GROUP
arglabel:NUMBERING INTERVAL (amino acids/codons)
argtype:slider
argmin:5
argmax:100
argvalue:5

in:in1
informat:flat
insave:

The itemmethod is the command that is executed to run the program. In this case, the sed command is used to translate the GDE flat file format into FASTA format. The output from the sed command is piped directly to the prot2nuc program, using parameters LINLEN and GROUP substituted into the command line. Output is redirected to the file in1.out, which is launched using the text editor specified in the $GDE_TEXTEDIT environment variable.

For a more complete description of how to write GDE menu items, you really have to read Appendix B - Adding Functions in the GDE Manual.

Note on bioLegato HELP The example above shows the syntax for specifying a help file to be opened in when the HELP button is pressed in a GDE item menu. The general formula is: itemhelp:filename itemopen:program where filename is the file to open (path is relative to the GDE_HELP_DIR directory) and program is the program to open the file. filename can also be a URL. program is usually gde_help_viewer.csh, which chooses the viewer based on the file extension. There is one exception. Where a URL points to a named anchor in an HTML document (ie. a URL containing a '#' character) use itemopen:browser.csh gde_help_viewer.csh will not properly handle these types of URLs, so browser.csh can be called to force the file to be read in the BIRCH default browser. All help files must be accessed through the $GDE_HELP_DIR. If you need to specify a path to files that are not part of the main BIRCH distribution, you can use the 'root' link, which resides in all GDE help directories. This points to the root of the directory tree, '/'. So, for example, to get your biolegato item to display the help file found in: /export/data/programs/emboss/share/EMBOSS/doc/programs/html/prettyplot.html Add the following lines to the .item file: itemhelp:root/export/data/programs/emboss/share/EMBOSS/doc/programs/html/prettyplot.html itemopen:gde_help_viewer.csh To point to files in your $BIRCH/local directory, the help directories also have a symbolic link called 'local' eg. itemhelp:local/doc/filename

Some of the subtleties for writing good GDE menu items are further discussed in GDEmenus Hints and Tips.

There are lots and lots of example of menu items in $BIRCH/dat/bl_instance/menus. As well, when you first install BIRCH, the directory

$BIRCH/local/dat/bl_instance/menus

will have some  menu item files that you could edit to fit your system. For example, there are a set of FASTA and BLAST menu item files that you can edit to use your local copies of sequence databases. These will override the generic  FASTA and BLAST menus that are part of the BIRCH core.

If  you update your BIRCH system to a new release you may wish to check the

$BIRCH/local-generic/dat/bl_instance/menus

directory for new menu item files that might be modified to work on your site.

Note: None of the menu item files will appear in themenus until you add their names to the menulist file, as described below.

1.4.2 Adding your menu item to the menulist file

Your menu item file must have a file name of the form

name.item

where name is the name of the menu item. It should be saved in

$BIRCH/local/dat/bl_instance/menus/directory

where directory is the name of the menu where you would like your item to appear. For example, if I wanted to add a menuitem named paracelBLASTN.item to the Database menu of bldna, it would be saved as

$BIRCH/local/dat/bldna/menus/Database/paracelBLASTN.item

However, this .item file will be ignored unless we also add the name of the file to the makemenus/menus/menulist file. In this example, we need to have an entry added to the file that looks like this:

Database
    paracelBLASTN

Note: the indentation is done by a single TAB character, NOT using spaces. The syntax for creating a menulist file is more fully explained in the manual page for menulist. Do not go any further before you read this page!

1.4.3 Merging your menu item into the .GDEmenus file

Your local menus items will be merged  with the core menus when a biolegato instance launches. For example, if the paracelBLASTN command was only available on Solaris hosts, your menulist file would look like this:

Database
    paracelBLASTN   S

Again, you have to read the menulist manual page for full details.

1.4.4 Testing and refining your menu item

For the new menu to appear, you have to launch a new bioLegato window after running makemenus.py. This is because the menus in bioLegato are read from .GDEmenus only when the program first starts. One trick for doing many test and refine cycles is to run makemenus.py, and then, in your bioLegato window, choose Edit --> Select All, and then Edit --> Extract. This will take the contents of the current bioLegato window and launch a new bioLegato window, which will have the updated menus. That saves having to launch bioLegato at the command line and re-read the data each time you run the program.

The debugging process can be a difficult one . One of the most useful tricks for debugging is to insert commands into the itemmethod: commands that open up intermediate files in a text editor. That way, you can see whether any given step was successful. For example,

itemmethod: sed "s/[#%]/>/" <in1 >in1.test; $GDE_TEXTEDIT in1.test; cat in1.test | prot2nuc -l$LINLEN -g$GROUP > in1.out; ($GDE_TEXTEDIT in1.out; rm in1*)&

will let you verify that the sed command worked corrrectly before prot2nuc is run.

Leverage the multiwindow environment

For this kind of work, you can make things a lot easier by having different windows for different steps. For the test and refine process you might have the following windows on your screen:

• a text editor with your bioLegato menu item file
• a terminal window in the $BIRCH/dat/GDE/ directory. Run makemenus.py in this window. If the only command you type in this window is 'python makemenus.py', the shell's history command can save you some typing. If you type '!!' the previous command will be repeated.
• a terminal window open to the directory in which you are testing GDE. Launch bioLegato from this window.
  

Using this strategy, moving back and forth between directories does not have to be done using 'cd'. Rather, you move between directories by moving from one window to the other.