<tool id="metaquantome_expand" name="metaQuantome: expand" version="@TOOL_VERSION@+galaxy@VERSION_SUFFIX@">
  <description>a set of functional or taxonomy annotations</description>
  <macros>
    <import>macros.xml</import>
    <xml name="FUNC_FILE">
      <param argument="--func_file" type="data" format="tabular" label="Functional file"
          help="Tabular file with a peptide sequence column and a functional assignment column with GO terms, EC number, or COG."/>
      <param argument="--pep_colname_func" type="text" label="Functional file: peptide column name" value="peptide"
          help="The column name within the function file that corresponds to the peptide sequences">
          <validator type="empty_field"/>
      </param>
    </xml>
    <xml name="FUNC_COLNAME">
      <param argument="--func_colname" type="text" label="Functional column name"
          help="The column name within the function file with the functional terms">
          <validator type="empty_field"/>
      </param>
    </xml>
    <xml name="TAX_FILE">
      <param argument="--tax_file" type="data" format="tabular" label="Taxonomy assignments file"/>
      <param argument="--pep_colname_tax" type="text" label="Taxonomy file: peptide column name" value="peptide"
          help="The column name within the taxonomy file that corresponds to the peptide sequences">
          <validator type="empty_field"/>
      </param>
    </xml>
    <xml name="TAX_COLNAME">
      <param argument="--tax_colname" type="text" label="Taxonomy column name">
          <help>
              Name of column in taxonomy annotation file that contains
              the lowest common ancestor (LCA) annotation. The annotations must
              be either NCBI taxids (strongly preferred) or taxonomy
              names.
          </help>
          <validator type="empty_field"/>
      </param>
    </xml>
    <xml name="FT_TAR_RANK">
      <param argument="--ft_tar_rank" type="select" label="rank at which to group taxonomy">
        <option value="species">species</option>
        <option value="genus" selected="true">genus</option>
        <option value="family">family</option>
        <option value="order">order</option>
        <option value="class">class</option>
        <option value="phylum">phylum</option>
        <option value="kingdom">kingdom</option>
      </param>
    </xml>
    <token name="@FUNC_FILE@">
      --func_file='$mode_args.func_file'
      --pep_colname_func='$mode_args.pep_colname_func'
    </token>
    <token name="@FUNC_COLNAME@">
      --func_colname='$mode_args.func_colname'
    </token>
    <token name="@ONTOLOGY@">
      --ontology='$mode_args.ontology_args.ontology'
      #if $mode_args.ontology_args.ontology == 'go'
          #if $mode_args.ontology_args.slim_down
              --slim_down
          #end if
      #end if
    </token>
    <token name="@TAX_FILE@">
      --tax_file='$mode_args.tax_file'
      --pep_colname_tax='$mode_args.pep_colname_tax'
    </token>
    <token name="@TAX_COLNAME@">
      --tax_colname='$mode_args.tax_colname'
    </token>
    <token name="@FT_TAR_RANK@">
      --ft_tar_rank='$mode_args.ft_tar_rank'
    </token>
  </macros>
  <expand macro="requirements" />
  <command detect_errors="exit_code"><![CDATA[
    tar -xf '$db_tar' &&
    metaquantome expand
    --data_dir ./data
    --samps '$samps'
    --mode '$mode_args.mode'
    --int_file='$int_file'
    --pep_colname_int='$pep_colname_int'
    #if $mode_args.mode == 'f'
      @FUNC_FILE@
      @FUNC_COLNAME@
      @ONTOLOGY@
    #elif $mode_args.mode =='t'
      @TAX_FILE@
      @TAX_COLNAME@
    #elif $mode_args.mode == 'ft'
      @FUNC_FILE@
      @FUNC_COLNAME@
      @ONTOLOGY@
      @TAX_FILE@
      @TAX_COLNAME@
      @FT_TAR_RANK@
    #end if
    --outfile='$outfile'
  ]]></command>
  <inputs>
    <param name="db_tar" type="data" format="tar" label="Database Archive File"
      help="must be created by 'metaQuantome: download'"/>
    <expand macro="SAMPS"/>
      <conditional name="mode_args">
        <param argument="--mode" type="select" label="Mode">
          <option value="f">Functional analysis</option>
          <option value="t">Taxonomic analysis</option>
          <option value="ft">Functional-taxonomic interaction analysis</option>
        </param>
        <when value="f">
          <expand macro="FUNC_FILE"/>
          <expand macro="ONTOLOGY_ARGS"/>
          <expand macro="FUNC_COLNAME"/>
        </when>
        <when value="t">
          <expand macro="TAX_FILE"/>
          <expand macro="TAX_COLNAME"/>
        </when>
        <when value="ft">
          <expand macro="FUNC_FILE"/>
          <expand macro="FUNC_COLNAME"/>
          <expand macro="ONTOLOGY_ARGS"/>
          <expand macro="TAX_FILE"/>
          <expand macro="TAX_COLNAME"/>
          <expand macro="FT_TAR_RANK"/>
        </when>
      </conditional>
      <param argument="--int_file" type="data" format="tabular" label="Intensity file"
        help=""/>
      <param argument="--pep_colname_int" type="text" value="peptide" label="Intensity file: peptide column name"
        help="The column name within the intensity file that corresponds to the peptide sequences">
        <validator type="empty_field"/>
      </param>
  </inputs>
  <outputs>
      <data format="tabular" name="outfile" label="${tool.name} on ${on_string} expanded"/>
  </outputs>
  <tests>
    <test>
       <param name="db_tar" value="ec.tar" ftype="tar"/>
       <param name="samps" value="samples_basic.tab" ftype="tabular"/>
       <param name="int_file" value="int_ttest.tab" ftype="tabular"/>
       <param name="pep_colname_int" value="peptide" />
       <param name="func_file" value="multiple_func.tab" />
       <param name="pep_colname_func" value="peptide" />
       <param name="func_colname" value="ec"/>
       <param name="mode" value="f" />
       <param name="ontology" value="ec" />
       <output name="outfile">
         <assert_contents>
           <has_text text="1.2.7.10"/>
         </assert_contents>
       </output>
    </test>
  </tests>
  <help>
<![CDATA[
metaQuantome expand
===================

The *expand* module is the first analysis step in the metaQuantome analysis workflow,
and can be run to analyze function, taxonomy, or function and taxonomy together.

To prepare to run this module, you must create your samples file with
"metaQuantome: create samples file" and download the necessary databases with
"metaQuantome: database".

Some example analysis workflows are:

1. Get the functional, taxonomic, or functional-taxonomic distribution: run expand, filter, and viz.
2. Cluster analysis: run expand, filter, and viz. The viz module has heatmaps and PCA plots for cluster analysis.
3. Differential expression: run expand, filter, stat, and viz.


The following information is required for all 3 analysis modes
(function, taxonomy, and function-taxonomy).

- experimental design information.
- a tab-separated peptide intensity file.
- the name of the peptide column in the intensity file.

Function mode
-------------

In function mode, the following information is required:

- the ontology being used: Gene Ontology (GO), Clusters of Orthologous Groups (COG), or Enzyme Commission (EC) numbers.
- a tab-separated functional annotation file, with a peptide column and a functional annotation column. An entry in the functional annotation column may contain multiple functional annotations separated by commas.
- the name of the peptide column in the functional annotation file.
- the name of the functional annotation column in the functional annotation file.

Taxonomy mode
-------------

In taxonomy mode, the following information is required:

- a tab-separated taxonomy annotation file, with a peptide column and a taxonomy annotation column. The taxonomic annotations should be the lowest common ancestor (LCA) for each peptide, preferably given as NCBI taxonomy IDs.
- the name of the peptide column in the taxonomic annotation file.
- the name of the taxonomy annotation column in the taxonomy annotation file.

Function-Taxonomy mode
----------------------

In the combined mode, all of the above must be provided. In addition, the "target rank" must be provided, which is the desired taxonomic rank at which to summarize the function/taxonomy results.

Output of the expand module
---------------------------

The structure of the output file depends on the analysis mode and the experimental design,
but the columns generally look like this, with one row for each term:

=======  =======================  =======================  ======================  =========================  ==========================
term id  info about term.         mean term intensity      term intensity          number of unique peptides  number of sample children
         (one or more columns)    (by sample group)        (by sample)             (by sample)                in each sample
=======  =======================  =======================  ======================  =========================  ==========================
term1    name, rank, etc.         note that this           this is the log2        integer. 0 is coded as NA  integer. 0 is coded as NA
                                  is the log2 of the mean  of term intensity
                                  intensity                in each sample.
                                                           Missing data is coded
                                                           as NA.
=======  =======================  =======================  ======================  =========================  ==========================

The next step in the metaQuantome workflow is "filter", which
filters out rows that don't meet certain conditions on the intensity,
the number of unique peptides annotated with each term, and the
number of sample children.

Questions, Comments, Problems, Kudos
------------------------------------

Please file any issues at https://github.com/galaxyproteomics/tools-galaxyp/issues.
]]></help>
  <expand macro="citations" />
</tool>