BIRCH BIRCH - Adding binaries, scripts and libraries

1.1 Binaries and scripts

Add new programs to the appropriate directory as follows:
BIRCH automatically includes the bin and script directories (but not java) in the $PATH. Once you add a binary or a script, it can be run by all users.

Note: remember to make your scripts and binaries world-readable and world-executable.

1.2 Setting environment variables and $PATH

Many programs require one or more environment variables. These need to be set both for shells in the BOURNE shell family and C-shell family. That is, you can't predict which shell users might be using, so you need to set these variables for both shell families. These should be set in the following files:
 For many of the popular viewers, editors and browsers, environment variables are already available in these files, commented out. All you need to do is to uncomment the appropriate variable and it will override the BIRCH default.

See Choosing default applications for viewing and displaying data for more details.

1.3 Libraries

For each platform, library directories are provided for locally-added programs:
 The recommended method for getting programs to find these library directories is to launch the program from a wrapper script that sets the environment variable $LD_LIBRARY_PATH. A good example can be found in $BIRCH/script/sequin, which adds several libraries to $LD_LIBRARY_PATH and launches the sequin binary. This way, LD_LIBRARY_PATH changes only in the shell running sequin, and not in any other shell.

A good practice is to always create a new subdirectory within lib-xxx-xxx for each program that needs supplemental libraries. This keeps all libraries for a program together, and makes it more straightforward when updating libraries or removing a program at a later time.

In earlier versions of BIRCH, $LD_LIBRARY_PATH was set in cshrc.source and profile.source, and included all possible libraries that might be needed, along with system libraries. The danger of using this approach is that LD_LIBRARY_PATH replaces, rather than adding to, the library search path. Therefore, if you don't correctly guess all of the possible library paths on your system, you risk breaking other programs. A more in-depth discussion of this point is found at Shared Library Search Paths by Russ Allbery.

Notes:
  1. Another alternative, if you have root permissions, is to add library files to /usr/local/lib. On Linux systems, you can find out whether this directory is in the library search path by checking the file /etc/ld.so.conf.

1.4 Adding programs to BioLegato

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.

This section provides the information you need to add programs to BioLegato at your site. You will discover that actually, the hard part about adding a new program is first figuring out how to run that program at the command line. Subsequently,  creating a BioLegato menu is straightforward.

There are three critical things to know:
  • The distinctions between the different instances of BioLegato.
  • How the BioLegato menus are organized in hierarchical folders
  • How to reuse and modify existing menus to create new menus

The BioLegato Graphical Interfaces

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

bl_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

Remembering that virtually all of BioLegato is programmable, we can create new instances of BioLegato by creating new wrapper scripts, and their corresponding instance directories. For example, the bldna script contains a line that tells BioLegato where to look for its menus:

BL_DATA_DIR=$BIRCH/dat/bldna

Similarly, there is another line in the script which identifies a properties file to be read, which includes various default settings for this BioLegato instance:

BL_PROPERTIES=$BL_DATA_DIR/bldna.properties

BioLegato Menus are Read from a set of hierarchically organized folders

Each BL_DATA_DIR will contain, at least, a directory called PCD, which contains the hierarchical menus to be included in the BioLegato window, and a .properties file that contains various parameters for running BioLegato.
Example of a BioLegato folder - bldna
$BIRCH/dat/bldna
bldna.properties
PCD
Alignment
Database
DNARNA
AssembleContigs.blmenu
Bachrest.blmenu
BLrevcomp.blmenu
Findall.blmenu
NUMSEQ.blmenu
pcd_order
Ribosome.blmenu
TACGrest.blmenu
.......
Similarity
pcd_order


For each menu in BioLegato, there is a folder by that name within the PCD folder. In the example above, the folders are shown in alphabetical order. For brevity, only a few folders are listed above. The order in which the menus are to appear in BioLegato are read from a file within the PCD directory called 'pcd_order'.

In $BIRCH/dat/blinstance, the pcd_order lists the order of menus as they appear left to right. The name of the menu is simply the name of the directory. Each directory contains files whose names end in '.blmenu'. For example, in $BIRCH/dat/bldna, pcd_order contains the following lines:
pcd_order file
 Appearance of menus, left to right, in BioLegato
File
Edit
 Documentation
DNARNA
RNA_Struct
Similarity
Database
Patterns
Alignment
Primers
Phylogeny
Help

Similarly, the directory for each menu has a pcd_order file. For example, the order of menu items in the DNARNA menu is determined by a file called $BIRCH/dat/bldna/PCD/DNARNA/pcd_order.
pcd_order file
 Appearance of DNARNA menu, top to bottom
 
AssembleContigs.blmenu
NUMSEQ.blmenu
BLrevcomp.blmenu
Ribosome.blmenu
Findall.blmenu
Bachrest.blmenu
TACGrest.blmenu

When bldna starts, it reads .blmenu files from the subirectories found in $birch/local/dat/bldna/PCD, 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.

You can override the default order of menu items, and even replace or remove menu items, by creating pcd_order files in your $BIRCH/local/dat/blinstance directories.

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

name.blmenu

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.

Creating a  BioLegato menu

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: 
name        "PROT2NUC - reverse translation"
icon    "$BIRCH/public_html/images/birch_black_ico.png"
tip    "use ambiguity symbols to represent all possible DNA sequences encoding each amino acid in a protein"
var "linlen"
    type        number
    label       "CODONS PER LINE"
    min         5
    max         100
    default     25
var "in1"
    type        tempfile
    direction   in
    format      flat
    save        true
var "group"
    type        number
    label       "NUMBERING INTERVAL (amino acids/codons)"
    min         5
    max         100
    default     5
panel
    var "Run"
        type        button
        label       "Run"
        shell       "sed ""s/[#%]/>/"" <%in1% | prot2nuc  -l%LINLEN% -g%GROUP% > %in1%.out; ($BL_TextEditor %in1%.out; rm %in1%*)&"
        close       true
    var "Help"
        type        button
        label       "Help"
        shell       "$BIRCH/script/chooseviewer.py $BIRCH/doc/xylem/prot2nuc.txt"
        close       false

The shell field 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 a temporary file with a name such as bio87676544.out, represented in the shell command as %in1%.out, which is launched using the text editor specified in the $BL_TextEditor environment variable.

The menu generated by the above code looks like this:

For a more complete description of how to write PCD menu items, you really have to read the {PDC manual - not yet available}.

Note on BioLegato HELP buttons

The example above shows the syntax for specifying a help file to be opened in when the HELP button is pressed in a PCD item menu. The general formula is:

    var "Help"
        type        button
        label       "Help"
        shell       "program filename"
        close       false
where filename is the file to open 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 are lots and lots of example of menu items in $BIRCH/dat/bl_instance/PCD. As well, when you first install BIRCH, the directory

$BIRCH/local/dat/bl_instance/PCD

will have some menu item files that you could edit to fit your system. For example, there are a set of FASTA  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/PCD

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

Note: By default, menus added to the local/dat directories are added to the bottom of existing menus. To add a new menu, or to specify the exact order of menus or menu items within a menu, see the next section.

1.4.1 Setting the order of menus and menu items using pcd_order files.

For example, if I wanted to add a menuitem named paracelBLASTN.blmenu to the Database menu of bldna, it would be saved as

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

However, this .blmenu file will be ignored unless we also add the name of the file to the pcd_order file.

1.4.2 Testing and refining your menu item

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

Write a first draft of the .blmenu file and place it into the appropriate subdirectory within local/dat/bldna/PCD. Usually it is best to copy an existing .blmenu file, rename it, and modify it for use with the program you wish to add.

If you want the new item to appear somewhere other than at the bottom of the menu, add that item to to local/dat/bldna/PCD/xxx/pcd_order, or add a pcd_order file to this directory, if it doesn't already exist

repeat
launch a new BioLegato window and test the menu
if not satisfactory
refine the menu based on the test
until menu item is satisfactory

For the new menu to appear, you have to launch a new BioLegato window. One trick for doing many test and refine cycles is to 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, 
shell       "sed ""s/[#%]/>/"" <%in1% >%in1%.test; $BL_TextEditor %in1%.test; cat %in1%.test  | prot2nuc  -l%LINLEN% -g%GROUP% > %in1%.out; ($BL_TextEditor %in1%.out; rm %in1%*)&"
will let you verify that the sed command worked corrrectly before prot2nuc is run.

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


Please send suggestions of comments regarding this page to psgendb@cc.umanitoba.ca