NewToolSetup

== Adding a new BALL-based tool to ballaxy ==

The ballaxy tools reside in the ball repository in the folder "/~/ball/source/APPLICATIONS/TOOLS". \ If you want to create a new tool you have to do the following: \

[=#point1 (1)] Create a c++ file called NameOfYourNewTool.C (yes, it's .C) in the folder mentioned above and write some content in it. Preferably a working c++ program. \ For parsing the command line parameters, which is needed for proper ballaxy tools, use BALL's commandline parser\ #include <BALL/FORMAT/commandlineParser.h>. \ This in turn allows to use BALL's GalaxyConfigGenerator class, which is automatically called when building ballaxy (see step [#point4 (4)] to create galaxy tool config xml files.

[=#point2 (2)] Open the file "sources.cmake" in the aforementioned folder and enter "NameOfYourNewTool" in the set of executables.

[=#point3 (3)] In the build folder of your BALL repository: Configure BALL again by typing "cmake .. -DBALL_BUILD_BALLAXY=true".

[=#point4 (4)] Compile ballaxy by typing "make ballaxy".

[=#point5 (5)] After doing this, you have to add your tool to the ballaxy tool configuration.

Either manually add "NameOfYourNewTool" to the file "tool_conf.xml" in "//ballaxy/galaxy-dist" in the appropriate section \ "OR" \ copy a predefined configuration of the ballaxy build located in the file "tool_conf.xml.section" in the folder "//ballaxy/ball/build/ballaxy/default" to "tool_conf.xml". \ You can do this by opening the file "tool_conf.xml.section" in "/~/ballaxy/galaxy-dist", removing all sections parts, entering the content of the file mentioned before and saving the result as "tool_conf.xml". \

[=#point6 (6)] Start the ballaxy server as usual and enjoy your new tool.

Best practice is to have a look into one of the existing tools to get BALL's CommandlineParser (for handling multiple output files, optional parameters, parameters limited for bash use...).

{{{#!comment The explanation should clearly show how to deal with input and output parameters to allow for the integration in a workflow. }}}

Parameters in BALL-based tools

BALL's commandline parser class handles all tasks for registering parameters and flags of the tool, tool manual texts, define restrictions on parameters and register file-formats that are supported for in- or output-files, and specifying the environment in which the tools shall run.

All tools created that way have a number of predefined parameters:

• '-env' allows to differentiate between command line ('cmdline') behaviour and special adaptions to workflow systems like galaxy or knime.
• '-write_par' allows to specify an xml-based parameter-file that will be automatically written, containing the specification of the tool, all its parameters and all parameter values used on the commend-line
• '-par' allows to read such a file, so that the parameter-values stored in it will be used. If parameters (other than -par) are specified on the command-line, their values will automatically overload those stored in the xml-file.

[=#clpoint1 (1)] First instatiate a commandline parser {{{ CommandlineParser parpars(tool_name, tool_description, tool_version, build_date, category) }}} where

• tool_name (String): the tools name
• tool_description (String): the tools brief description (will appear in the ballaxy's left hand side tool list)
• tool_version (String): the tool version, including #include "version.h" allows to use the ballaxy VERSION macro
• build_date (String): the date of the build, for convenience use String(__DATE__)
• category (String): the category under which the tool shall appear (ballaxy's left hand side tool list)

[=#clpoint2 (2)] Next register the input and output parameters {{{ registerParameter (String name, String description, ParameterType type, bool mandatory=false, String default_value="", bool hidden=false) }}} where

• name : the parameters switch name with which its value can be queried
• description: the description of the parameter (used for generating the parameter help)
• type : the type of the parameter, e.g. INFILE, OUTFILE, INT, DOUBLE, STRING,
• mandatory : denote, if this parameter is required
• default_value : the default value
• hidden : denote, if this parameter shall be hidden in the ballaxy GUI (default is false, needed for multiple output parameters see below)

Please not, that boolean parameters need a call to {{{ registerFlag (String name, String description, bool default_gui_value=false, bool hidden=false) }}}

Example for input files: {{{ parpars.registerParameter("i", "input mol2-file", INFILE, true); }}}

Example for output parameters: {{{ parpars.registerParameter("o", "output file name", OUTFILE, false, "", true); }}}

If you have multiple output parameters, the following trick is needed:

• create a normal output file
• create an output file identifier with type GALAXY_OPT_OUTID), non-mandatory, and a default value "$o.id" and hidden in the ballaxy GUI
• also exclude the id-parameter from the command line mode {{{ parpars.registerParameter("o_id", "output id", GALAXY_OPT_OUTID, false, "$o.id", true); // need to be hidden in command line mode parpars.setParameterAsAdvanced("o_id"); }}}

[=#clpoint3 (3)] Then register the manual {{{ String man = String("This tool does something given other stuff.\n\nOptional parameters are ... ".\n\nOutput of this tool is something fancy.\n\nFurther information and help ..."); parpars.setToolManual(man); }}}

[=#clpoint4 (4)] Then specify the supported file types for all input and output file parameters {{{ parpars.setSupportedFormats("i","mol2"); parpars.setSupportedFormats("o","mol2"); }}}

Currently BALL supports the following file formats: ac, dat, dcd, fasta, hin, mol, mol2, sdf, pdb, txt, xyz.

Please keep in mind that adding further file types need special adaptions with the galaxy core!

[=#clpoint5 (5)] Finally parse the given arguments {{{ parpars.parse(argc, argv); }}}

[=#clpoint6 (6)] and query the parameters in your main tool code using the method get (String name), e.g.

{{{ MOL2File f0; f0.open(parpars.get("i")); }}}