<?xml version="1.0"?>
<tool id="mageck_test" name="MAGeCKs test" version="@VERSION@.1" >
    <description>- given a table of read counts, perform the sgRNA and gene ranking</description>
    <macros>
        <import>mageck_macros.xml</import>
    </macros>
    <expand macro="requirements" />
    <expand macro="version" />
    <command detect_errors="exit_code"><![CDATA[

mageck test
-k '$count_table'

#if $sampleids.sample_select == "treated":
    -t '$sampleids.treatment_id'
#elif $sampleids.sample_select == "control":
    --day0-label '$sampleids.day0_label'
#end if

#if '$control_id':
    -c '$control_id'
#end if

-n output

$out.normcounts

$out.pdfreport

#if $adv.norm_method:
    --norm-method $adv.norm_method
#end if

#if $adv.fdr_threshold:
    --gene-test-fdr-threshold $adv.fdr_threshold
#end if

#if $adv.adjust_method:
    --adjust-method $adv.adjust_method
#end if

$adv.var_samples

#if $adv.sort_criteria:
    --sort-criteria $adv.sort_criteria
#end if

#if $adv.remove_zero:
    --remove-zero $adv.remove_zero
#end if

#if $adv.remove_zero_threshold:
    --remove-zero-threshold $adv.remove_zero_threshold
#end if

#if $adv.lfc_method:
    --gene-lfc-method $adv.lfc_method
#end if

#if $adv.control_sgrna:
    --control-sgrna $adv.control_sgrna
#end if

#if $adv.cnv_norm:
    --cnv-norm $adv.cnv_norm
#end if

#if $adv.cell_line:
    --cell-line $adv.cell_line
#end if

    ]]></command>
    <inputs>
        <param name="count_table" argument="--count-table" type="data" format="tabular" label="Counts file" help="A tab-separated file of read counts. See Help below for format" />
        <conditional name="sampleids">
            <param name="sample_select" type="select" label="Specify Treated samples or Control"
                help="You can choose to either specify the treated samples or the control">
                <option value="treated">Treated samples</option>
                <option value="control">Control sample</option>
            </param>
            <when value="treated">
                <param name="treatment_id" argument="--treatment-id" type="text" label="Treated Sample Labels (or Indexes)" help="If sample label is provided, the labels must match the labels in the first line of the count table, separated by comma (,); for example, HL60.final,KBM7.final. For sample index, 0,2 means the 1st and 3rd samples are treatment experiments. See Help below for a detailed description.">
                    <validator type="regex" message="Please only use letters, numbers or underscores in sample labels, and separate labels by commas">^[\w,]+$</validator>
                </param>
            </when>
            <when value="control">
                <param name="day0_label" argument="--day0-label" type="text" optional="true" value="" label="Control Sample Label" help="Specify the label for the control sample. For every other sample label, the module will treat it as a treatment condition and compare with control sample (usually day 0 or plasmid)">
                    <validator type="regex" message="Please only use letters, numbers or underscores in sample label">^[\w]+$</validator>
                </param>
            </when>
        </conditional>
        <param name="control_id" argument="--control-id" type="text" optional="true" label="Control Sample Labels (or Indexes)" help="If sample label is provided, the labels must match the labels in the first line of the count table, separated by comma (,). Default is all the samples not specified in treatment experiments. See Help below for a detailed description.">
            <validator type="regex" message="Please only use letters, numbers or underscores in sample labels, and separate labels by commas">^[\w,]+$</validator>
        </param>
        <section name="out" title="Output Options">
            <param name="normcounts" argument="--normcounts-to-file" type="boolean" truevalue="--normcounts-to-file" falsevalue="" checked="false" optional="true" label="Output normalized counts file" help="Default: No"  />
            <param name="pdfreport" argument="--pdf-report" type="boolean" truevalue="--pdf-report" falsevalue="" checked="false" optional="true" label="Output plots" help="Generate PDF of the plots. Default: No" />
            <param name="rfilesOpt" type="boolean" truevalue="True" falsevalue="" checked="false" optional="true" label="Output R files" help="Output the .R and .Rnw files to generate the PDF report. The gene summary file will also be output as it is required to regenerate the report. Default: No" />
            <param name="out_log" type="boolean" truevalue="True" falsevalue="" checked="false" label="Output Log file" help="This file includes the logging information during the execution. Default: No" />
        </section>

        <section name="adv" title="Advanced Options">
            <param name="norm_method" argument="--norm-method" optional="true" type="select" label="Method for normalization" help="If control is specified, the size factor will be estimated using control sgRNAs specified in --control-sgrna option. Default: Median" >
            <option value="median" selected="True">Median</option>
            <option value="none">None</option>
            <option value="total">Total</option>
            <option value="control">Control</option>
        </param>
        <param name="fdr_threshold" argument="--gene-test-fdr-threshold" type="float" min="0" max="1" optional="true" label="Gene test FDR-adjusted Threshold" help="FDR threshold for gene test. Default: 0.25"/>
        <param name="adjust_method" argument="--adjust-method" type="select" optional="true" label="P-Value Adjustment Method" help="Method for sgRNA-level p-value adjustment, including False Discovery Rate (FDR), Holm's method (Holm), or Pounds's method (Pounds). Default: FDR">
            <option value="fdr" selected="True">FDR</option>
            <option value="holm">Holm</option>
            <option value="pounds">Pounds</option>
        </param>
        <param name="var_samples" argument="--variance-from-all-samples" type="boolean" truevalue="--variance-from-all-samples" falsevalue="" checked="false" optional="true" label="Estimate the variance from all samples, instead of from only control samples" help="Use this option only if you believe there are relatively few essential sgRNAs or genes between control and treatment samples" />
        <expand macro="sort_criteria" />
        <param name="remove_zero" argument="--remove-zero" type="select" optional="true" label="Remove zero" help="Remove sgRNAs whose mean value is zero in Control, Treatment, Both control/treatment, or Any control/treatment sample. Default: Both (remove those sgRNAs that are zero in both control and treatment samples)" >
            <option value="none" >None</option>
            <option value="control">Control</option>
            <option value="treatment">Treatment</option>
            <option value="both" selected="True">Both</option>
            <option value="any">Any</option>
        </param>
        <param name="remove_zero_threshold" argument="--remove-zero-threshold" type="float" optional="true" label="Remove zero Threshold" help="sgRNA normalized count threshold to be considered removed in the --remove-zero option. Default: 0"/>
        <param name="lfc_method" argument="--gene-lfc-method" type="select" optional="true" label="Gene Log-Fold Change Method." help="Method to calculate gene log fold changes (LFC) from sgRNA LFCs. Available methods include the median/mean of all sgRNAs (median/mean), or the median/mean sgRNAs that are ranked in front of the alpha cutoff in RRA (alphamedian/alphamean), or the sgRNA that has the second strongest LFC (secondbest). In the alphamedian/alphamean case, the number of sgRNAs correspond to the goodsgrna column in the output, and the gene LFC will be set to 0 if no sgRNA is in front of the alpha cutoff. Default: Median. (new since v0.5.5)">
            <option value="median" selected="True">Median</option>
            <option value="alphamedian">Alphamedian</option>
            <option value="mean">Mean</option>
            <option value="alphamean">Alphamean</option>
            <option value="secondbest">Secondbest</option>
        </param>
        <param name="control_sgrna" argument="--control-sgrna" type="data" format="tabular" optional="true" label="Control sgRNAs file" help="A list of control sgRNAs for normalization and for generating the null distribution of RRA" />
        <param name="cnv_norm" argument="--cnv-norm" type="data" format="tabular" optional="true" label="CNV profile file" help="A tab-delimited file containing the CNV status for each gene. See Help below for more information and format." />
        <param name="cell_line" argument="--cell-line" type="text" optional="true" label="Cell line column" help="Name of the column from the CNV profile file to use. See Help below for more information" />
        </section>
    </inputs>

    <outputs>
        <data name="gene_summary" format="tabular" from_work_dir="output.gene_summary.txt" label="${tool.name} on ${on_string}: Gene Summary" />
        <data name="sgrna_summary" format="tabular" from_work_dir="output.sgrna_summary.txt" label="${tool.name} on ${on_string}: sgRNA Summary" />
        <data name="log" format="tabular" from_work_dir="output.log" label="${tool.name} on ${on_string}: Log">
            <filter>out['out_log'] is True</filter>
        </data>
        <data name="normcounts" format="tabular" from_work_dir="output.normalized.txt" label="${tool.name} on ${on_string}: sgRNA Normalized Counts">
            <filter>out['normcounts'] is True</filter>
        </data>
        <data name="plots" format="pdf" from_work_dir="output.pdf" label="${tool.name} on ${on_string}: PDF Report">
            <filter>out['pdfreport'] is True</filter>
        </data>
        <data name="rscript" format="txt" from_work_dir="output.R" label="${tool.name} on ${on_string}: R file"  >
            <filter>out['rfilesOpt'] is True</filter>
        </data>
        <data name="rnwfile" format="txt" from_work_dir="output_summary.Rnw" label="${tool.name} on ${on_string}: Rnw file"  >
            <filter>out['rfilesOpt'] is True</filter>
        </data>
    </outputs>
    <tests>
        <!-- Ensure MAGeCK's default output works -->
        <test expect_num_outputs="2">
            <param name="count_table" value="in.test.sample.txt" ftype="tabular" />
            <param name="treatment_id" value="HL60_final,KBM7_final" />
            <param name="control_id" value="HL60_initial,KBM7_initial" />
            <output name="gene_summary" file="out.test.gene_summary.txt"/>
            <output name="sgrna_summary" file="out.test.sgrna_summary.txt"/>
        </test>
        <!-- Ensure MAGeCK's additional outputs works -->
        <test expect_num_outputs="7">
            <param name="count_table" value="in.test.sample.txt" ftype="tabular" />
            <param name="treatment_id" value="HL60_final,KBM7_final" />
            <param name="control_id" value="HL60_initial,KBM7_initial" />
            <param name="out_log" value="True" />
            <param name="normcounts" value="True" />
            <param name="pdfreport" value="True" />
            <param name="rfilesOpt" value="True" />
            <output name="gene_summary" file="out.test.gene_summary.txt"/>
            <output name="sgrna_summary" file="out.test.sgrna_summary.txt"/>
            <output name="normcounts" file="out.test.normalized.txt"/>
            <output name="log" file="out.test.log.txt" compare="sim_size"/>
            <output name="plots" file="out.test.plots.pdf" compare="sim_size"/>
            <output name="rscript" file="out.test.R" />
            <output name="rnwfile" file="output_summary.Rnw" />
        </test>
    </tests>

    <help><![CDATA[
.. class:: infomark

**What it does**

`Model-based Analysis of Genome-wide CRISPR-Cas9 Knockout` (MAGeCK) is a computational tool to identify important genes from the recent genome-scale CRISPR-Cas9 knockout screens (or GeCKO) technology. MAGeCK can be used for prioritizing single-guide RNAs, genes and pathways in genome-scale CRISPR/Cas9 knockout screens. MAGeCK identifies both positively and negatively selected genes simultaneously and reports robust results across different experimental conditions. MAGeCK is developed and maintained by Wei Li and Han Xu from `Prof. Xiaole Shirley Liu's lab`_ at the Department of Biostatistics and Computational Biology, Dana-Farber Cancer Institute and Harvard School of Public Health. MAGeCK has been used to identify functional lncRNAs from screens with close to `100% validation rate`_.

.. _`Model-based Analysis of Genome-wide CRISPR-Cas9 Knockout`: https://genomebiology.biomedcentral.com/articles/10.1186/s13059-014-0554-4
.. _`100% validation rate`: https://sourceforge.net/p/mageck/wiki/Home/
.. _`Prof. Xiaole Shirley Liu's lab`: http://liulab.dfci.harvard.edu/

-----

**mageck test**

This tests and ranks sgRNAs and genes based on the table provided.

**Inputs**

**sgRNA count file**

The input sgRNA count file be tab-delimited and list the names of the sgRNA, the gene it is targeting, followed by the read counts in each sample. A header line is optional. For example in the studies of T. Wang et al. Science 2014, there are 4 CRISPR screening samples, and they are labeled as: HL60.initial, KBM7.initial, HL60.final, KBM7.final, see below.

Example:

  ==============  ========    ================    ================   ==============   ==============
  **sgRNA**       **gene**    **HL60.initial**    **KBM7.initial**   **HL60.final**   **KBM7.final**
  --------------  --------    ----------------    ----------------   --------------   --------------
  A1CF_m52595977  A1CF        213                 274                883              175
  A1CF_m52596017  A1CF        294                 412                1554             1891
  A1CF_m52596056  A1CF        421                 368                566              759
  A1CF_m52603842  A1CF        274                 243                314              855
  A1CF_m52603847  A1CF        0                   50                 145              266
  ==============  ========    ================    ================   ==============   ==============

**Sample Labels**

In the Treatment and Control inputs above, you can use either Sample Label or Sample Index to specify samples. If sample label is used, the labels MUST match the sample labels in the first line of the count table. For example, "HL60.final,KBM7.final".
You can also use sample index to specify samples. The index of the sample is the order it appears in the sgRNA read count file, starting from 0. The index is used in the Treatment and Control inputs. In the example above, there are four samples, and the index of each sample is as follows:

  ============  =======
  *sample*      *index*
  ------------  -------
  HL60.initial  0
  KBM7.initial  1
  HL60.final    2
  KBM7.final    3
  ============  =======

**Control sgRNA file**

The optional Control sgRNA file is used to generate null distribution when calculating the p values. If this option is not specified, MAGeCK generates the null distribution of RRA scores by assuming all of the genes in the library are non-essential. This approach is sometimes over-conservative, and you can improve this if you know some genes are not essential. By providing the corresponding sgRNA IDs in this option, MAGeCK will have a better estimation of p values. To use this option, you need to prepare a text file specifying the IDs of control sgRNAs, one line for one sgRNA ID.

-----

**Outputs**

This tool outputs

    * a ranked sgRNA Summary file
    * a ranked Gene Summary file

Optionally, under **Output Options** you can choose to output

    * a Normalized Counts table
    * a PDF of the plots
    * the .R and .Rnw files to generate the report
    * a Log file of the analysis

**sgRNA Summary file**

An example of the sgRNA ranking output is as follows:

================  ========  ================= ===================  ================  ============== =======  ===============  ===========  =========  ========= =========== ============== ===========  =====================
**sgrna**         **Gene**  **control_count** **treatment_count**  **control_mean**  **treat_mean** **LFC**  **control_var**  **adj_var**  **score**  **p.low** **p.high**  **p.twosided** **FDR**      **high_in_treatment**
----------------  --------  ----------------- -------------------  ----------------  -------------- -------  ---------------  -----------  ---------  --------- ----------- -------------- -----------  ---------------------
INO80B_m74682554  INO80B    0.0/0.0           1220.15/1476.14      0.810860          1348.15        10.70    0.0              19.0767      308.478    1.0       1.11022e-16  2.22044e-16   1.57651e-14  True
NHS_p17705966     NHS       1.62172/3.90887   2327.09/1849.95      2.76529           2088.52        9.54     2.61554          68.2450      252.480    1.0       1.11022e-16  2.22044e-16   1.57651e-14  True
================  ========  ================= ===================  ================  ============== =======  ===============  ===========  =========  ========= =========== ============== ===========  =====================

The contents of each column are as follows:

* **sgrna** sgRNA ID
* **Gene**  The targeting gene
* **control_count** Normalized read counts in control samples
* **treatment_count** Normalized read counts in treatment samples
* **control_mean**  Mean read counts in control samples
* **treat_mean**  Mean read counts in treatment samples
* **LFC** The log fold change of sgRNA
* **control_var** The raw variance in control samples
* **adj_var** The adjusted variance in control samples
* **score** The score of this sgRNA
* **p.low** p-value (lower tail)
* **p.high**  p-value (higher tail)
* **p.twosided**  p-value (two sided)
* **FDR** false discovery rate
* **high_in_treatment** Whether the abundance is higher in treatment samples


**Gene Summary file**

An example of the gene summary output file is as follows:

======= ======= ============= =============== =========== ============ ================= =========== ============= =============== =========== ============ ================= ===========
**id**  **num** **neg|score** **neg|p-value** **neg|fdr** **neg|rank** **neg|goodsgrna** **neg|lfc** **pos|score** **pos|p-value** **pos|fdr** **pos|rank** **pos|goodsgrna** **pos|lfc**
------- ------- ------------- --------------- ----------- ------------ ----------------- ----------- ------------- --------------- ----------- ------------ ----------------- -----------
ESPL1   12      6.4327e-10    7.558e-06       7.9e-05      1           -2.35             11          0.99725       0.99981         0.999992    615          0                 -0.07
RPL18   12      6.4671e-10    7.558e-06       7.9e-05      2           -2.12             11          0.99799       0.99989         0.999992    620          0                 -0.32
CDK1    12      2.6439e-09    7.558e-06       7.9e-05      3           -1.93             12          1.0           0.99999         0.999992    655          0                 -0.12
======= ======= ============= =============== =========== ============ ================= =========== ============= =============== =========== ============ ================= ===========

The contents of each column is as follows:

* **id**  Gene ID
* **num** The number of targeting sgRNAs for each gene
* **neg|score** The RRA lo value of this gene in negative selection
* **neg|p-value** The raw p-value (using permutation) of this gene in negative selection
* **neg|fdr** The false discovery rate of this gene in negative selection
* **neg|rank**  The ranking of this gene in negative selection
* **neg|goodsgrna** The number of "good" sgRNAs, i.e., sgRNAs whose ranking is below the alpha cutoff (determined by the --gene-test-fdr-threshold option), in negative selection.
* **neg|lfc** The log fold change of this gene in negative selection
* **pos|score** The number of targeting sgRNAs for each gene in positive selection (usually the same as num.neg)
* **pos|score** The RRA lo value of this gene in negative selection
* **pos|p-value** The raw p-value of this gene in positive selection
* **pos|fdr** The false discovery rate of this gene in positive selection
* **pos|rank**  The ranking of this gene in positive selection
* **pos|goodsgrna** The number of "good" sgRNAs, i.e., sgRNAs whose ranking is below the alpha cutoff (determined by the --gene-test-fdr-threshold option), in positive selection.
* **pos|lfc** The log fold change of this gene in positive selection

Genes are ranked by the p.neg field (by default). If you need a ranking by the p.pos, you can use the --sort-criteria option.

-----

**More Information**

**Overview of the MAGeCK algorithm**

Briefly, read counts from different samples are first median-normalized to adjust for the effect of library sizes and read count distributions. Then the variance of read counts is estimated by sharing information across features, and a negative binomial (NB) model is used to test whether sgRNA abundance differs significantly between treatments and controls. This approach is similar to those used for differential RNA-Seq analysis. We rank sgRNAs based on P-values calculated from the NB model, and use a modified robust ranking aggregation (RRA) algorithm named α-RRA to identify positively or negatively selected genes. More specifically, α-RRA assumes that if a gene has no effect on selection, then sgRNAs targeting this gene should be uniformly distributed across the ranked list of all the sgRNAs. α-RRA ranks genes by comparing the skew in rankings to the uniform null model, and prioritizes genes whose sgRNA rankings are consistently higher than expected. α-RRA calculates the statistical significance of the skew by permutation, and a detailed description of the algorithm is presented in the Materials and methods section of the `MAGeCK paper`_. Finally, MAGeCK reports positively and negatively selected pathways by applying α-RRA to the rankings of genes in a pathway.

For more information on using MAGeCK, see the `MAGeCK website here`_.

.. _`MAGeCK paper`: https://genomebiology.biomedcentral.com/articles/10.1186/s13059-014-0554-4
.. _`MAGeCK website here`: https://sourceforge.net/p/mageck/wiki/QA/#using-mageck

    ]]></help>
      <expand macro="citations" />
</tool>