annotate create_tool_recommendation_model.xml @ 2:76251d1ccdcc draft

"planemo upload for repository https://github.com/bgruening/galaxytools/tree/recommendation_training/tools/tool_recommendation_model commit 6fa2a0294d615c9f267b766337dca0b2d3637219"

<tool id="create_tool_recommendation_model" name="Create a model to recommend tools" version="0.0.1">
    <description>using deep learning</description>
    <requirements>
        <requirement type="package" version="3.6">python</requirement>
        <requirement type="package" version="1.13.1">tensorflow</requirement>
        <requirement type="package" version="2.3.0">keras</requirement>
        <requirement type="package" version="0.21.3">scikit-learn</requirement>
        <requirement type="package" version="2.9.0">h5py</requirement>
        <requirement type="package" version="1.0.4">csvkit</requirement>
        <requirement type="package" version="0.1.2">hyperopt</requirement>
    </requirements>
    <version_command>echo "@VERSION@"</version_command>
    <command detect_errors="aggressive">
<![CDATA[
        python '$__tool_directory__/main.py'
            --workflow_file '$input_tabular_workflows'
            --tool_usage_file '$input_tabular_tool_usage'
            --cutoff_date '$data_parameters.input_cutoff_date'
            --maximum_path_length '$data_parameters.input_maximum_path_length'
            --n_epochs '$training_parameters.n_epochs'
            --optimize_n_epochs '$training_parameters.optimize_n_epochs'
            --max_evals '$training_parameters.max_evals'
            --test_share '$training_parameters.test_share'
            --validation_share '$training_parameters.validation_share'
            --batch_size '$nn_parameters.batch_size'
            --units '$nn_parameters.units'
            --embedding_size '$nn_parameters.embedding_size'
            --dropout '$nn_parameters.dropout'
            --spatial_dropout '$nn_parameters.spatial_dropout'
            --recurrent_dropout '$nn_parameters.recurrent_dropout'
            --learning_rate '$nn_parameters.learning_rate'
            --activation_recurrent '$nn_parameters.activation_recurrent'
            --activation_output '$nn_parameters.activation_output'
            --output_model '$outfile_model'
]]>
    </command>
    <inputs>
        <param name="input_tabular_workflows" type="data" format="tabular" label="Dataset containing workflows" help="Please provide Galaxy workflows as a tabular file."/>
        <param name="input_tabular_tool_usage" type="data" format="tabular" label="Dataset containing usage frequencies of tools" help="Please provide tools usage frequencies as a tabular file."/>
        <section name="data_parameters" title="Data parameters" expanded="False">

            <param name="input_cutoff_date" type="text" value="2017-12-01" label="Cutoff date" help="Provide a date (in the past) in yyyy-mm-dd format. The earliest date from which usage of tools will be extracted. For example, 2017-12-01 specifies that the usage of tools from this date until the data extraction date is extracted. The usage of tools before this date is not considered."/>

            <param name="input_maximum_path_length" type="integer" value="25" label="Maximum number of tools in a tool sequence" help="Provide an integer between 1 and 25. A workflow is divided into unique paths and this number specifies the maximum number of tools a path can have. Paths longer than this number are ignored and are not included in the deep learning training."/>

        </section>
        <section name="training_parameters" title="Training parameters" expanded="False">
            <param name="max_evals" type="integer" value="50" label="Maximum number of evaluations of different configurations of parameters" help="Provide an integer. Different combinations of parameters are sampled and optimized to find the best one. This number specifies the number of different configurations sampled and tested."/>

            <param name="optimize_n_epochs" type="integer" value="20" label="Number of training iterations to optimize the neural network parameters" help="Provide an integer. This number specifies the number of training iterations done for each sampled configuration while optimising the parameters."/>

            <param name="n_epochs" type="integer" value="20" label="Number of training iterations" help="Provide an integer. This specifies the number of deep learning training iterations done after finding the best/optimised configuration of neural network parameters."/>

            <param name="test_share" type="float" value="0.0" label="Share of the test data" help="Provide a real number between 0.0 and 1.0. This set of data is used to look through the prediction accuracy on unseen data after neural network training on an optimised configuration of parameters. It should be set to 0.0 while training for a model to be deployed to production. The minimum value can be 0.0 and maximum value should not be more than 0.5."/>

            <param name="validation_share" type="float" value="0.2" label="Share of the validation data" help="Provide a real number between 0.0 and 1.0. This set of data is used to validate each step of learning while optimising the configurations of parameters. The minimum value can be 0.0 and maximum value should not be more than 0.5."/>

        </section>
        <section name="nn_parameters" title="Neural network parameters" expanded="False">
            <param name="batch_size" type="text" value="1,512" label="Training batch size" help="Provide a comma-separated range to sample the batch size from. The training of the neural network is done using batch learning in this work. The training data is divided into equal batches and for each epoch (a training iteration), all the batches of data are trained one after another. An example: 1,512." />

            <param name="units" type="text" value="1,512" label="Number of hidden recurrent units" help="Provide a comma-separated range to sample the number of hidden recurrent units. A higher value provide stronger neural network model (may lead to overfitting in case of smaller data) and smaller value leads to weaker model (may lead to underfitting in case of larger data). An example: 1,512."/>

            <param name="embedding_size" type="text" value="1,512" label="Embedding vector size" help="Provide a comma-separated range to sample the embedding size for tools. A fixed-size vector is learned for each tool. This number specifies the fixed-size. An example: 1,512."/>

            <param name="dropout" type="text" value="0.0,0.5" label="Dropout between neural network layers" help="Provide a comma-separated range to sample the amount of dropout to be used after neural netwrok layers. The minimum value should be 0.0 and the maximum value should be 1.0. Dropout is used to prevent or minimize overfitting after each neural network layer. An example: 0.0,0.5"/>

            <param name="spatial_dropout" type="text" value="0.0,0.5" label="Dropout for the embedding layer" help="Provide a comma-separated range to sample the amount of dropout to be used after embedding layer. The minimum value should be 0.0 and the maximum value should be 1.0. Dropout is used to prevent or minimize overfitting in the embedding layer. An example: 0.0,0.5"/>

            <param name="recurrent_dropout" type="text" value="0.0,0.5" label="Dropout for recurrent layers" help="Provide a comma-separated range to sample the amount of dropout to be used for the recurrent layers. The minimum value should be 0.0 and the maximum value should be 1.0. Dropout is used to prevent or minimize overfitting in the recurrent layers. An example: 0.0,0.5"/>

            <param name="learning_rate" type="text" value="0.0001,0.1" label="Learning rate" help="Provide a range of positive real numbers to sample the learning rate. Learning rate defines the speed of neural network learning. A higher value will ensure fast learning and smaller value will ensure slower learning. An example: 0.0001,0.1"/>
            <param name="activation_recurrent" type="text" value="elu" label="Name of the activation function for recurrent layers" help="It is a mathematical function that transforms the input of recurrent layers to the following neural network layer."/>

            <param name="activation_output" type="text" value="sigmoid" label="Name of the activation function for output layer" help="It is a mathematical function that transforms the input of the last dense layer to the output of the neural network."/>
        </section>
    </inputs>
    <outputs>
        <data format="h5" name="outfile_model" label="Model to recommend tools in Galaxy"></data>
    </outputs>
    <tests>
        <test>
            <param name="input_tabular_workflows" value="test_workflows" ftype="tabular"/>
            <param name="input_tabular_tool_usage" value="test_tool_usage" ftype="tabular"/> 
            <param name="max_evals" value="1"/>
            <param name="optimize_n_epochs" value="1"/>
            <param name="n_epochs" value="1"/>
            <param name="test_share" value="0.1"/>
            <output name="outfile_model">
                <assert_contents>
                    <has_h5_keys keys="best_parameters,class_weights,compatible_tools,data_dictionary,model_config,weight_0,weight_1,weight_2,weight_3,weight_4,weight_5,weight_6,weight_7,weight_8"/>
                </assert_contents>
            </output>
        </test>
        <test>
            <param name="input_tabular_workflows" value="test_workflows" ftype="tabular"/>
            <param name="input_tabular_tool_usage" value="test_tool_usage" ftype="tabular"/>
            <param name="max_evals" value="1"/>
            <param name="optimize_n_epochs" value="1"/>
            <param name="n_epochs" value="1"/>
            <param name="test_share" value="0.0"/>
            <output name="outfile_model">
                <assert_contents>
                    <has_h5_keys keys="best_parameters,class_weights,compatible_tools,data_dictionary,model_config,weight_0,weight_1,weight_2,weight_3,weight_4,weight_5,weight_6,weight_7,weight_8"/>
                </assert_contents>
            </output>
        </test>
        <test expect_failure="true">
            <param name="input_tabular_workflows" value="test_workflows" ftype="tabular"/>
            <param name="input_tabular_tool_usage" value="test_tool_usage" ftype="tabular"/>
            <param name="validation_share" value="0.0"/>
        </test>
        <test expect_failure="true">
            <param name="input_tabular_workflows" value="test_workflows" ftype="tabular"/>
            <param name="input_tabular_tool_usage" value="test_tool_usage" ftype="tabular"/>
            <param name="batch_size" value="1"/>
        </test>
        <test expect_failure="true">
            <param name="input_tabular_workflows" value="test_workflows" ftype="tabular"/>
            <param name="input_tabular_tool_usage" value="test_tool_usage" ftype="tabular"/>
            <param name="units" value="1"/>
        </test>
        <test expect_failure="true">
            <param name="input_tabular_workflows" value="test_workflows" ftype="tabular"/>
            <param name="input_tabular_tool_usage" value="test_tool_usage" ftype="tabular"/>
            <param name="embedding_size" value="1"/>
        </test>
        <test expect_failure="true">
            <param name="input_tabular_workflows" value="test_workflows" ftype="tabular"/>
            <param name="input_tabular_tool_usage" value="test_tool_usage" ftype="tabular"/>
            <param name="dropout" value="0.1"/>
        </test>
        <test expect_failure="true">
            <param name="input_tabular_workflows" value="test_workflows" ftype="tabular"/>
            <param name="input_tabular_tool_usage" value="test_tool_usage" ftype="tabular"/>
            <param name="spatial_dropout" value="0.1"/>
        </test>
        <test expect_failure="true">
            <param name="input_tabular_workflows" value="test_workflows" ftype="tabular"/>
            <param name="input_tabular_tool_usage" value="test_tool_usage" ftype="tabular"/>
            <param name="recurrent_dropout" value="0.1"/>
        </test>
         <test expect_failure="true">
            <param name="input_tabular_workflows" value="test_workflows" ftype="tabular"/>
            <param name="input_tabular_tool_usage" value="test_tool_usage" ftype="tabular"/>
            <param name="learning_rate" value="0.0001"/>
        </test>
    </tests>
    <help>
        <![CDATA[
**What it does**

**Description**

It creates a model to recommend tools in Galaxy by learning the connections of tools in workflows. The model is an HDF5 file containing the tool dictionary, weights and configuration of the neural network. The recurrent neural network (Gated Recurrent Units) is used as a deep learner to learn the higher-order dependencies in tool connections of workflows. It takes two tabular files as input - one for the workflows and another for tools' usage frequencies. There are multiple other parameters to be set to find the best configuration of parameters of the neural network. This is achieved using bayesian optimisation hyperparameter search approach. Once the best configuration is found, a model is created which can be used to recommend tools in Galaxy. Further details about the input data and network parameters are explained below.

-----

**Input files**

There are two input files:

1. The first file ("dataset containing workflows") contains tool connections for workflows in a tabular format. The workflows are arranged as pairs of tool connections. Each row is a pair of tool connections in a workflow as shown below:

    ==========  ===================       =========    =================          =============    ==========     ============   ==============
    **wf_id**   **wf_updated**            **in_id**    **in_tool**                **in_tool_v**    **out_id**     **out_tool**   **out_tool_v**
    ----------  -------------------       ---------    -----------------          -------------    ----------     ------------   --------------
    3           2013-02-07 16:48:00       7            Remove beginning1          1.0.0            5              Grep1          1.0.1
    ==========  ===================       =========    =================          =============    ==========     ============   ==============

The first column (wf_id) is the workflow id, second (wf_updated) is the last updated date timestamp, third (in_id) is the id of the tool which is the input to the tool connection, fourth (in_tool) is the   name of the input tool, fifth (in_tool_v) is the version of the input tool, sixth (out_id) is the id of the output tool in the tool connection, seventh (out_tool) is the name of the output tool and the last one (out_tool_v) is the version of the output tool. The tools connections (rows) for each workflow are used to recreate the workflow (directed acyclic graph) and unique tool sequences for each workflow are extracted. These tool sequences are then used to learn higher-order dependencies using a recurrent neural network to recommend tools.
    
2. The second file ("dataset containing usage frequencies of tools") is also a tabular file containing the usage frequencies of tools for a period of time. It has 3 columns:

    ============================================================================================  ==========  ===   
    upload1                                                                                       2019-03-01  176
    toolshed.g2.bx.psu.edu/repos/devteam/fastqc/fastqc/0.72                                       2019-03-01  97
    toolshed.g2.bx.psu.edu/repos/bgruening/deeptools_bam_coverage/deeptools_bam_coverage/3.0.2.0  2019-03-01  67
    ============================================================================================  ==========  ===

The first column is the name of the tool, second is the date and the last one is the number of times the tool has been used in a month. For example, if this data is collected for 1 year, then each tool will appear in this list at most 12 times (months in which the usage is > 0). This data helps to know the usage pattern of a tool i.e. if a tool is being used often (high frequency in recent months) in the last one year or not being used at all (low frequency in recent months). This frequency is then used as weights for these tools in the neural network learning. The tools with high frequency in recent months is more important than tools with low frequency in recent months. This constraint allows to phase-out those tools from predictions which are not being used recently.

-----


**Parameters**

There are multiple parameters which can be set. They are divided into 3 categories:

1. Data parameters
    - "input_cutoff_date": It is used to set the earliest date from which the usage frequencies of tools should be considered. The format of the date is YYYY-MM-DD. This date should be in the past.
    - "input_maximum_path_length": This takes an integer and specifies the maximum size of a tool sequence extracted from any workflow. Any tool sequence of length larger than this number is not included in the dataset for training.
    
2. Training parameters
    - "max_evals": The hyperparameters of the neural network are tuned using a Bayesian optimisation approach and multiple configurations are sampled from different ranges of parameters. The number specified in this parameter is the number of configurations of hyperparameters evaluated to optimise them. Higher the number, the longer is the running time of the tool.
    - "optimize_n_epochs": This number specifies how many iterations would the neural network executes to evaluate each sampled configuration.
    - "n_epochs": Once the best configuration of hyperparameters has been found, the neural network takes this configuration and runs for "n_epochs" number of times minimising the error to produce a model at the end.
    - "test_share": It specifies the size of the test set. For example, if it is 0.5, then the test set is half of the entire data available. It should not be set to more than 0.5. This set is used for evaluating the precision on an unseen set.
    - "validation_share": It specifies the size of the validation set. For example, if it is 0.5, then the validation set is half of the entire data available. It should not be set to more than 0.5. This set is used for computing error while training on the best configuration.
    
3. Neural network parameters:
    - "batch_size": The training of the neural network is done using batch learning in this work. The training data is divided into equal batches and for each epoch (a training iteration), all batches of data are trained one after another. A higher or lower value can unsettle the training. Therefore, this parameter should be optimised.
    - "units": This number is the number of hidden recurrent units. A higher number means stronger learning (may lead to overfitting) and a lower number means weaker learning (may lead to underfitting). Therefore, this number should be optimised.
    - "embedding_size": For each tool, a fixed-size vector is learned and this fixed-size is known as the embedding size. This size remains same for all the tools. A lower number may underfit and a higher number may overfit. This parameter should be optimised as well.
    - "dropout": A neural network tends to overfit (especially when it is stronger). Therefore, to avoid or minimize overfitting, dropout is used. The fraction specified by dropout is the fraction of units "deleted" randomly from the network to impose randomness which helps in avoiding overfitting. This parameter should be optimised as well.
    - "spatial_dropout": Similar to dropout, this is used to reduce overfitting in the embedding layer. This parameter should be optimised as well.
    - "recurrent_dropout": Similar to dropout and spatial dropout, this is used to reduce overfitting in the recurrent layers (hidden). This parameter should be optimised as well.
    - "learning_rate": The learning rate specifies the speed of learning. A higher value ensures fast learning (the optimiser may diverge) and a lower value causes slow learning (may not reach the optimum). This parameter should be optimised as well.
    - "activation_recurrent": Activations are mathematical functions to transform input into output. This takes the name of an activation function from the list of Keras activations (https://keras.io/activations/) for recurrent layers.
    - "activation_output": This takes the activation for transforming the input of the last layer to the output of the neural network. It is also taken from Keras activations (https://keras.io/activations/).

-----

**Output file**

The output file (model) is an HDF5 file (http://docs.h5py.org/en/latest/high/file.html) containing multiple attributes like a dictionary of tools, neural network configuration and weights for each layer, weights of all tools and so on. After the tool has finished executing, it can be downloaded and placed at "/galaxy/database/" inside a Galaxy instance codebase. To see the recommended tools (enable the UI integrations) in Galaxy, the following changes should be made to "galaxy.yml" file:

    - Enable and then set the property "enable_tool_recommendation" to "true".
    - Enable and then set the property "model_path" to "database/<<model_file_name>>".

        ]]>
    </help>
    <citations>
        <citation type="bibtex">
            @ARTICLE{anuprulez_galaxytools,
                Author = {Anup Kumar and Björn Grüning},
                keywords = {bioinformatics, recommendation system, deep learning},
                title = {{Tool recommendation system for Galaxy workflows}},
                url = {https://github.com/bgruening/galaxytools}
            }
        </citation>
    </citations>
</tool>