annotate rpfba.xml @ 3:b62127088cfe draft

planemo upload for repository https://github.com/galaxyproject/tools-iuc/tree/master/tools/rptools commit 044274b46d50a1d0e3708e80e0dfecf1de653c65

<tool id="rptools_rpfba" name="Flux balance analysis" version="@TOOL_VERSION@+galaxy@VERSION_SUFFIX@" profile="21.09">
    <description>for the RetroPath2.0 heterologous pathways</description>
    <macros>
        <import>macros.xml</import>
    </macros>
    <expand macro="requirements"/>
    <stdio>
        <regex match="WARNING" level="warning" />
        <regex match="ERROR" level="fatal" />
    </stdio>
    <command detect_errors="exit_code"><![CDATA[
        python -m rptools.rpfba '$pathway' '$model' '$compartment_id' '$pathway_with_fba'
            #if str($adv.merge) == "true":
                --merge
            #end if
                --objective_rxn_id '$objective_rxn_id'
                --sim '$input_sim_type.sim_type'
            #if str($adv.ignore_orphan_species) == "true":
                --ignore_orphan_species
            #end if
                --log "error"
            #if str($input_sim_type.sim_type)=="fba"
                --fraction_of 0.0
            #else
                --fraction_of '$input_sim_type.fraction_of'
            #end if
                --biomass_rxn_id '$biomass_rxn_id'
    ]]></command>
    <inputs>
        <param name="pathway" type="data" format="sbml" label="Pathway (rpSBML)" />
        <param name="model" type="data" format="sbml" label="Model (SBML)" />
        <param name="compartment_id" type="text" label="SBML compartment ID" value="c" >
            <validator type="empty_field" message="A compartment ID is required"/>
        </param>
        <param name="objective_rxn_id" type="text" value="rxn_target" label="Reaction ID to optimise" >
            <validator type="empty_field" message="Reaction ID is required"/>
        </param>
        <param name="biomass_rxn_id" type="text" label="Biomass reaction ID" value="" >
            <validator type="empty_field" message="Biomass reaction ID is required"/>
        </param>
        <conditional name="input_sim_type">
            <param name="sim_type" type="select" label="Constraint based simulation type">
                <option value="fraction" selected="true">Fraction of Reaction</option>
                <option value="fba" >FBA</option>
                <option value="pfba">Parsimonious FBA</option>
            </param>
            <when value="fraction">
                <param name="fraction_of" type="float" value="0.75" min="0" max="1.0" label="Fraction of the optimum" />
            </when>
            <when value="pfba">
                <param name="fraction_of" type="float" value="0.95" min="0" max="1.0" label="Fraction of the optimum" />
            </when>
            <when value="fba">
            </when>
        </conditional>
        <section name="adv" title="Advanced Options" expanded="false">
            <param name="merge" type="boolean" label="Output the merged model?" checked="false" display="checkboxes" />
            <param name="ignore_orphan_species" type="boolean" label="Ignore metabolites that are only consumed or produced?" checked="true" />
        </section>
    </inputs>
    <outputs>
        <data name="pathway_with_fba" format="sbml" label="${tool.name}(${input_sim_type.sim_type}) - ${pathway.name}" />
    </outputs>
    <tests>
        <test>
        <!-- test 1: check if identical outputs are produced with R_BIOMASS__3 biomass name ID and BiGG model (iCN718)  -->
            <param name="pathway" value="rp_001_0001_rpfba_in.xml" />
            <param name="model" value="iCN718.xml.gz" />
            <param name="biomass_rxn_id" value="R_BIOMASS__3" />
            <output name="pathway_with_fba" >
                <assert_contents>
                    <is_valid_xml />
                    <!--check fba_fraction value-->
                    <has_text text="5.54302" />
                    <!--check fba_biomass value-->
                    <has_text text="1.31359" />
                    <has_n_lines n="396" />
                </assert_contents>
            </output>
        </test>
        <test>
        <!-- test 2: check if identical outputs are produced with R_BIOMASS__3 biomass name ID and BiGG model (iCN718)  and sim_type=fba-->
            <param name="pathway" value="rp_001_0001_rpfba_in.xml" />
            <param name="model" value="iCN718.xml.gz" />
            <param name="biomass_rxn_id" value="R_BIOMASS__3" />
            <conditional name="input_sim_type">
                <param name="sim_type" value="fba"/>
            </conditional>
            <output name="pathway_with_fba" >
                <assert_contents>
                    <is_valid_xml />
                    <!--check fba_fba value-->
                    <has_text text="16.47058" />
                    <not_has_text text="fba_fraction" />
                    <has_n_lines n="380" />
                </assert_contents>
            </output>
        </test>
        <test>
        <!-- test 3: check if identical outputs are produced with R_DM_biomass_c biomass name ID and BiGG model (iCN718)  and sim_type=pfba-->
            <param name="pathway" value="rp_001_0001_rpfba_in.xml" />
            <param name="model" value="iCN718.xml.gz" />
            <param name="biomass_rxn_id" value="R_DM_biomass_c" />
            <conditional name="input_sim_type">
                <param name="sim_type" value="pfba"/>
            </conditional>
            <output name="pathway_with_fba" >
                <assert_contents>
                    <is_valid_xml />
                    <!--check fba_pfba value-->
                    <has_text text="2623.54248" />
                    <not_has_text text="fba_fraction" />
                    <has_n_lines n="380" />
                </assert_contents>
            </output>
        </test>
    </tests>
    <help><![CDATA[
FBA
=====


Flux balance analysis is a mathematical approach for analyzing the flow of metabolites through a metabolic network. It is performed for heterologous pathways generated by RetroPath2.0. The tool performs the following steps:

- Merges a user-defined GEM SBML model with each given heterologous pathway individually.
- Performs FBA using the CobraPy package. Three different analysis methods are proposed; two of which are native CobraPy methods - standard FBA and Parsimonious FBA, the other one proposed is an in-house analysis method named "Fraction of Reaction".

The "Fraction of Reaction" method involves performing FBA using the "Source Reaction" as the objective function (by default the biomass reaction is specified, which refers to the rate at which all of the biomass precursors are made in the correct proportions). Then the flux of that reaction has its upper and lower bounds set to the same value, determined as a "Fraction of the source reaction" (default is 75% of its optimum). Thereafter, the objective is set to the target reaction followed by performing FBA once again. The tool uses the FBC package to manage the objective and flux bounds.
For the first two, the user must specify the name(s) of reaction(s) that the model will optimize to, while for the latter the user must provide the target reaction but also another source reaction that will be restricted.
Using the Advanced Options, the user can specify the name of the heterologous pathway as created by "Pathways to SBML" and the compartment ID of the heterologous pathway. The user may obtain a merged version of the resulting model, or the heterologous pathway only using the "output the merged model ?" boolean parameter. Using the "Maximize the Objective?", the user may choose to maximize or minimize the objective (biomass production in this case) in the model.

NOTE: In order to FBA works correctly, some of chemical species have to be ignored. These species are selected according to the following criteria:

- pathway species has not been found in the model (neither by its ID nor its InChIKey),
- the species is not the target, and
- the species is only consumed or produced with the heterologue pathway.

.. image:: https://raw.githubusercontent.com/Galaxy-SynBioCAD/rpFBA/standalone/galaxy/img/rpFBA.png
    :width: 60 %
    :align: center

|

The above figure illustrates the steps in the tool's calculation of FBA. The pathway is merged with a GEM SBML model and using the FBC package and CobraPy FBA is performed and the fluxes saved to the SBML file.

Input
-----

Required:

* **Pathway (rpSBML)**\ : SBML file that contains an heterologous pathway
* **Model (SBML)**\ : GEM SBML model file
* **Biomass reaction ID**\ : (string) biomass reaction ID that will be restricted in the "fraction" simulation type. This parameter is ignored for "fba" and "pfba"

Optional:

* **SBML compartment ID**\ : (string, default='c') Model compartment id (e.g. 'c' or 'MNXC3')
* **reaction ID to optimise**\ : (string, default=rxn_target) reaction ID to optimise. This parameters is required in all simulation type
* **Constraint based simulation type**\ : (string, default=Fraction of Reaction) The type of constraint based modelling method. Valid options include: Fraction of Reaction, FBA, Parsimonious FBA.
* **Fraction of the optimum**\ : (float, default=0.75) Portion of the maximal flux used to set the maximal and minimal bounds for the source reaction of the "fraction" simulation type.

Advanced options:

* **Output the merged model?**\ : (boolean, default=False) output the full merged model instead of heterologous pathway only
* **Ignore Orphan Species?**\ : (boolean, default=True) ignore metabolites that are only consumed or produced
    ]]></help>
    <expand macro="creator"/>
    <citations>
        <citation type="doi">10.1186/1752-0509-7-74</citation>
        <citation type="doi">10.1515/jib-2016-290</citation>
        <citation type="doi">10.1038/s41467-022-32661-x</citation>
    </citations>
</tool>