<tool id="flowAI" name="flowAI" version="1.0+galaxy2">
  <description> automatic quality control</description>
  <requirements>
    <requirement type="package" version="1.42.0">bioconductor-flowcore</requirement>
    <requirement type="package" version="1.2.9">bioconductor-flowai</requirement>
    <requirement type="package" version="0.0.1">mscorefonts</requirement>
  </requirements>
  <stdio>
    <exit_code range="1:" level="fatal" description="See stderr for more details."/>
  </stdio>
  <command><![CDATA[
      Rscript $__tool_directory__/FCSflowAI.R '${input}' '${remove}' $alphaFR $chremFS $outFS $penFS '${sideFM}' report.html high.fcs low.fcs qc.fcs &&
      cp report.html $full_rep
      #if $highQ_FCS:
        && cp high.fcs $highfcs
      #end if
      #if $lowQ_FCS:
        && cp low.fcs $lowfcs
      #end if
      #if $QC_FCS:
        && cp qc.fcs $qcfcs
      #end if
  ]]>
  </command>
  <inputs>
    <param format="fcs" name="input" type="data" label="FCS file"/>
    <param name="remove" type="select" label="Remove low quality cells from:">
      <option value="all">Flow rate, Signal acquisition and Dynamic range</option>
      <option value="FR_FS">Flow rate and Signal acquisition</option>
      <option value="FR_FM">Flow rate and Dynamic range</option>
      <option value="FS_FM">Signal acquisition and Dynamic range</option>
      <option value="FR">Flow rate</option>
      <option value="FS">Signal acquisition</option>
      <option value="FM">Dynamic range</option>
    </param>
    <param name="alphaFR" type="float" label="Significance threshold for flow rate check:" value="0.01"/>
    <param name="chremFS" type="boolean" checked="true" truevalue="TRUE" falsevalue="FALSE" label="Do you want to exclude the FSC and SSC parameters from the signal acquisition check?" help="The FSC and SSC parameters will not be taken into account for analysis but will not be removed."/>
    <param name="outFS" type="boolean" checked="false" truevalue="TRUE" falsevalue="FALSE" label="Do you want to remove outliers before the signal acquisition check?"/>
    <param name="penFS" type="integer" label="Stringency of signal acquisition check (higher tolerance with higher values):" value="200"/>
    <param name="sideFM" type="select" label="Include in dynamic range check:">
      <option value="both">Both limits</option>
      <option value="upper">Upper limit only</option>
      <option value="lower">Lower limit only</option>
    </param>
    <param name="highQ_FCS" type="boolean" checked="true" truevalue="TRUE" falsevalue="FALSE" label="Create FCS file with only high quality events?"/>
    <param name="lowQ_FCS" type="boolean" checked="false" truevalue="TRUE" falsevalue="FALSE" label="Create FCS file with only low quality events?"/>
    <param name="QC_FCS" type="boolean" checked="false" truevalue="TRUE" falsevalue="FALSE" label="Create FCS file with an additional parameter where low quality events have values higher than 10,000?"/>
  </inputs>
  <outputs>
    <data format="html" name="full_rep" label="QC of ${input.name}">
    </data>
    <data format="fcs" name="highfcs" label="High quality events only from ${input.name}">
      <filter>(highQ_FCS)</filter>
    </data>
    <data format="fcs" name="lowfcs" label="Low quality events only from ${input.name}">
      <filter>(lowQ_FCS)</filter>
    </data>
    <data format="fcs" name="qcfcs" label="All events (low quality event marked up) from ${input.name}">
      <filter>(QC_FCS)</filter>
    </data>
  </outputs>
  <tests>
    <test expect_num_outputs="2">
      <param name="input" value="input.fcs"/>
      <param name="remove" value="all"/>
      <param name="alphaFR" value="0.01"/>
      <param name="chremFS" value="TRUE"/>
      <param name="outFS" value="FALSE"/>
      <param name="penFS" value="200"/>
      <param name="sideFM" value="both"/>
      <param name="highQ_FCS" value="TRUE"/>
      <param name="lowQ_FCS" value="FALSE"/>
      <param name="QC_FCS" value="FALSE"/>
      <output name="full_rep">
        <assert_contents>
          <has_n_lines min="100" max="500"/>
          <has_text text="data:image/png;base64"/>
          <has_text text="Dynamic range check"/>
          <has_text text="total_UNIQUE"/>
          <has_size value="320266" delta="30000"/>
        </assert_contents>
      </output>
      <output name="highfcs" file="std/hqdata.fcs" compare="sim_size"/>
    </test>
    <test expect_num_outputs="4">
      <param name="input" value="input.fcs"/>
      <param name="remove" value="all"/>
      <param name="alphaFR" value="0.01"/>
      <param name="chremFS" value="TRUE"/>
      <param name="outFS" value="FALSE"/>
      <param name="penFS" value="200"/>
      <param name="sideFM" value="both"/>
      <param name="highQ_FCS" value="TRUE"/>
      <param name="lowQ_FCS" value="TRUE"/>
      <param name="QC_FCS" value="TRUE"/>
      <output name="full_rep">
        <assert_contents>
          <has_n_lines min="100" max="500"/>
          <has_text text="data:image/png;base64"/>
          <has_text text="Dynamic range check"/>
          <has_text text="total_UNIQUE"/>
          <has_size value="320266" delta="30000"/>
        </assert_contents>
      </output>
      <output name="highfcs" file="std/hqdata.fcs" compare="sim_size"/>
      <output name="lowfcs" file="std/lqdata.fcs" compare="sim_size"/>
      <output name="qcfcs" file="std/alldata.fcs" compare="sim_size"/>
    </test>
    <test expect_num_outputs="2">
      <param name="input" value="input.fcs"/>
      <param name="remove" value="all"/>
      <param name="alphaFR" value="0.01"/>
      <param name="chremFS" value="TRUE"/>
      <param name="outFS" value="TRUE"/>
      <param name="penFS" value="200"/>
      <param name="sideFM" value="both"/>
      <param name="highQ_FCS" value="TRUE"/>
      <param name="lowQ_FCS" value="FALSE"/>
      <param name="QC_FCS" value="FALSE"/>
      <output name="full_rep">
        <assert_contents>
          <has_n_lines min="100" max="500"/>
          <has_text text="data:image/png;base64"/>
          <has_text text="Dynamic range check"/>
          <has_size value="320433" delta="30000"/>
        </assert_contents>
      </output>
      <output name="highfcs" file="nooutliers/hqdata_nooutliers.fcs" compare="sim_size"/>
    </test>
    <test expect_num_outputs="2">
      <param name="input" value="input.fcs"/>
      <param name="remove" value="all"/>
      <param name="alphaFR" value="0.01"/>
      <param name="chremFS" value="FALSE"/>
      <param name="outFS" value="FALSE"/>
      <param name="penFS" value="200"/>
      <param name="sideFM" value="both"/>
      <param name="highQ_FCS" value="TRUE"/>
      <param name="lowQ_FCS" value="FALSE"/>
      <param name="QC_FCS" value="FALSE"/>
      <output name="full_rep">
        <assert_contents>
          <has_n_lines min="100" max="500"/>
          <has_text text="data:image/png;base64"/>
          <has_text text="Dynamic range check"/>
          <has_text text="total_UNIQUE"/>
          <has_size value="320220" delta="30000"/>
        </assert_contents>
      </output>
      <output name="highfcs" file="withsfsc/hqdata_sfsc.fcs" compare="sim_size"/>
    </test>
  </tests>
  <help><![CDATA[
   This tool automatically performs quality control of flow cytometry data.

-----

**Input files**

  • One or more FCS files.

**Output files**

  • full HTML report
  • new FCS file containing only high quality events (default)
  • new FCS file containing only low quality events (optional)
  • original FCS file containing an additional parameter where the low quality events have a value higher than 10,000 (optional)


The files generated will be FCS 3.0.

----

Description of the approach
'''''''''''''''''''''''''''
This tool identifies anomalies from three fundamental properties of flow cytometry data:

  - *Flow rate*. Surges and substantial shifts of the rate of the cells passing through the capillary tube are detected.

  - *Signal acquisition*. Instability in the signal acquired for each channel are detected. In most cases it corresponds to flow rate surges and shifts.

  - *Dynamic range*. Values recorded in the upper limit (margin events) and negative outliers are removed.

.. class:: infomark

An HTML report with informative plots is generated. Users are advised to review the report and also::

  1. Eventually adjust the quality control parameters
  2. Discard the entire FCS file because of an unacceptable number of anomalies
  3. Program a flow cytometry maintenance because of recurrent issues


Parameters
''''''''''
Default settings work well in the majority of cases. Setting customization may be needed to address properties of unique datasets. For example, high-dimensional FCS files may perform best with more tolerant setttings for signal acquisition checks.

Example
'''''''
This section provides an example of a flowAI quality control html report with plots:


Flow rate check: anomalies are flagged with a green circle. In this instance a surge was detected and discarded as well as a shift from the median value later in the experiment.

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

Signal acquistion check: Orange background (or yellow depending on the user's computer) highlights the stable region. Signal acquistion shifts are identified on a per channel basis and the largest region containing no anomalies is retained.

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

Dynamic range check: red and blue lines reflect the detected number of events over time. The x-axis corresponds to that of the signal acquisition plot.

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

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