<tool id="flowsom_cross_comp" name="Map individual FCS to reference SOM" version="1.0">
  <description>using FlowSOM.</description>
  <requirements>
    <requirement type="package" version="1.8.0">bioconductor-flowsom</requirement>
  </requirements>
  <stdio>
    <exit_code range="10" level="fatal" description="Please provide valid input files (FCS or flowFrame)." />
    <exit_code range="11" level="fatal" description="Please provide a valid reference SOM tree." />
    <exit_code range="12" level="fatal" description="Input files should all be in the same format." />
    <exit_code range="13" level="fatal" description="There are inconsistencies in marker names between FCS files." />
    <exit_code range="14" level="fatal" description="FCS file and reference tree markers are inconsistent." />
  </stdio>
  <command><![CDATA[
  Rscript $__tool_directory__/FlowSOMMApIndividualFCS.R '${reftree}' 'newDataOutput' '${cluster}' '${tablecontent}' '${mfi}' '${stats}' '${mfistats}' '${allstats}'
  #if $plot == "TRUE"
    'newDataTrees'
  #end if
  #if $mplot == "TRUE"
    'newDataMarkers'
  #end if
  #for $f in $input
    '${f}' '${f.name}'
  #end for
  ]]>
  </command>
  <inputs>
    <param format="fcs, flowframe" name="input" type="data_collection" collection_type="list" label="FCS files or flowFrames Collection"/>
    <param format="fsom" name="reftree" type="data" label="Reference SOM tree"/>
    <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>
    <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="plot" type="boolean" label="Plot SOM Tree?" checked="false" truevalue="TRUE" falsevalue="FALSE" />
    <param name="mplot" type="boolean" label="Plot individual marker trees?" checked="false" truevalue="TRUE" falsevalue="FALSE" />
    <param name="mfi" type="select" label="Calculate centroids using:">
      <option value="mfi" selected="true">Mean Fluorescence Intensity</option>
      <option value="mdfi">Median Fluorescence Intensity</option>
      <option value="gmfi">Geometric Mean Fluorescence Intensity</option>
    </param>
  </inputs>
  <outputs>
    <collection type="list" label="Mapping of ${input.name} to ${reftree.name}" name="output">
      <discover_datasets pattern="(?P&lt;name&gt;.*)" directory="newDataOutput" format="flowclr" />
    </collection>
    <data format="flowstat1" name="stats" label="${tablecontent} cluster distribution in ${input.name}"/>
    <data format="flowstat2" name="mfistats" label="${tablecontent} cluster ${mfi} centroids in ${input.name}"/>
    <data format="flowstat3" name="allstats" label="${tablecontent} cluster descriptive stats of ${input.name}"/>
    <collection type="list" label="Tree representations of mapping ${input.name} to ${reftree.name}" name="trees">
      <discover_datasets pattern="(?P&lt;name&gt;.*)" directory="newDataTrees" format="png" />
      <filter>(plot)</filter>
    </collection>
    <collection type="list" label="Marker trees from mapping ${input.name} to ${reftree.name}" name="mtrees">
      <discover_datasets pattern="(?P&lt;name&gt;.*)" directory="newDataMarkers" format="pdf" />
      <filter>(mplot)</filter>
    </collection>
  </outputs>
  <tests>
    <test>
      <param name="input">
        <collection type="list">
          <element name="input1.flowframe" value="input1.flowframe"/>
          <element name="input2.flowframe" value="input2.flowframe"/>
          <element name="input3.flowframe" value="input3.flowframe"/>
        </collection>
      </param>
      <param name="reftree" value="input.fsom"/>
      <param name="tablecontent" value="meta"/>
      <param name="cluster" value="10"/>
      <param name="plot" value="FALSE"/>
      <param name="mplot" value="FALSE"/>
      <param name="mfi" value="mfi"/>
      <output name="stats" file="out1.flowstat1"  compare="sim_size"/>
      <output name="mfistats" file="out1.flowstat2" compare="sim_size"/>
      <output name="allstats" file="out1.flowstat3" compare="sim_size"/>
      <output_collection name="output" type="list" count="3">
        <element name="input1.flowframe_clustered.flowclr" file="run1/input1.flowclr" compare="sim_size"/>
        <element name="input2.flowframe_clustered.flowclr" file="run1/input2.flowclr" compare="sim_size"/>
        <element name="input3.flowframe_clustered.flowclr" file="run1/input3.flowclr" compare="sim_size"/>
      </output_collection>
    </test>
    <test>
      <param name="input">
        <collection type="list">
          <element name="input1.fcs" value="input1.fcs"/>
          <element name="input2.fcs" value="input2.fcs"/>
          <element name="input3.fcs" value="input3.fcs"/>
        </collection>
      </param>
      <param name="reftree" value="input.fsom"/>
      <param name="tablecontent" value="FlowSOM"/>
      <param name="cluster" value="10"/>
      <param name="plot" value="TRUE"/>
      <param name="mplot" value="TRUE"/>
      <param name="mfi" value="mfi"/>
      <output name="stats" file="out2.flowstat1" compare="sim_size"/>
      <output name="mfistats" file="out2.flowstat2" compare="sim_size"/>
      <output name="allstats" file="out2.flowstat3" compare="sim_size"/>
      <output_collection name="output" type="list" count="3">
        <element name="input1.fcs_clustered.flowclr" file="run2/input1.flowclr" compare="sim_size"/>
        <element name="input2.fcs_clustered.flowclr" file="run2/input2.flowclr" compare="sim_size"/>
        <element name="input3.fcs_clustered.flowclr" file="run2/input3.flowclr" compare="sim_size"/>
      </output_collection>
      <output_collection name="trees" type="list" count="3">
        <element name="input1.fcs_tree.png" file="run2/input1.png" compare="sim_size"/>
        <element name="input2.fcs_tree.png" file="run2/input2.png" compare="sim_size"/>
        <element name="input3.fcs_tree.png" file="run2/input3.png" compare="sim_size"/>
      </output_collection>
      <output_collection name="mtrees" type="list" count="3">
        <element name="input1.fcs_marker_plots.pdf" file="run2/input1.pdf" compare="sim_size" delta="100000"/>
        <element name="input2.fcs_marker_plots.pdf" file="run2/input2.pdf" compare="sim_size" delta="100000"/>
        <element name="input3.fcs_marker_plots.pdf" file="run2/input3.pdf" compare="sim_size" delta="100000"/>
      </output_collection>
    </test>
  </tests>
  <help><![CDATA[
Map fcs samples to SOM
-------------------

   This tool uses FlowSOM to compare individual FCS or flowframes to a SOM reference tree.

**Input**

This tool compares FCS files or flowframes from a data collection to the reference Self-Organizing Map generated by a FlowSOM run. The same data collection merged and run with FlowSOM should ideally be used to ensure consistency in the attribution of events to clusters or meta-clusters.

.. class:: infomark

The option chosen for the centroids (mean, median or geometric mean) is used to generate descriptive statistics.

**Output**

Each individual FCS files or flowframe from the input collection is mapped to the reference tree, and a table mapping events to FlowSOM clusters or meta-clusters is generated for each. Two sets of plots can be optionally generated, one representing the resulting SOM Trees, and the other displaying each marker's contribution to the trees. The text files can be used as input for vizualisation tools. A table of the custer or meta-cluster composition of each file is generated as well as MFI and population descriptive statistics.

-----

**Example**

*Input*::

- FCS files or flowFrame (binary formats)
- FlowSOM tree (binary format)

*Output* for each text file - fluorescence intensities per marker and cluster ID per event::

   Marker1 Marker2 Marker3 ... Population
   33      47      11      ... 1
   31      64      11      ... 6
   21      62      99      ... 2
   14      34      60      ... 7
   ...     ...     ...     ... ...

*Summary table* - distribution of events in each population in each file::

   Filename SampleName Pop1 Pop2 Pop3 ...
   File1    Biosample1 0.1  0.25 0.14 ...
   File2    Biosample2 0.02 0.1  0.17 ...
   File3    Biosample3 0.4  0.05 0.21 ...
   File4    Biosample4 0.05 0.3  0.08 ...
   ...      ...        ...  ...  ...  ...

*Cluster MFI Summary table* - for each file, mean, median or geometric mean fluorescence intensities per marker per population::

   Marker1 Marker2 Marker3 ... Population Percentage SampleName
   154     885     24      ... 1          0.2        Biosample1
   458     74      574     ... 2          0.3        Biosample1
   3       210     86      ... 3          0.05       Biosample1
   140     921     19      ... 1          0.1        Biosample2
   428     79      508     ... 2          0.25       Biosample2
   9       225     90      ... 3          0.3        Biosample2
   ...     ...     ...     ... ...        ...        ...

*Cluster MFI Descriptive Statistics table* - for the set of files, mean, median and standard deviation of each centroid per marker per population, as well as mean, median and standard deviation of the population's proportion::

   Population Marker1_mean Marker1_median Marker1_stdev ... Percentage_mean Percentage_median Percentage_stdev
   1          94.65        90.86          25.8          ... 1.84            0.55              2.48
   2          132.18       131.58         5.02          ... 9.89            9.76              0.33
   3          71.8         69.68          10.53         ... 3.02            1.49              3.45
   4          84.85        84.85          nan           ... 8.52            8.52              nan
   5          161.82       132.77         61.29         ... 0.95            0.37              1.06
   ...        ...          ...            ...           ... ...             ...               ...

*FlowSOM tree*:

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

*Marker plots*:

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