annotate FCSGateTrans.xml @ 1:c28c2e680bf5 draft

"planemo upload for repository https://github.com/ImmPortDB/immport-galaxy-tools/tree/master/flowtools/fcs_gate_trans commit f34ed6ca8e77b9792a270890262c2936b13e30b9"

<tool id="fcs_gate_trans_convert" name="Transform FCS data" version="1.2+galaxy0">
  <description>with optional compensation and automated gating with flowDensity.</description>
  <requirements>
    <requirement type="package" version="1.10.0">bioconductor-flowdensity</requirement>
  </requirements>
  <stdio>
    <exit_code range="2:" level="fatal" description="See stderr for more details." />
  </stdio>
  <command><![CDATA[
    Rscript $__tool_directory__/FCSGateTrans.R '${input}' '${output}' $comp '${outformat}' '${graph}' '${report}' '${transform.trans_method}'
      #if $transform.trans_method == "arcsinh"
        $transform.scaling_factor
      #else if $transform.trans_method == "logicle"
        $transform.w $transform.t $transform.m
      #end if
  ]]>
  </command>
  <inputs>
    <param format="fcs" name="input" type="data" label="FCS file"/>
    <param name="comp" type="boolean" checked="false" truevalue="TRUE" falsevalue="FALSE" label="Compensate?"/>
    <conditional name="transform">
      <param name="trans_method" type="select" label="Transformation using:" help="by default, FCSTrans">
        <option value="fcstrans">FCSTrans</option>
        <option value="logicle_auto">logicle, automatic estimation of parameters</option>
        <option value="logicle">logicle</option>
        <option value="arcsinh">arcsinh</option>
        <option value="None">no transformation please.</option>
      </param>
      <when value="arcsinh">
        <param name="scaling_factor" type="integer" min="1" max="200" value="150" label="Scaling factor b for arcsinh transform:" help="The default value is 150 for standard FCM data. The recommended value for cyTOF data is 5.">
        </param>
      </when>
      <when value="logicle">
        <param name="w" type="float" value="0.5" label="Linearization width w for logicle transform:" help="w should be positive and determines the slope of transformation at zero. The default value is 0.5.">
        </param>
        <param name="t" type="integer" value="262144" label="Top of the scale data value t for logicle transform:" help=" t should be greater than zero. Recommended values are 10000 for common 4 decade data or 262144 for a 18 bit data range. The default value is 262144.">
        </param>
        <param name="m" type="float" value="4.5" label="Full width of the transformed display m for logicle transform:" help="m is expressed in asymptotic decades and should be positive. The default value is 4.5 .">
        </param>
      </when>
    </conditional>
    <param name="gate" type="select" label="Automatically gate debris?">
      <option value="FALSE">No, thank you</option>
      <option value="TRUE">Yes, please</option>
    </param>
    <param name="gate" type="boolean" checked="false" truevalue="TRUE" falsevalue="FALSE" label="Automatically gate debris?"/>
    <param name="outformat" type="select" label="Output Format">
      <option value="flowtext">Text File</option>
      <option value="FCS">FCS 3.0</option>
      <option value="flowFrame">R Data, flowFrame</option>
    </param>
  </inputs>
  <outputs>
    <data format="flowtext" name="output" label="${outformat} FCSGateTrans output with ${transform.trans_method} on ${input.name}">
      <change_format>
        <when input="outformat" value="FCS" format="fcs" />
        <when input="outformat" value="flowFrame" format="flowframe" />
      </change_format>
    </data>
    <data format="png" name="graph" label="Graphs of automated gating on ${input.name} with ${transform.trans_method}">
      <filter>(gate)</filter>
    </data>
    <data format="txt" name="report" label="Report of automated gating on ${input.name} with ${transform.trans_method}">
      <filter>(gate)</filter>
    </data>
  </outputs>
  <tests>
    <test>
      <param name="input" value="testfcs1.fcs"/>
      <param name="comp" value="TRUE"/>
      <param name="gate" value="FALSE"/>
      <param name="outformat" value="FCS"/>
      <param name="trans_method" value="fcstrans"/>
      <output name="output" file="comp_gated.fcs" compare="sim_size"/>
    </test>
    <test>
      <param name="input" value="testfcs1.fcs"/>
      <param name="comp" value="TRUE"/>
      <param name="gate" value="FALSE"/>
      <param name="outformat" value="flowFrame"/>
      <param name="trans_method" value="fcstrans"/>
      <output name="output" file="comp_gated.flowframe" compare="sim_size"/>
    </test>
  </tests>
  <help><![CDATA[
    This tool offers data transformation options, optional automated gating of debris using flowDensity and conversion of FCS files to text.

-----

**Input files**

This tool uses FCS files as input and files are processed serially. Users choose to automatically gate cellular debris, and/or compensate the data.

**Output files**

Output is tab-separated text containing transformed fluorescence intensity values for each marker.
If the option is selected, a FCS file (format FCS3.0) is generated.

**Gating output**

Automatically gated output includes a summary of data pre- and post-gating as well as density scatter plots pre- and post- gating for each marker pair.

-----

Compensation will be implemented according to the spillover matrix included in the FCS files (if available).

-----

**Transformation**

This tools currently supports 3 transformation algorithms: FCSTrans, arcsinh and logicle. The latter two are implemented using flowCore, FCSTrans is documented in the paper cited below. Transformation algorithms are NOT applied to FSC and SSC channels.

-----

**Automated Gating**

Automated gating is implemented with flowDensity. Cellular debris removal uses gate coordinates calculated based on the density of the forward scatter channel only. The calculated gate is vertical and located at the largest value of either the 0.1 quantile of the FSC density or the lowest density between the first and second density peaks. Cells smaller than the threshold are removed.

.. class:: warningmark

Users should verify whether data benefit from being gated. We recommend evaluating the number of events and scatter plots pre- and post-gating.

-----

**Example**

*Output text file*::

   Forward Scatter Side Scatter Marker1 Marker2 Marker3 Marker4 ...
   449             157          551     129     169     292     ...
   894             1023	        199     277     320     227     ...
   262             73           437     69      0       146     ...
   340             115          509     268     0       74      ...
   ...             ...          ...     ...     ...     ...     ...


*Gating summary*::

   =========================
   ==    BEFORE GATING    ==
   =========================
       events parameters
       203584         13
           FSC-A FSC-H SSC-A  SSC-H APC-A APC-H7-A FITC-A PerCP-Cy5-5-A V450-A V500-A   PE-A PE-Cy7-A  Time
   Min.        0    78     0    0.0     0      0.0      0             0      0      0    0.0        0     0
   1st Qu.   869   769   544  514.0   940      0.0   1023           826    978   1104  358.8      913  4182
   Median   1234  1081   754  704.0  1750     31.0   1247          1614   1971   1505 1612.0     1791  8392
   Mean     1304  1108  1002  863.6  1629    812.8   1329          1597   1694   1765 1376.0     1813  8536
   3rd Qu.  1675  1474  1240 1087.0  2326   1573.0   1629          2565   2326   2640 2261.0     2782 12760
   Max.     4095  4061  4095 4012.0  4096   4086.0   4094          4022   4091   4096 4093.0     4096 17740

   =========================
   ==    AFTER  GATING    ==
   =========================
       events parameters
       171547         13
           FSC-A FSC-H  SSC-A  SSC-H APC-A APC-H7-A FITC-A PerCP-Cy5-5-A V450-A V500-A PE-A PE-Cy7-A  Time
   Min.      403   219    1.0    4.0     0      0.0      0             0      0      0    0        0     0
   1st Qu.   949   849  599.0  565.0   979      0.0   1063           943   1203   1119  444     1060  4182
   Median   1348  1170  782.0  730.0  1809      0.0   1258          1717   2082   1493 1785     1883  8358
   Mean     1353  1177  989.2  885.9  1642    779.4   1330          1678   1778   1753 1458     1873  8504
   3rd Qu.  1670  1475 1204.0 1076.0  2322   1559.0   1591          2623   2345   2630 2289     2808 12700
   Max.     2953  2406 4055.0 3329.0  4069   4080.0   3498          3868   3612   4076 4093     3764 17730

*Gating plots*:

.. image:: ./static/images/flowtools/flowdensity.png
  ]]>
  </help>
  <citations>
    <citation type="doi">10.1002/cyto.a.22037</citation>
    <citation type="doi">10.1093/bioinformatics/btu677</citation>
    <citation type="doi">10.1186/1471-2105-10-106</citation>
  </citations>
</tool>