annotate COBRAxy/src/ras_to_bounds.xml @ 550:4cf00f21f609 draft default tip

Uploaded

<tool id="MaREA RAS to bounds" name="RAS2Bounds" version="2.0.0">
    
    <macros>
        <import>marea_macros.xml</import>
    </macros>

	<requirements>
        <requirement type="package" version="1.24.4">numpy</requirement>
        <requirement type="package" version="2.0.3">pandas</requirement>
		<requirement type="package" version="0.29.0">cobra</requirement>
        <requirement type="package" version="5.2.2">lxml</requirement>
        <requirement type="package" version="1.4.2">joblib</requirement>
	</requirements>

    <command detect_errors="exit_code">
        <![CDATA[
      	python $__tool_directory__/ras_to_bounds.py
        --tool_dir $__tool_directory__
        --cell_class $cell_class
        --model_upload $model_upload
        #set $names = ""
        --input_ras "${",".join(map(str, $input_ras))}"
        #for $input_temp in $input_ras:
            #set $names = $names + $input_temp.element_identifier + ","
        #end for

        --save_models $save_models
        --save_models_path saved_models/
        --name "$names"
        --out_log $log
        ]]>
    </command>
    <inputs>

        <param name="model_upload" argument="--model_upload" type="data" format="csv,tsv,tabular" multiple="false"
                label="Model tabular:" help="Upload a CSV/TSV file containing information generated by the Import Metabolic Model tool." />

        <param name="input_ras" argument="--input_ras" multiple="true" type="data" format="tabular, csv, tsv" label="RAS matrix:" />


        <param name="save_models" argument="--save_models" type="select" label="Save models with applied bounds?">
            <option value="False" selected="true">No</option>
            <option value="True">Yes</option>
        </param>

    </inputs>

    <outputs>
        <data format="txt" name="log" label="RAStoBounds- Log" />
        <data format="tabular" name="cell_class" label="RAStoBounds - Cells class" />
        <collection name="ras_to_bounds" type="list" label="Ras to Bounds">
            <discover_datasets name = "collection" pattern="__name_and_ext__" directory="ras_to_bounds"/>
        </collection>
        <collection name="saved_models" type="list" label="Saved Models (Tabular Format)">
            <filter>save_models == "True"</filter>
            <discover_datasets name = "saved_models_collection" pattern="__name_and_ext__" directory="saved_models"/>
        </collection>
    </outputs>

    <help>

    <![CDATA[

Overview
-------------

This tool computes reaction bounds for a tabular metabolic model, combining information from:
 - A tabular model generated by the Import Metabolic Model tool, and
 - One or more Reaction Activity Score (RAS) matrices produced by the RAS Generator tool (Expression2RAS).


Input:
-------------

The tool has two types of input files:	
    - Metabolic model: a tab-separated file containing the structure of the metabolic model (reactions, metabolites, etc.).
    - RAS matrix: tab-separated files containing the reaction activity scores.

If "Save models with applied bounds?" is set to TRUE, it is possible to save a collection of models, one for each sample and with its specific constraints

You can upload multiple RAS files (e.g. one for normal cells and one for cancer cells).
When multiple RAS matrices are provided, the computed bounds are normalized across all samples in the dataset. This option is highly recommended to make model simulation outcomes comparable.


Output:
-------------

The tool generates three outputs:
    - Collection of tabular files: one per sample, containing the lower and upper bounds for all reactions.
    - Classes: a file listing the class assigned to each sample. The class name of a RAS matrix corresponds to its file name. Format: tab-separated.
    - a log file (.txt).

The lower and upper bounds are calculated, as described in Di Filippo et al. (2020), using the RAS values and the Flux Variability Analysis (FVA) results. These bounds are then used as inputs for flux simulation tools.

If a reaction i has a RAS value R_i, its upper bound is computed as R_i * UB, where UB is the maximum flux value obtained from the FVA analysis for that reaction.
Similarly, the lower bound is computed as R_i * LB, where LB is the minimum flux value obtained from the FVA analysis.

RAS values are normalized across all samples between 0 and 1.

If multiple RAS matrices are uploaded, the normalization is performed across all cells in the dataset to ensure consistent scaling.

Example for multiple RAS matrices:
- Input files: cancer.csv and normal.csv, generated by the RAS Generator tool (the corresponding class names are "cancer" and "normal").
- The tool produces one unified collection of bounds files for both cancer and normal cells, with normalization applied across all cells.
- The mapping between samples and their corresponding classes is provided in the "cell_class" file, which can be used for downstream flux enrichment analysis based on class grouping.

Example

Assume the tabular model includes a reaction named "R_GLCt1r" (glucose transport) and the FVA determined its flux range as:
- Lower bound (LB) = 0
- Upper bound (UB) = 20

If the RAS values are:
- RAS_normal = 0.5
- RAS_cancer = 0.9

Then the calculated bounds are:
- For normal cells: lower bound = 0.5 * 0 = 0; upper bound = 0.5 * 20 = 10
- For cancer cells: lower bound = 0.9 * 0 = 0; upper bound = 0.9 * 20 = 18

    ]]>
    </help>
    <expand macro="citations" />

</tool>