<tool id="gen_flow_overview" name="Generate overview information" version="1.0">
  <description>of FLOCK flow analysis</description>
  <requirements>
    <requirement type="package" version="1.5.0">matplotlib</requirement>
    <requirement type="package" version="1.10.2">numpy</requirement>
    <requirement type="package" version="0.16.0">scipy</requirement>
    <requirement type="package" version="0.17.1">pandas</requirement>
    <requirement type="package" version="2.8">jinja2</requirement>
    <requirement type="package" version="3.3.0">r</requirement>
    <requirement type="package" version="1.11.2">bioconductor-flowcl</requirement>
  </requirements>
  <stdio>
    <exit_code range="2" level="fatal" description="There was a problem running flowCL. You might want to check your marker names - See stderr for more details." />
    <exit_code range="3:" level="fatal" description="See stderr for more details." />
  </stdio>
  <command><![CDATA[
   #if $ontology.runcl == "no"
    python $__tool_directory__/genFlowOverview.py -i "${input}" -o "${html_file}" -M "${mfi}" -d "${html_file.files_path}" -t $__tool_directory__
   #else
    python $__tool_directory__/genFlowOverview.py -i "${input}" -o "${html_file}" -M "${mfi}" -d "${html_file.files_path}" -t $__tool_directory__ -p "${scores}"
   #end if
  ]]>
  </command>
  <inputs>
    <param format="flowclr" name="input" type="data" label="Flow Result File"/>
    <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>
    <conditional name="ontology">
      <param name="runcl" type="select" label="Associate FLOCK population score profiles with Cell Ontology?" help="using FlowCL">
        <option value="no">No, thank you</option>
        <option value="yes">Yes, pretty please, even though it will take 10 more minutes to run</option>
      </param>
      <when value="yes">
        <param format="flowscore" name="scores" type="data" label="Population score profiles from FLOCK"/>
      </when>
    </conditional>
  </inputs>
  <outputs>
    <data format="html" name="html_file" label="Overview of ${input.name}">
    </data>
  </outputs>
  <tests>
    <test>
      <param name="input" value="input.flowclr"/>
      <param name="mfi" value="mfi"/>
      <param name="runcl" value="no"/>
      <output name="output_file" file="out1/out.html">
        <extra_files type="file" name="flow.mfi" value="out1/flow.mfi"/>
        <extra_files type="file" name="flow.mfi_pop" value="out1/flow.mfi_pop"/>
        <extra_files type="file" name="flow.overview" value="out1/flow.overview"/>
        <extra_files type="file" name="flow.sample" value="out1/flow.sample"/>
        <extra_files type="file" name="boxplot.json" value="out1/boxplotData.json"/>
        <extra_files type="file" name="m0_m0_90X90.png" value="out1/m0_m0_90X90.png" compare="contains"/>
        <extra_files type="file" name="m0_m1_90X90.png" value="out1/m0_m1_90X90.png" compare="contains"/>
        <extra_files type="file" name="m1_m0_90X90.png" value="out1/m1_m0_90X90.png" compare="contains"/>
        <extra_files type="file" name="m1_m1_90X90.png" value="out1/m1_m1_90X90.png" compare="contains"/>
      </output>
    </test>
    <test>
      <param name="input" value="input.flowclr"/>
      <param name="mfi" value="mfi"/>
      <param name="runcl" value="yes"/>
      <param name="scores" value="profile.flowscore"/>
      <output name="output_file" file="out2/out.html">
        <extra_files type="file" name="boxplot.json" value="out2/boxplotData.json"/>
        <extra_files type="file" name="CLprofiles.txt" value="out2/CLprofiles.txt"/>
        <extra_files type="file" name="flow.mfi" value="out2/flow.mfi"/>
        <extra_files type="file" name="flow.mfi_pop" value="out2/flow.mfi_pop"/>
        <extra_files type="file" name="flow.overview" value="out2/flow.overview"/>
        <extra_files type="file" name="flow.sample" value="out2/flow.sample"/>
        <extra_files type="file" name="m0_m0_90X90.png" value="out2/m0_m0_90X90.png" compare="contains"/>
        <extra_files type="file" name="m0_m1_90X90.png" value="out2/m0_m1_90X90.png" compare="contains"/>
        <extra_files type="file" name="m1_m0_90X90.png" value="out2/m1_m0_90X90.png" compare="contains"/>
        <extra_files type="file" name="m1_m1_90X90.png" value="out2/m1_m1_90X90.png" compare="contains"/>
        <extra_files type="file" name="scores.txt" value="out2/scores.txt"/>
        <extra_files type="file" name="flowcl_pop01.pdf" value="out2/flowcl_pop01.pdf" compare="contains"/>
        <extra_files type="file" name="flowcl_pop01.txt" value="out2/flowcl_pop01.txt"/>
        <extra_files type="file" name="flowcl_pop04.pdf" value="out2/flowcl_pop04.pdf" compare="contains"/>
        <extra_files type="file" name="flowcl_pop04.txt" value="out2/flowcl_pop04.txt"/>
        <extra_files type="file" name="flowcl_pop07.pdf" value="out2/flowcl_pop07.pdf" compare="contains"/>
        <extra_files type="file" name="flowcl_pop07.txt" value="out2/flowcl_pop07.txt"/>
        <extra_files type="file" name="flowcl_pop13.pdf" value="out2/flowcl_pop13.pdf" compare="contains"/>
        <extra_files type="file" name="flowcl_pop13.txt" value="out2/flowcl_pop13.txt"/>
        <extra_files type="file" name="flowcl_pop14.pdf" value="out2/flowcl_pop14.pdf" compare="contains"/>
        <extra_files type="file" name="flowcl_pop14.txt" value="out2/flowcl_pop14.txt"/>
        <extra_files type="file" name="flowcl_pop15.pdf" value="out2/flowcl_pop15.pdf" compare="contains"/>
        <extra_files type="file" name="flowcl_pop15.txt" value="out2/flowcl_pop15.txt"/>
        <extra_files type="file" name="flowcl_pop19.pdf" value="out2/flowcl_pop19.pdf" compare="contains"/>
        <extra_files type="file" name="flowcl_pop19.txt" value="out2/flowcl_pop19.txt"/>
        <extra_files type="file" name="flowcl_pop20.pdf" value="out2/flowcl_pop20.pdf" compare="contains"/>
        <extra_files type="file" name="flowcl_pop20.txt" value="out2/flowcl_pop20.txt"/>
        <extra_files type="file" name="flowcl_pop23.pdf" value="out2/flowcl_pop23.pdf" compare="contains"/>
        <extra_files type="file" name="flowcl_pop23.txt" value="out2/flowcl_pop23.txt"/>
      </output>
    </test>
  </tests>
  <help><![CDATA[
   This tool generates an overview of the flow analysis results.

-----

**Input**

Tool input is a tab-separated file containing markers fluorescence intensities for each event as well as population and is generated as part of FLOCK or CrossSample output.  If the option is selected, flowCL is used to associate populations defined by FLOCK to a Cell Ontology term.

.. class:: infomark

Tip: Marker names need to be in the Cell Ontology for flowCL to run.

**Output**

The output is a page with multiple tabs that allows visualization of the data.

.. class: warningmark

The FLOCK output is proportionally downsampled to 20K events for the visualization.

.. class:: warningmark

*The output of this tool is interactive. However, comments or any other modifications made are not saved when exiting the view.*

-----

**Example**

*Input* - fluorescence intensities per marker and population ID per event::

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

*Output*

Summary of the data:

The comment field of this table is editable, and can be used to name the populations. The edited values are used to populate the legends of the other graphs. The columns are re-orderable. The 'col visibility' button allows to choose which columns to display. 'CSV', 'PDF' and 'Copy' respectively allow to download a comma-separated values file, a pdf version or to copy to your clipboard in a tab-separated format the current view of the table.

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

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


Scatterplots overview:

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


2D Scatterplot:

The user can choose which populations and markers to display. The Plotly toolbar allows more control over the display of the graph. There is an option to save the plot as a png file.

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


3D Scatterplot:

The user can choose which populations and markers to display. The Plotly toolbar allows more control over the display of the graph. There is an option to save the plot as a png file.

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


Parallel Coordinates:

The user can reorder the markers, and choose which populations to display either by selecting them in the legends via checkboxes or by selecting them on the graph. Data selected for display is shown in the table below the graph. Mousing over a line in that table highlights the corresponding line on the graph. The 'col visibility' button allows to choose which columns to display. 'CSV', 'PDF' and 'Copy' respectively allow to download a comma-separated values file, a pdf version or to copy to your clipboard in a tab-separated format the current view of the table.

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


Summary Statistics Boxplots:

The user can choose whether to group the boxplots per marker or per population. By default, the values displayed are the 25th, median and 75th percentiles. The whiskers represent 1.5 times the interquartile range. The MFI or the values can be displayed by checking the corresponding checkboxes. The number of markers that can be plotted simultaneously is limited to 5. The number of outliers per data point is limited to 100. If there are more than 100 outliers, they are downsampled randomly to a 100 and a warning message is displayed.

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


If the ontology option was selected, the following tab is displayed.
The CL terms hyperlink to their representation in the Immport Cell Ontology browser. The full flowCL run summary is accessible by clicking on the phenotype.

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

  ]]>
  </help>
  <citations>
    <citation type="doi">10.1093/bioinformatics/btu807</citation>
  </citations>
</tool>