annotate mutspecStat.xml @ 7:eda59b985b1c draft default tip

Uploaded

<tool id="mutSpecStat" name="MutSpec Stat" version="0.1" hidden="false">
<description>Calculate various statistics on mutations</description>

<requirements>
    <requirement type="set_environment">SCRIPT_PATH</requirement>
    <requirement type="package" version="5.18.1">perl</requirement>
    <requirement type="package" version="3.5">weblogo</requirement>
    <requirement type="package" version="1.9">numpy</requirement>
    <requirement type="package" version="3.2.1">R</requirement>
    <requirement type="package" version="2.11.1">fontconfig</requirement>
    <requirement type="package" version="0.1">mutspec</requirement>
</requirements>

<command interpreter="bash">
        mutspecStat_wrapper.sh
        $html
        ${GALAXY_DATA_INDEX_DIR}/shared/ucsc/chrom/
        #if str($estimateSignature.estimSign) == "true":
              ${estimateSignature.estimT}
        #else
            0
        #end if

        "--refGenome ${refGenome} --pathSeqRefGenome ${refGenome.fields.path} $pooldata $reportSample"
        #import re
        #for $f in $dataset_list
        	#set $regexp = $re.compile("\((.*)\)")
        	#if $regexp.search($f.name)
        		#set filename=$regexp.search($f.name)
				 "$f=${filename.group(1)}"
        	#else
				 "$f=${f.name}"
			#end if
		#end for
</command>

<inputs>
	<param name="dataset_list" type="data_collection" format="tabular" collection_type="list" label="Annotated Dataset List" help="Select a dataset list/collection from your history" />
	<param name="refGenome" type="select" label="Reference genome" help="All data in your dataset list should have been generated with the selected genome">
	        <options from_data_table="annovar_index" />
	</param>

	<param name="pooldata" type="boolean" checked="true" truevalue="--pooldata" falsevalue="" label="Include statistics on the pooled samples" />
	<param name="reportSample" type="boolean" checked="false" truevalue="--reportSample" falsevalue="" label="Generate one output file for each sample" help="By default, one output Excel file will be generated with statistics of each sample shown in different data sheets. Setting this option to true will generate one Excel file for each sample instead. It is recommended to use this option if your dataset list contains more than 250 files as the Excel output file may be too heavy to open easily on a computer with limited RAM"/>

    <conditional name="estimateSignature">
        <param name="estimSign" type="boolean" checked="false" truevalue="true" label="Compute statistics for estimating the number of signatures" help="This option gererates different statistics that can be used to estimate the number of signatures to extract with NMF (this number should be used in the MutSpec-NMF tool"/>
        <when value="true">
            <param name="estimT" type="text" value="8" label="Maximum number of signatures to compute" help="Warning: Selecting a number above 8 may not work on small datasets"/>
        </when>
    </conditional>

</inputs>

<outputs>
	<data name="html" type="data" format="html" label="mutation spectra report on  ${dataset_list.name}" />
</outputs>

<stdio>
    <regex match="FutureWarning"               source="both"     level="warning"  description="FutureWarning" />
    <regex match="Missing flag !"              source="stderr"   level="fatal"    description="You have forgotten to specify one or more arguments" />
    <regex match="Error"                       source="stderr"   level="fatal"    description="Read error message for more details" />
    <regex match="Erreur"                      source="both"     level="fatal"    description="Read error message for more details" />
    <regex match="Use of uninitialized value"  source="both"     level="fatal"    description="Read error message for more details" />
    <regex match="errors in some of the runs"  source="both"     level="fatal"    description="Specify a lower maximum number of signatures to estimate" />
    <regex match="Couldn't locate"  source="both"     level="fatal"    description="Read error message for more details" />
</stdio>

<help>

**What it does**

MutSpec-Stat calculates various statistics describing mutation characteristics extracted from a dataset collection, and estimate (optional) the number of signatures present in the dataset.
The statistics include overall distribution of mutations, mutation distribution for single base substitutions (SBS) by functional regions, chromosomes, or in their trinucleotide sequence context (see details below).

--------------------------------------------------------------------------------------------------------------------------------------------------

**Input formats**

The tool accepts a dataset list

.. class:: infomark

You should thus create a dataset list even when using one file (see Galaxy help to learn `how to create a dataset list`__)

.. __: https://wiki.galaxyproject.org/Histories#Dataset_Collections

.. class:: warningmark

The input files must have been generated by the MutSpec-Annot tool (so they contain the required annotations).

--------------------------------------------------------------------------------------------------------------------------------------------------

**Output**

MutSpec-Stat generates an html page with links to :
   - an Excel file that includes all computed statistics shown in tabular and graphical formats, for each sample (one by datasheet) and for the pooled samples (optional),
   - html pages for individual sample results,
   - the input matrix for the tool MutSpec-NMF,
   - the result of the estimation of the number of signatures (if the option "Compute statistics for estimating the number of signatures" was selected).

The following statistics are generated:

**Graph 1. SBS distribution**
Proportion (percent of all SBS) of each type of single base substitution (SBS).
All SBS are considered, including the ones without strand orientation annotation.

**Table 1. Frequency and counts of all SBS**
Values corresponding to graph 1.


**Graph 2. Impact on protein sequence**
Impact of all mutations (SBS and Indel) on the protein sequence based on the ExonicFunc.refGene annotation.
For more details about the annotation, please visit the `Annovar web page`__

.. __: http://www.openbioinformatics.org/annovar/annovar_gene.html#output1


**Table 2. Frequency and counts of functional impacts**
Values corresponding to graph 2.


**Graph 3. Stranded distribution of SBS**
Proportion (percent of all SBS with strand annotation) of the six substitution types on the transcribed and non-transcribed strand.
Only regions with strand annotation are considered.

**Table 3. Significance of the strand biases**
The strand bias for each SBS type is calculated as the ratio of SBS on the non-transcribed (coding) versus the transcribed (non-coding) strand.
The statistical significance of the differences between the mutational frequencies on the non-transcribed and the
transcribed strand (equal to 0.5, as expected by chance) is assessed using a chi-squared test followed by the Benjamini-
Hochberg procedure for multiple testing corrections (only samples with at least 1 mutations on the non-transcribed or on the transcribed strand are considered).
Two tables are shown to display the 6 SBS types in both orientations.


**Table 4. SBS distribution by functional region**
Count and percentages of SBS in genomic regions based on the Func.refGene annotation.


**Table 5. Strand bias by functional region**
Counts of the strand bias for the 6 SBS types in different functional regions.


**Table 6. SBS distribution per chromosome**
Counts of SBS per chromosome for the six SBS types.
The correlation between SBS counts and chromosome size is calculated using a Pearson correlation test.


**Panel 1. Trinucleotide sequence context of SBS on the genomic sequence**
The trinucleotide sequence context takes into consideration the flanking base in 5' and in 3' of the SBS.
SBS counts and frequency data are shown as tables, heatmaps or bar graphs. The heatmap colors are scaled to the maximum value of the corresponding table. The bar graph is scaled to the maximum frequency value (total number of mutation by SBS type is shown in parenthesis).



**Panel 2. Stranded analysis of trinucleotide sequence context of SBS**
SBS within their trinucleotide sequence context are counted on the non-transcribed and transcribed strands of the gene region they are located in. Counts and frequencies are shown as tables or bar graphs.
Only SBS with strand orientation annotation are considered in this analysis (strand annotation retrieved from RefSeq database).



--------------------------------------------------------------------------------------------------------------------------------------------------

**Contact**

[e-mail]; [e-mail]

--------------------------------------------------------------------------------------------------------------------------------------------------

**Code**

The source code is available on `GitHub`__

.. __: https://github.com/IARCbioinfo/mutspec.git

</help>

<citations>
    <citation type="bibtex">
        @article{ardin_mutspec:_2016,
            title = {{MutSpec}: a Galaxy toolbox for streamlined analyses of somatic mutation spectra in human and mouse cancer genomes},
            volume = {17},
            issn = {1471-2105},
            doi = {10.1186/s12859-016-1011-z},
            shorttitle = {{MutSpec}},
            abstract = {{BACKGROUND}: The nature of somatic mutations observed in human tumors at single gene or genome-wide levels can reveal information on past carcinogenic exposures and mutational processes contributing to tumor development. While large amounts of sequencing data are being generated, the associated analysis and interpretation of mutation patterns that may reveal clues about the natural history of cancer present complex and challenging tasks that require advanced bioinformatics skills. To make such analyses accessible to a wider community of researchers with no programming expertise, we have developed within the web-based user-friendly platform Galaxy a first-of-its-kind package called {MutSpec}.
        {RESULTS}: {MutSpec} includes a set of tools that perform variant annotation and use advanced statistics for the identification of mutation signatures present in cancer genomes and for comparing the obtained signatures with those published in the {COSMIC} database and other sources. {MutSpec} offers an accessible framework for building reproducible analysis pipelines, integrating existing methods and scripts developed in-house with publicly available R packages. {MutSpec} may be used to analyse data from whole-exome, whole-genome or targeted sequencing experiments performed on human or mouse genomes. Results are provided in various formats including rich graphical outputs. An example is presented to illustrate the package functionalities, the straightforward workflow analysis and the richness of the statistics and publication-grade graphics produced by the tool.
        {CONCLUSIONS}: {MutSpec} offers an easy-to-use graphical interface embedded in the popular Galaxy platform that can be used by researchers with limited programming or bioinformatics expertise to analyse mutation signatures present in cancer genomes. {MutSpec} can thus effectively assist in the discovery of complex mutational processes resulting from exogenous and endogenous carcinogenic insults.},
            pages = {170},
            number = {1},
            journaltitle = {{BMC} Bioinformatics},
            author = {Ardin, Maude and Cahais, Vincent and Castells, Xavier and Bouaoun, Liacine and Byrnes, Graham and Herceg, Zdenko and Zavadil, Jiri and Olivier, Magali},
            date = {2016},
            pmid = {27091472},
            keywords = {Galaxy, Mutation signatures, Mutation spectra, Single base substitutions}
        }
    </citation>
</citations>

</tool>