Redirected from page "Admin/Tools/Add Tool Tutorial"

Clear message
Locked History Actions

Admin/Tools/AddToolTutorial

Adding custom tools to Galaxy

Vast number of good and well-implemented tools for Galaxy is available through the Galaxy ToolShed and you can freely install any of them into your Galaxy instance via the admin interface. Short tutorial to get you started is available here.

If you did not find your favorite tool in the ToolShed you can always add it to your Galaxy manually (and later share in the Tool Shed with the rest of the world if you like). This article will help you with this creation of a custom tool in your Galaxy.

See also the Tutorial for Creating a Histogram Tool.

1. Write and test your tool outside Galaxy:

Suppose one has written a simple Perl script (called toolExample.pl) for computing the GC content of a sequence in the FASTA format, which looks like this:

   1 #!/usr/bin/perl -w
   2 
   3 # usage : perl toolExample.pl <FASTA file> <output file>
   4 
   5 open (IN, "<$ARGV[0]");
   6 open (OUT, ">$ARGV[1]");
   7 while (<IN>) {
   8     chop;
   9     if (m/^>/) {
  10         s/^>//;
  11         if ($. > 1) {
  12             print OUT sprintf("%.3f", $gc/$length) . "\n";
  13         }
  14         $gc = 0;
  15         $length = 0;
  16     } else {
  17         ++$gc while m/[gc]/ig;
  18         $length += length $_;
  19     }
  20 }
  21 print OUT sprintf("%.3f", $gc/$length) . "\n";
  22 close( IN );
  23 close( OUT );

To integrate this tool into Galaxy we will follow these steps:

2. Put tool into Galaxy's tools directory:

To begin the tool integration process we need to add our Perl script to the tools/ directory, where all tool-related files are stored. In this example we will create a new subdirectory called myTools within tools/. So cd to your Galaxy installation and type these commands:

   1 cd tools
   2 mkdir myTools
   3 cd myTools

Now one needs to copy the script (in this case toolExample.pl) into the tools/myTools/ directory.

3. Create Tool Definition File:

At this point toolExample.pl resides within the tools/myTools/ directory, but Galaxy still does not know how to run this tool. To let Galaxy know the execution details of our new tool, we need to write a tool configuration file, which, in this case, will be called toolExample.xml. For this particular example open a text editor of your choice and create the toolExample.xml file within the tools/myTools directory. This file looks like this:

   1 <tool id="fa_gc_content_1" name="Compute GC content" version="0.1.0">
   2   <description>for each sequence in a file</description>
   3   <command interpreter="perl">toolExample.pl $input $output</command>
   4   <inputs>
   5     <param format="fasta" name="input" type="data" label="Source file"/>
   6   </inputs>
   7   <outputs>
   8     <data format="tabular" name="output" />
   9   </outputs>
  10 
  11   <tests>
  12     <test>
  13       <param name="input" value="fa_gc_content_input.fa"/>
  14       <output name="out_file1" file="fa_gc_content_output.txt"/>
  15     </test>
  16   </tests>
  17 
  18   <help>
  19 This tool computes GC content from a FASTA file.
  20   </help>
  21 
  22 </tool>

Note how this file specifies command line parameters, links them to input and output, and provides help information using the restructured text format. Once you are done, the tools/myTools directory will contain two files toolExample.pl and toolExample.xml. For basic and general tool definition file please see Example Tool Definiton File. Once you feel comfortable with the basics you can browse through the full tool definition syntax.

4. Make Galaxy aware of the new tool:

Now the tool and its configuration file are ready. The final step makes Galaxy aware of the new tools. Galaxy knows about installed tools (and also what to display on the left pane) from the tool_conf.xml tool-registry file. Thus, letting Galaxy know about our new tool is as easy as adding these lines to the tool_conf.xml file located in the config directory of the Galaxy distribution:

   1  <section name="MyTools" id="mTools">
   2     <tool file="myTools/toolExample.xml" />
   3  </section>

5. Start it up:

At this point, start Galaxy by typing sh run.sh from within Galaxy's root directory and point your browser to http://localhost:8080. The interface of the new tool will look like this:

Admin/Tools/AddToolTutorial/toolExample.png

Note the correspondence between elements of the toolExample.xml file (Step 2) and the interface elements shown above. The "Compute GC for" dropdown reads "no data has the proper type" because the history pane contains no data in the FASTA format (it is empty).

6. (optional) Upload your tool to the Tool Shed:

If you want to easily share your tool with others upload it to the Galaxy Tool Shed. It allows others to install the tool into their Galaxies seamlessly via the Admin interface. If the tool is well written and tested it can even make it to the Main Galaxy instance or other Public Galaxy Servers!

To get started with the sharing of your tool please see Tool Shed's Get started.

Tool Development Resources