<tool id="flowsom_tree" name="Generate a reference Self Organizing Map" version="1.0+galaxy2" profile="18.01">
  <description>using FlowSOM.</description>
  <requirements>
    <requirement type="package" version="1.18.0">bioconductor-flowsom</requirement>
    <requirement type="package" version="0.0.1">mscorefonts</requirement>
  </requirements>
  <stdio>
    <exit_code range="1:9" level="fatal" description="See stderr for more details." />
    <exit_code range="10" level="fatal" description="Please provide a valid input (FCS or flowFrame)." />
    <exit_code range="11" level="fatal" description="Please provide integers for columns you want to analyze, in a comma separated list." />
    <exit_code range="12" level="fatal" description="Provided indices are out of range in the FCS file / flowframe given as input." />
    <exit_code range="13" level="fatal" description="Please provide integers for the number of expected clusters." />
    <exit_code range="14" level="fatal" description="Please provide integers for the grid size." />
    <exit_code range="15" level="fatal" description="Please provide an integer to set the seed." />
    <exit_code range="16:" level="fatal" description="See stderr for more details." />
  </stdio>
  <command><![CDATA[
      Rscript $__tool_directory__/FlowSOMGenerateTree.R '${input}' '${output}' '${cols}' '${cluster}' '${xdim}' '${ydim}' '${seed}'
      #if $plotoutput.plot == "TRUE"
        '${treeplot}' '${plotoutput.plotformat}' '${plotoutput.nodesize}'
      #end if
      #if $mplot == "TRUE"
        '${mrkrplot}'
      #end if
      #if $txtoutput.table == "TRUE"
        '${txtoutput.tablecontent}' '${txttable}' '${mappingtable}' 'mm' 'mm'
      #end if
  ]]>
  </command>
  <inputs>
    <param format="fcs, flowframe" name="input" type="data" label="FCS file or flowFrame" />
    <param name="cols" type="text" value="i.e.:1,2,5" label="Columns to use for analysis" help="By default, all markers except for FSC and SSC will be taken into account." />
    <param name="cluster" type="integer" value="10" optional="true" label="Number of expected metaclusters" help="By default, the number of expected metaclusters is set to 10" />
    <param name="xdim" type="integer" value="10" label="Grid size, width"/>
    <param name="ydim" type="integer" value="10" label="Grid size, height"  help="By default, the grid size is 10x10. The grid size specifies the number of clusters." />
    <param name="seed" type="integer" value="42" label="Seed"  help="Let's be geeks, default is set to 42." />
    <conditional name="txtoutput">
      <param name="table" type="boolean" label="Output text?" checked="false" truevalue="TRUE" falsevalue="FALSE" />
      <when value="TRUE">
        <param name="tablecontent" type="select" label="Associate each event to SOM clusters or meta-clusters?">
          <option value="FlowSOM">FlowSOM Clusters</option>
          <option value="meta">Meta-Clusters</option>
        </param>
      </when>
    </conditional>
    <conditional name="plotoutput">
      <param name="plot" type="boolean" label="Plot SOM Tree?" checked="false" truevalue="TRUE" falsevalue="FALSE" />
      <when value="TRUE">
        <param name="nodesize" type="boolean" label="Make all nodes the same size?" checked="false" truevalue="TRUE" falsevalue="FALSE" />
        <param name="plotformat" type="select" label="Graph output Format">
          <option value="PNG">PNG</option>
          <option value="PDF">PDF</option>
        </param>
      </when>
    </conditional>
    <param name="mplot" type="boolean" label="Plot individual marker trees?" checked="false" truevalue="TRUE" falsevalue="FALSE" />
  </inputs>
  <outputs>
    <data format="fsom" name="output" label="FlowSOM tree from ${input.name}">
    </data>
    <data format="flowclr" name="txttable" label="FlowSOM tree on ${input.name} with ${txtoutput.tablecontent} clusters">
      <filter>txtoutput['table']</filter>
    </data>
    <data format="tabular" name="mappingtable" label="Mapping of nodes to meta-clusters from FlowSOM tree on ${input.name}">
      <filter>txtoutput['table']</filter>
    </data>
    <data format="png" name="treeplot" label="Representation of FlowSOM tree on ${input.name} in ${plotoutput.plotformat}">
      <filter>plotoutput['plot']</filter>
      <change_format>
        <when input="plotoutput.plotformat" value="PDF" format="pdf" />
      </change_format>
    </data>
    <data format="pdf" name="mrkrplot" label="Marker trees from FlowSOM on ${input.name}">
      <filter>(mplot)</filter>
    </data>
  </outputs>
  <tests>
    <test>
      <param name="input" value="input.fcs"/>
      <param name="cols" value="3,4,5"/>
      <param name="cluster" value="10"/>
      <param name="xdim" value="10"/>
      <param name="ydim" value="10"/>
      <param name="seed" value="33"/>
      <param name="plot" value="FALSE"/>
      <param name="table" value="FALSE" />
      <param name="mplot" value="FALSE"/>
      <output name="output" file="output1.fsom" compare="sim_size"/>
    </test>
    <test>
      <param name="input" value="input.flowframe"/>
      <param name="cols" value="3,4,5"/>
      <param name="cluster" value="15"/>
      <param name="xdim" value="10"/>
      <param name="ydim" value="10"/>
      <param name="seed" value="33"/>
      <param name="plot" value="TRUE"/>
      <param name="nodesize" value="FALSE"/>
      <param name="mplot" value="FALSE"/>
      <param name="plotformat" value="PNG"/>
      <param name="table" value="FALSE" />
      <output name="output" file="output2.fsom" compare="sim_size"/>
      <output name="treeplot" file="tree.png" compare="sim_size"/>
    </test>
    <test>
      <param name="input" value="input.fcs"/>
      <param name="cols" value="3,4,5"/>
      <param name="cluster" value="15"/>
      <param name="xdim" value="10"/>
      <param name="ydim" value="10"/>
      <param name="seed" value="33"/>
      <param name="plot" value="TRUE"/>
      <param name="nodesize" value="FALSE"/>
      <param name="mplot" value="TRUE"/>
      <param name="plotformat" value="PDF"/>
      <param name="table" value="FALSE" />
      <output name="output" file="output3.fsom" compare="sim_size"/>
      <output name="treeplot" file="tree.pdf" compare="sim_size" delta="100000"/>
      <output name="mrkrplot" file="mrkrplot.pdf" compare="sim_size" delta="100000"/>
    </test>
    <test>
      <param name="input" value="input.fcs"/>
      <param name="cols" value="3,4,5"/>
      <param name="cluster" value="10"/>
      <param name="xdim" value="7"/>
      <param name="ydim" value="7"/>
      <param name="seed" value="33"/>
      <param name="plot" value="FALSE"/>
      <param name="mplot" value="FALSE"/>
      <param name="table" value="TRUE" />
      <param name="tablecontent" value="FlowSOM" />
      <output name="output" file="output4.fsom" compare="sim_size"/>
      <output name="txttable" file="output5.flowclr" compare="sim_size"/>
      <output name="mappingtable" file="mapping1.tabular" compare="sim_size"/>
    </test>
    <test>
      <param name="input" value="input.fcs"/>
      <param name="cols" value="3,4,5"/>
      <param name="cluster" value="10"/>
      <param name="xdim" value="7"/>
      <param name="ydim" value="7"/>
      <param name="seed" value="33"/>
      <param name="plot" value="FALSE"/>
      <param name="mplot" value="FALSE"/>
      <param name="table" value="TRUE" />
      <param name="tablecontent" value="meta" />
      <output name="output" file="output6.fsom" compare="sim_size"/>
      <output name="txttable" file="output7.flowclr" compare="sim_size"/>
      <output name="mappingtable" file="mapping2.tabular" compare="sim_size"/>
    </test>
  </tests>
  <help><![CDATA[
Generate reference SOM
-----

This tool generates a reference Self-Organizing Map using FlowSOM.

**Input files**

This tool require a valid FCS file or flowFrame as input.

.. class:: warningmark

Compensation and Transformation will NOT be applied with this tool.

**Parameters**

*Columns to use*

Please indicate the indices of the markers to use in the computation of the SOM in a comma-separated list.

.. class:: infomark

Tip: One of the tools in the FCS File Tools section can help check the markers and channels indices:

- Get list of markers and channels in FCS files.

*Number of meta-clusters*

Please indicate the exact number of meta-clusters expected.

*Grid dimension*

Please indicate the dimension of the grid for establishing the SOM. The dimension of the grid defines the number of clusters (height x width = cluster)

*Seed*

Please indicate a random number to use as seed. To make your analysis reproducible, use the same seed.

**Output files**

This tool produces a FlowSOM object and optionally two sets of plots, one representing the SOM Tree generated, and the other displaying each marker's contribution to the tree. A flat text file can also optionally be generated and used as input for vizualisation tools.

.. class:: warningmark

PDF are larger files that may take some time to load. It might be faster to download the PDF output once generated to open it locally.

-----

**Example**

*Output text file*::

   Marker1 Marker2 Marker3 ... Population
   34      45      12      ... 1
   33      65      10      ... 5
   19      62      98      ... 2
   12      36      58      ... 1
   ...     ...     ...     ... ...

*Node/Meta-cluster mapping file*::

   Node Meta-Cluster
   1    10
   2    9
   3    1
   4    9
   ...  ...

*FlowSOM tree*:

.. image :: .static/images/flowtools/FlowSOM_tree.png

*Marker plots*:

.. image:: .static/images/flowtools/flowSOM_marker.png
  ]]>
  </help>
  <citations>
    <citation type="doi">10.1002/cyto.a.22625</citation>
  </citations>
</tool>