annotate rpfba.xml @ 0:fb5efc456dcc draft

"planemo upload commit 2f1af427fa4c4f2aad53ab94c4cdb51456c66019-dirty"

<tool id="rpFBA" name="FBA" version="5.9.2">
    <description>Perform FBA for the RetroPath2.0 heterologous pathways</description>
	<requirements>
        <requirement type="package" version="5.9.2">rptools</requirement>
    </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 '$input_sim_type.objective_rxn_id'
				--sim '$input_sim_type.sim_type'
            #if str($adv.ignore_orphan_species) == "true":
                --ignore_orphan_species
			#end if
				--log '$adv.log_level'
			#if str($input_sim_type.sim_type)=="fraction"
				--biomass_rxn_id '$input_sim_type.biomass_rxn_id'
				--fraction_of '$input_sim_type.fraction_of'
			#end if
			#if str($input_sim_type.sim_type)=="pfba"
				--biomass_rxn_id ''
				--fraction_of '$input_sim_type.fraction_of'
			#end if
			#if str($input_sim_type.sim_type)=="fba"
				--biomass_rxn_id ''
				--fraction_of 0.0
			#end if
    ]]></command>
    <inputs>
		<param name="pathway" type="data" format="xml" label="Pathway (rpSBML)" />
		<param name="model"   type="data" format="xml" label="Model (SBML)" />
        <param name="compartment_id" type="text" label="SBML compartment ID" value="MNXC3" />
        <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"       label="Fraction of the optimum" />
				<param name="objective_rxn_id"    type="text"  value="rxn_target" label="reaction ID to optimise" />
				<param name="biomass_rxn_id"    type="text"  value="biomass"    label="biomass reaction ID" />
			</when>
			<when value="pfba">
				<param name="fraction_of"        type="float" value="0.95"       label="Fraction of the optimum" />
				<param name="objective_rxn_id"    type="text"  value="rxn_target" label="reaction ID to optimise" />
			</when>
			<when value="fba">
				<param name="objective_rxn_id"    type="text"  value="rxn_target" label="reaction ID to optimise" />
			</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" />
			<param name="log_level"      type="select"  label="Log level">
                <option value="debug" >debug</option>
                <option value="info" >info</option>
			    <option value="warning" >warning</option>
			    <option value="error"   selected="true">error</option>
			    <option value="critical" >critical</option>
            </param>
		</section>
    </inputs>
    <outputs>
        <data name="pathway_with_fba" format="xml" label="${tool.name}(${input_sim_type.sim_type}) - ${pathway.name}" />
    </outputs>
    <tests>
        <test>
        <!-- test 1: check if identical outputs are produced with default parameters  -->
            <param name="pathway" value="rp_001_0001.xml" />
            <param name="model" value="e_coli_iML1515.sbml" />
            <output name="pathway_with_fba" file="rp_001_0001_with_fba.xml" ftype="xml" compare="diff" sort="true"/>
        </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_file**\ : (string) SBML file that contains an heterologous pathway
* **model_filel**\ : (string) Path to the GEM SBML model
* **compartment_id**\ : (string) Model compartment id (e.g. 'c' or 'MNXC3')
* **outfile**\ : (string) Path to the output file

Advanced options:


* **--sim**\ : (string, default=fraction) Valid options include: fraction, fba, pfba. The type of constraint based modelling method
* **--biomass_rxn_id**\ : (string, default=biomass) biomass reaction ID that will be restricted in the "fraction" simulation type. This parameter is ignored for "fba" and "pfba"
* **--objective_rxn_id**\ : (string, default=rxn_target) reaction ID to optimise. This parameters is required in all simulation type
* **--fraction_of**\ : (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
* **--merge**\ : (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
* **--log**: (string, default=error) Set the log level, choices are 'debug', 'info', 'warning', 'error', 'critical'


Project Links
---------------------

* `GitHub <https://github.com/brsynth/rptools/tree/master/rptools/rpfba>`_

Version
----------

5.9.2

Authors
-------

* **Melchior du Lac**
* **Joan Hérisson**

License
-------

`MIT <https://github.com/brsynth/rptools/blob/master/LICENSE>`_

Acknowledgments
---------------


* Thomas Duigou
    ]]></help>
    <citations>
        <citation type="bibtex">
@article{hucka2016sbml,
  title={SBML Level 3 package: Groups, Version 1 Release 1},
  author={Hucka, Michael and Smith, Lucian P},
  journal={Journal of integrative bioinformatics},
  volume={13},
  number={3},
  pages={8--29},
  year={2016},
  publisher={De Gruyter}
}
        </citation>
        <citation type="bibtex">
@article{ebrahim2013cobrapy,
  title={COBRApy: COnstraints-based reconstruction and analysis for python},
  author={Ebrahim, Ali and Lerman, Joshua A and Palsson, Bernhard O and Hyduke, Daniel R},
  journal={BMC systems biology},
  volume={7},
  number={1},
  pages={74},
  year={2013},
  publisher={Springer}
}
        </citation>
    </citations>
</tool>