Unipro UGENE Online User Manual v. 33
Page tree
Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 5 Next »

A custom tool can be integrated into the UGENE GUI as a workflow element in the Workflow Designer - a UGENE component that allows joining tools into workflows.

As described in the "Custom Elements with External Tools" chapter of the Workflow Designer documentation, there are two options when one creates such workflow element:

  • Set a local executable path
  • Set an integrated external tool

The first option is intended for cases when a quick temporary integration of a tool into a workflow is enough.

The second option, although requires additional configuration steps, provides a more close integration with UGENE. It can be used by advanced UGENE users for providing a tool for their colleagues.

Below the preparatory configuration steps for the second option are described.

Create an XML configuration file for custom external tool

Create an XML file with the custom external tool description. The file should match the following XML schema:

<?xml version = "1.0" encoding = "UTF-8"?>
<xs:schema xmlns:xs = "http://www.w3.org/2001/XMLSchema">

<xs:element name = "ugeneExternalToolConfig">
    <xs:complexType>
        <xs:sequence>
            <xs:element name = "name" type = "xs:string" />
            <xs:element name = "path" type = "xs:string" minOccurs ="0" />
            <xs:element name = "description" type = "xs:string" minOccurs ="0" />
            <xs:element name = "toolkitName" type = "xs:string" minOccurs ="0" />
            <xs:element name = "version" type = "xs:string" minOccurs ="0" />
            <xs:element name = "launcherId" type = "xs:string" minOccurs ="0" />
            <xs:element name = "dependencies" type = "xs:string" minOccurs ="0" />
            <xs:element name = "binaryName" type = "xs:string" />
        </xs:sequence>
        <xs:attribute name = "version" type = "xs:string" use="required" />
    </xs:complexType>
</xs:element>

</xs:schema>

 

There XML elements have the following meaning:

  • name - the external tool name as it should be displayed in the UGENE GUI. This XML element is mandatory.
  • binaryName - the name of the tool executable file (with the file extension, if it is present). UGENE will search for this file in some well-known locations during the UGENE start, if the tool path is not defined for some reasons. This XML element is mandatory.
  • path - a path to the external tool. It can be relative to the current config file location or absolute. You can set it in UGENE Application Settings later. This XML element is optional.
  • description - a detailed description of the external tool. This XML element is optional.
  • toolkitName - a name of the toolkit to group external tools. If it is not defined or empty, then the external tool name will be used as the toolkit name. This XML element is optional.
  • version - a version of the tool executable. This XML element is optional.

  • launcherId - if the tool is supposed to be run with some script interpreter or it is a java application, then this element should contain an appropriate ID. Currently, UGENE supports the following launchers IDs: PYTHON2, PERL, RSCRIPT, JAVA. If the launcher is specified, it would be added to the launch command explicitly whenever you try to launch the external tool. The path to the launcher will be taken from the "Application Settings" (see the corresponding tools in the "Supported tools" group). If the element is not specified or it is empty, no additional launcher will be added to the command that will run the tool. This XML element is optional.

  • dependencies - a comma-separated list of other external tool IDs the new tool is dependent from. If the dependency is not satisfied, then the dependent tool is marked as "not valid" in UGENE. This XML element is optional.

See also the following examples:

  1. A minimalistic config: 

    <?xml version = "1.0" encoding = "UTF-8"?>
<ugeneExternalToolConfig version = "1.0">
    <name>An imported custom tool</name>
    <binaryName>my_tool.py</binaryName>
</ugeneExternalToolConfig>

    This config describes only a tool name and a tool binary name. After the import the path will be empty, the tool won't have any dependencies, its version will be "unknown".

  2. A config without dependencies and a launcher:

    <?xml version = "1.0" encoding = "UTF-8"?>
<ugeneExternalToolConfig version = "1.0">
    <name>RAxML</name>
    <path>raxmlHPC</path>
    <description>RAxML - Randomized Axelerated Maximum Likelihood</description>
    <version>8.2.12</version>
    <binaryName>raxmlHPC</binaryName>
</ugeneExternalToolConfig>

    This config describes an external tool with a description and a version. Path to the tool executable is relative: it is supposed that the executable is in the same folder as the config file.

  3. A config with a dependecy and a launcher:

    <?xml version = "1.0" encoding = "UTF-8"?>
<ugeneExternalToolConfig version = "1.0">
    <name>HISAT2</name>
    <path>d:\work\hisat2.1\hisat2</path>
    <description>HISAT2 is a fast and sensitive alignment program for 
mapping next-generation sequencing reads (both DNA and RNA) to a 
population of human genomes (as well as to a single reference genome).</description>
    <toolkitName>HISAT2</toolkitName>
    <version>2.1.0</version>
    <launcherId>PERL</launcherId>
    <dependencies>PERL</dependencies>
    <binaryName>hisat2</binaryName>
</ugeneExternalToolConfig>

    This config describes a tool that is supposed to be run by the Perl interpreter. There is no Perl by default on Windows, but the UGENE installer provides a possibility to install Perl. The tool can notify UGENE that it should be launched by Perl, so UGENE will add a path to Perl to the command that runs the tool.

Prepare a package with the XML configuration tool and the tool

The easiest way to "pack" the custom external tool is to:

  • create a new folder with all files required for running the tool,
  • specify a relative path in the XML configuration file described above,
  • put the XML configuration in the same folder as the main tool executable.

This "package" can be shared with other users, if required.

Import the tool in UGENE

To add the custom external tool one need to import its XML configuration file in the "Custom tools" group on the "External Tools" page of the "Application Settings" dialog.

 

  • No labels