annotate goseq.xml @ 3:783e8b70b047 draft

planemo upload for repository https://github.com/galaxyproject/tools-iuc/tree/master/tools/goseq commit 46c4278d292ab4d76dc5f3f74c3109c3179be7ef

<tool id="goseq" name="goseq" version="1.30.0">
    <description>tests for overrepresented gene categories</description>
    <requirements>
        <requirement type="package" version="1.6.0">r-optparse</requirement>
        <requirement type="package" version="1.30.0">bioconductor-goseq</requirement>
        <requirement type="package" version="3.5.0">bioconductor-org.hs.eg.db</requirement>
        <requirement type="package" version="3.5.0">bioconductor-org.dm.eg.db</requirement>
        <requirement type="package" version="3.5.0">bioconductor-org.dr.eg.db</requirement>
        <requirement type="package" version="3.5.0">bioconductor-org.mm.eg.db</requirement>
        <requirement type="package" version="0.7.6">r-dplyr</requirement>
        <requirement type="package" version="3.0.0">r-ggplot2</requirement>
    </requirements>
    <stdio>
        <regex match="Execution halted"
               source="both"
               level="fatal"
               description="Execution halted." />
        <regex match="Error in"
               source="both"
               level="fatal"
               description="An undefined error occured, please check your input carefully and contact your administrator." />
        <regex match="Fatal error"
               source="both"
               level="fatal"
               description="An undefined error occured, please check your input carefully and contact your administrator." />
    </stdio>
    <version_command><![CDATA[
echo $(R --version | grep version | grep -v GNU)", goseq version" $(R --vanilla --slave -e "library(goseq); cat(sessionInfo()\$otherPkgs\$goseq\$Version)" 2> /dev/null | grep -v -i "WARNING: ")", optparse version" $(R --vanilla --slave -e "library(optparse); cat(sessionInfo()\$otherPkgs\$optparse\$Version)" 2> /dev/null | grep -v -i "WARNING: ")", org.Hs.eg.db version" $(R --vanilla --slave -e "library(org.Hs.eg.db); cat(sessionInfo()\$otherPkgs\$org.Hs.eg.db\$Version)" 2> /dev/null | grep -v -i "WARNING: ")", org.Dr.eg.db version" $(R --vanilla --slave -e "library(org.Dr.eg.db); cat(sessionInfo()\$otherPkgs\$org.Dr.eg.db\$Version)" 2> /dev/null | grep -v -i "WARNING: ")", org.Dm.eg.db version" $(R --vanilla --slave -e "library(org.Dm.eg.db); cat(sessionInfo()\$otherPkgs\$org.Dm.eg.db\$Version)" 2> /dev/null | grep -v -i "WARNING: ")", org.Mm.eg.db version" $(R --vanilla --slave -e "library(org.Mm.eg.db); cat(sessionInfo()\$otherPkgs\$org.Mm.eg.db\$Version)" 2> /dev/null | grep -v -i "WARNING: ")", dplyr version" $(R --vanilla --slave -e "library(dplyr); cat(sessionInfo()\$otherPkgs\$dplyr\$Version)" 2> /dev/null | grep -v -i "WARNING: ")", ggplot2 version" $(R --vanilla --slave -e "library(ggplot2); cat(sessionInfo()\$otherPkgs\$ggplot2\$Version)" 2> /dev/null | grep -v -i "WARNING: ")
    ]]></version_command>
    <command><![CDATA[
Rscript '$__tool_directory__/goseq.r'

--dge_file '$dge_file'
--length_file '$length_file'

#if $categorySource.catSource == 'getgo':
    --genome $categorySource.genome
    --gene_id $categorySource.gene_id
    --fetch_cats '$categorySource.fetchcats'
#elif $categorySource.catSource == 'history':
    --category_file '$categorySource.category_file'
#end if

#if $methods['wallenius']:
    --wallenius_tab '$wallenius_tab'
#end if
#if $methods['hypergeometric']:
    --nobias_tab '$nobias_tab'
#end if
--repcnt '$methods.repcnt'
--sampling_tab '$sampling_tab'

--make_plots '$out.make_plots'
--length_bias_plot '$length_bias_plot'
--sample_vs_wallenius_plot '$sample_vs_wallenius_plot'

--rdata '$out.rdata_out'
--p_adj_method '$adv.p_adj_method'
--use_genes_without_cat '$adv.use_genes_without_cat'

#if $out.topgo_plot:
    --top_plot '$out.topgo_plot'
#end if

    ]]></command>

    <!-- Input Files-->
    <inputs>
        <param name="dge_file" type="data" format="tabular" label="Differentially expressed genes file" help="A tabular file with Gene IDs in the first column, and True or False in the second column. True means a gene is differentially expressed. See Help section for details."/>
        <param name="length_file" type="data" format="tabular" label="Gene lengths file" help="You can calculate the gene lengths using featureCounts or the Gene length and GC content tool."/>
        <conditional name="categorySource">
            <param name="catSource" type="select" format="tabular" label="Gene categories" help="You can obtain a mapping of genes to categories (for some genomes only) or you can provide your own category file.">
                <option value="getgo" selected="true">Get categories</option>
                <option value="history">Use a category file from history</option>
            </param>
            <when value="getgo">
                <param name="genome" type="select" label="Select a genome to use">
                    <option value="hg38">Human (hg38)</option>
                    <option value="mm10">Mouse (mm10)</option>
                    <option value="dm6">Fruit fly (dm6)</option>
                    <option value="danRer10">Zebrafish (danRer10)</option>
                </param>
                <param name="gene_id" type="select" label="Select Gene ID format" help="Supported Gene IDs to automatically fetch categories should either be Entrez, Ensembl, or gene symbols.">
                    <option value="ensGene">Ensembl Gene ID</option>
                    <option value="knownGene">Entrez Gene ID</option>
                    <option value="geneSymbol">Gene Symbol</option>
                </param>
                <param name="fetchcats" type="select" multiple="True" display="checkboxes" label="Select one or more categories" help="By default, goseq tests all three major Gene Ontology branches; Cellular Component, Biological Process and Molecular Function. However, it is possible to limit testing to any combination and/or to also use KEGG pathways.">
                    <option value="GO:CC" selected="True">GO: Cellular Component</option>
                    <option value="GO:BP" selected="True">GO: Biological Process</option>
                    <option value="GO:MF" selected="True">GO: Molecular Function</option>
                    <option value="KEGG">KEGG</option>
                </param>
            </when>
            <when value="history">
                <param name="category_file" type="data" format="tabular" label="Gene category file"/>
            </when>
        </conditional>

        <!-- Method Options -->
        <section name="methods" title="Method Options">
            <param name="wallenius" type="boolean" checked="true" label="Use Wallenius method" help="See help for details. Default: Yes" />
            <param name="hypergeometric" type="boolean" checked="false" label="Use Hypergeometric method" help="Does not use gene length information. See help for details. Default: No" />
            <param name="repcnt" type="integer" size="3" min="0" max="10000" value="0" label="Sampling number" help="Number of random samples to be calculated when sampling is used. Set to 0 to not do sampling. Larger values take a long time. Default: 0" />
        </section>

        <!-- Output Options -->
        <section name="out" title="Output Options">
            <param name="topgo_plot" type="boolean" checked="false" label="Output Top GO terms plot?" help="Output a PDF plot of the Top 10 over-represented GO terms. Default: No" />
            <param name="make_plots" type="boolean" checked="false" label="Produce diagnostic plots?" help="This will produce the length bias (PWF) plot. If both sampling and wallenius methods are selected, it will also produce a plot comparing their p-values. These plots may help you compare the different p-value estimation methods that goseq can use. Default: No" />
            <param name="rdata_out" type="boolean" checked="false" label="Output RData file?" help="Output all the data used by R to construct the tables and plots, can be loaded into R. Default: No" />
        </section>

        <!-- Advanced Options -->
        <section name="adv" title="Advanced Options">
            <param name="p_adj_method" type="select" label="Select a method for multiple hypothesis testing correction">
                <option value="BH" selected="True">Benjamini-Hochberg [FDR] (1995)</option>
                <option value="holm">Holm (1979)</option>
                <option value="hommel">Hommel (1988)</option>
                <option value="hochberg">Hochberg (1988)</option>
                <option value="bonferroni">Bonferroni</option>
                <option value="BY">Benjamini - Yekutieli (2001)</option>
            </param>
            <param name="use_genes_without_cat" type="boolean" checked="false" label="Count genes without any category?" help="For example, a large number of genes may have no GO term annotated. If this option is set to No, those genes will be ignored in the calculation of p-values. If this option is set to Yes, then these genes will count towards the total number of genes outside the category being tested. This was the default behaviour for version 1.15.1 and earlier. Default: No"/>
        </section>
    </inputs>

    <outputs>
        <data name="wallenius_tab" format="tabular" label="${tool.name} on ${on_string}: Ranked category list - Wallenius method">
            <filter>methods['wallenius']</filter>
        </data>
        <data name="sampling_tab" format="tabular" label="${tool.name} on ${on_string}: Ranked category list - Sampling method">
            <filter>methods['repcnt'] != 0</filter>
        </data>
        <data name="nobias_tab" format="tabular" label="${tool.name} on ${on_string}: Ranked category list - Hypergeometric method">
            <filter>methods['hypergeometric']</filter>
        </data>
        <data name="length_bias_plot" format="pdf" label="${tool.name} on ${on_string}: Length bias plot">
            <filter>out['make_plots']</filter>
        </data>
        <data name="sample_vs_wallenius_plot" format="pdf" label="${tool.name} on ${on_string}: Sampling vs Wallenius P-values plot">
            <filter>methods['repcnt'] != 0</filter>
            <filter>methods['wallenius']</filter>
            <filter>out['make_plots']</filter>
        </data>
        <data name="rdata" format="rdata" from_work_dir="goseq_analysis.RData" label="${tool.name} on ${on_string}: RData file">
            <filter>out['rdata_out']</filter>
        </data>
        <data name="top_plot" format="pdf" from_work_dir="top10.pdf" label="${tool.name} on ${on_string}: Top over-represented GO terms plot">
            <filter>methods['wallenius']</filter>
            <filter>out['topgo_plot']</filter>
        </data>
    </outputs>

    <tests>
        <!-- Ensure top plot is output -->
        <test expect_num_outputs="2">
            <param name="dge_file" value="dge_list.tab" ftype="tabular" />
            <param name="length_file" value="gene_length.tab" ftype="tabular" />
            <param name="catSource" value="history" />
            <param name="category_file" value="category.tab" ftype="tabular" />
            <param name="use_genes_without_cat" value="true" />
            <param name="topgo_plot" value="true" />
            <output name="top_plot" ftype="pdf" file="topgo.pdf" compare="sim_size"/>
        </test>
        <!-- Ensure Wallenius table is output -->
        <test expect_num_outputs="1">
            <param name="dge_file" value="dge_list.tab" ftype="tabular" />
            <param name="length_file" value="gene_length.tab" ftype="tabular" />
            <param name="catSource" value="history" />
            <param name="category_file" value="category.tab" ftype="tabular" />
            <param name="use_genes_without_cat" value="true" />
            <output name="wallenius_tab">
                <assert_contents>
                    <has_text_matching expression="category.*over_represented_pvalue.*under_represented_pvalue.*numDEInCat.*numInCat.*term.*ontology.*p.adjust.over_represented.*p.adjust.under_represented" />
                    <has_text_matching expression="GO:0000278.*0.01" />
                </assert_contents>
            </output>
        </test>
        <!-- Ensure getting GO categories works -->
        <test expect_num_outputs="1">
            <param name="dge_file" value="dge_list.tab" ftype="tabular"/>
            <param name="length_file" value="gene_length.tab" ftype="tabular"/>
            <param name="catSource" value="getgo" />
            <param name="genome" value="hg38" />
            <param name="gene_id" value="ensGene" />
            <param name="use_genes_without_cat" value="true" />
            <output name="wallenius_tab">
                <assert_contents>
                    <has_text_matching expression="category.*over_represented_pvalue.*under_represented_pvalue.*numDEInCat.*numInCat.*term.*ontology.*p.adjust.over_represented.*p.adjust.under_represented" />
                    <has_text_matching expression="GO:0005576.*5.2" />
                </assert_contents>
            </output>
        </test>
        <!-- Ensure getting GO categories for another genome (zebrafish) works -->
        <test expect_num_outputs="1">
            <param name="dge_file" value="dge_list_zf.tab" ftype="tabular"/>
            <param name="length_file" value="gene_length_zf.tab" ftype="tabular"/>
            <param name="catSource" value="getgo" />
            <param name="genome" value="danRer10"/>
            <param name="gene_id" value="ensGene" />
            <param name="use_genes_without_cat" value="true" />
            <output name="wallenius_tab">
                <assert_contents>
                    <has_text_matching expression="category.*over_represented_pvalue.*under_represented_pvalue.*numDEInCat.*numInCat.*term.*ontology.*p.adjust.over_represented.*p.adjust.under_represented" />
                    <has_text_matching expression="GO:0031324.*0.08" />
                </assert_contents>
            </output>
        </test>
        <!-- Ensure length bias plot works -->
        <test expect_num_outputs="2">
            <param name="dge_file" value="dge_list.tab" ftype="tabular" />
            <param name="length_file" value="gene_length.tab" ftype="tabular" />
            <param name="catSource" value="history" />
            <param name="category_file" value="category.tab" ftype="tabular" />
            <param name="make_plots" value="true" />
            <param name="use_genes_without_cat" value="true" />
            <output name="length_bias_plot" ftype="pdf" file="length_bias_plot.pdf" compare="sim_size" />
        </test>
        <!-- Ensure hypergeometric works -->
        <test expect_num_outputs="2">
            <param name="dge_file" value="dge_list.tab" ftype="tabular" />
            <param name="length_file" value="gene_length.tab" ftype="tabular" />
            <param name="catSource" value="history" />
            <param name="category_file" value="category.tab" ftype="tabular" />
            <param name="use_genes_without_cat" value="true" />
            <param name="hypergeometric" value="true" />
            <output name="nobias_tab" file="nobias.tab" compare="contains" />
        </test>
        <!-- Ensure sampling vs wallenius works -->
        <test expect_num_outputs="4">
            <param name="dge_file" value="dge_list.tab" ftype="tabular" />
            <param name="length_file" value="gene_length.tab" ftype="tabular" />
            <param name="catSource" value="history" />
            <param name="category_file" value="category.tab" ftype="tabular" />
            <param name="use_genes_without_cat" value="true" />
            <param name="make_plots" value="true" />
            <param name="repcnt" value="1000" />
            <output name="sampling_tab" file="samp.tab" compare="sim_size" />
            <output name="length_bias_plot" ftype="pdf" file="length_bias_plot.pdf" compare="sim_size" />
            <output name="sample_vs_wallenius_plot" ftype="pdf" file="sample_vs_wallenius_plot.pdf" compare="sim_size" />
        </test>
        <!-- Ensure RData output works -->
        <test expect_num_outputs="2">
            <param name="dge_file" value="dge_list.tab" ftype="tabular" />
            <param name="length_file" value="gene_length.tab" ftype="tabular" />
            <param name="catSource" value="history" />
            <param name="category_file" value="category.tab" ftype="tabular" />
            <param name="use_genes_without_cat" value="true" />
            <param name="rdata_out" value="true" />
            <output name="rdata" file="goseq_analysis.RData" compare="sim_size" />
        </test>
    </tests>

    <help><![CDATA[

.. class:: infomark

**What it does**

`Gene Ontology`_ (GO) analysis is widely used to reduce complexity and highlight biological processes in genome-wide expression studies, but standard methods give biased results on RNA-seq data due to over-detection of differential expression for long and highly expressed transcripts. This tool provides methods for performing GO analysis of RNA-seq data, taking length bias into account. The methods and software used by goseq are equally applicable to other category based tests of RNA-seq data, such as KEGG_ pathway analysis.

Options map closely to the excellent goseq manual_.

-----

**Inputs**

*Differentially expressed genes file*

goseq needs a tabular file containing information on differentially expressed genes. This should contain all genes assayed in the RNA-seq experiment. The file should have two columns with an optional header row. The first column should contain the Gene IDs, which must be unique within the file and not repeated. The second column should contain True or False. True means the gene should count as differentially expressed, False means it is not differentially expressed. You can use the "Compute an expression on every row" tool to create a True / False column for your dataset.

Example:

    =============== =====
    ENSG00000236824 False
    ENSG00000162526 False
    ENSG00000090402 True
    ENSG00000169188 False
    ENSG00000124103 False
    =============== =====

*Gene lengths file*

goseq needs information about the length of a gene to correct for potential length bias in differentially expressed genes using a Probability Weight Function (PWF). The PWF can be thought of, as a function which gives the probability that a gene will be differentially expressed, based on its length alone. The gene length file should have two columns with an optional header row. The first column should contain the Gene IDs, and the second column should contain the gene length in bp. If length data is unavailable for some genes, that entry should be set to NA. The goseq authors recommend using the gene lengths obtained from upstream summarization programs, such as **featureCounts**, if provided. Alternatively, the **Gene length and GC content** tool can produce such a file.

Example:

    =============== =====
    ENSG00000236824 13458
    ENSG00000162526 2191
    ENSG00000090402 6138
    ENSG00000169188 3245
    ENSG00000124103 1137
    =============== =====

*Gene categories file*

This tool can get GO and KEGG categories for some genomes. The three GO categories are GO:MF (Molecular Function - molecular activities of gene products), GO:CC (Cellular Component - where gene products are active), GO:BP (Biological Process - pathways and larger processes made up of the activities of multiple gene products). If your genome is not available, you will also need a file describing the membership of genes in categories. The category file should have two columns with an optional header row. with Gene ID in the first column and category identifier in the second column. As the mapping between categories and genes is usually many-to-many, this table will usually have multiple rows with the same Gene ID and category identifier.

Example:

    =============== ===========
    ENSG00000162526 GO\:0000003
    ENSG00000198648 GO\:0000278
    ENSG00000112312 GO\:0000278
    ENSG00000174442 GO\:0000278
    ENSG00000108953 GO\:0000278
    =============== ===========

-----

**Outputs**

* This tool outputs a tabular file containing a ranked list of gene categories, similar to below. The default output is the Wallenius method table. If the Sampling and/or Hypergeometric methods are also selected, additional tables are produced.
* Optionally, this tool can also output a plot of the top 10 over-represented categories, some diagnostic plots and an RData file, see **Output Options** above.

Example:

=========== =============== ================ ============ ========== ======================================== ========== =================== ====================
*category*  *over_rep_pval* *under_rep_pval* *numDEInCat* *numInCat* *term*                                   *ontology* *p.adjust.over_rep* *p.adjust.under_rep*
----------- --------------- ---------------- ------------ ---------- ---------------------------------------- ---------- ------------------- --------------------
GO\:0005576  0.000054        0.999975         56           142       extracellular region                     CC         0.394825             1
GO\:0005840  0.000143        0.999988         9            12        ribosome                                 CC         0.394825             1
GO\:0044763  0.000252        0.999858         148          473       single-organism cellular process         BP         0.394825             1
GO\:0044699  0.000279        0.999844         158          513       single-organism process                  BP         0.394825             1
GO\:0065010  0.000428        0.999808         43           108       extracellular membrane-bounded organelle CC         0.394825             1
GO\:0070062  0.000428        0.999808         43           108       extracellular exosome                    CC         0.394825             1
=========== =============== ================ ============ ========== ======================================== ========== =================== ====================

-----

**Method options**

3 methods, *Wallenius*, *Sampling* and *Hypergeometric*, can be used to calculate the p-values as follows.

*Wallenius*

approximates the true distribution of numbers of members of a category amongst DE genes by the Wallenius non-central hypergeometric distribution.
This distribution assumes that within a category all genes have the same probability of being chosen. Therefore, this approximation works best when the range in probabilities obtained by the probability weighting function is small. This is the method used by default.

*Sampling*

uses random sampling to approximate the true distribution and uses it to calculate the p-values for over (and under) representation of categories.
Although this is the most accurate method given a high enough value of sampling number, its use quickly becomes computationally prohibitive. It may sometimes be desirable to use random sampling to generate the null distribution for category
membership. For example, to check consistency against results from the Wallenius approximation. This is easily accomplished by using the method option to additionally specify sampling and the number of samples to generate.

*Hypergeometric*

assumes there is no bias in power to detect differential expression at all and calculates the p-values using a standard hypergeometric distribution (no length bias correction is performed). Useful if you wish to test the effect of length bias on your results.
Caution: Hypergeometric should NEVER be used for producing results for biological interpretation of RNA-seq data. If length bias is truly not present in your data, goseq will produce a nearly flat PWF plot, no length bias correction will be applied to your data, and all methods will produce the same results.

-----

**More Information**

In order to account for the length bias inherent to RNA-seq data when performing a GO analysis
(or other category based tests), one cannot simply use the hypergeometric distribution as the null
distribution for category membership, which is appropriate for data without DE length bias, such
as microarray data. GO analysis of RNA-seq data requires the use of random sampling in order
to generate a suitable null distribution for GO category membership and calculate each categories
significance for over representation amongst DE genes.

However, this random sampling is computationally expensive. In most cases, the Wallenius
distribution can be used to approximate the true null distribution, without any significant loss in
accuracy. The goseq package implements this approximation as its default option. The option
to generate the null distribution using random sampling is also included as an option, but users
should be aware that the default number of samples generated will not be enough to accurately
call enrichment when there are a large number of go terms.

Having established a null distribution, each category is then tested for over and under
representation amongst the set of differentially expressed genes and the null is used to calculate a
p-value for under and over representation.

Having performed a GO analysis, you may now wish to interpret the results. If you wish to
identify categories significantly enriched/unenriched below some p-value cutoff, it is necessary to
first apply some kind of multiple hypothesis testing correction. For example, you can identify GO categories over
enriched using a 0.05 FDR (p.adjust) cutoff [Benjamini and Hochberg, 1995].

Unless you are a machine, GO and KEGG category identifiers are probably not very meaningful to you.
Information about each identifier can be obtained from the `Gene Ontology`_ and KEGG_ websites.

.. _manual: https://bioconductor.org/packages/release/bioc/vignettes/goseq/inst/doc/goseq.pdf
.. _Gene Ontology: http://www.geneontology.org
.. _KEGG: http://www.genome.jp/kegg

    ]]></help>
    <citations>
        <citation type="doi">10.1186/gb-2010-11-2-r14</citation>
    </citations>
</tool>