<tool id="kegg_identification" name="KEGG pathways mapping and coverage" version="2019.01.23">
    <description>[PathView]</description>
    <requirements>
        <requirement type="package" version="1.18.0">bioconductor-keggrest</requirement>
    </requirements>
    <command detect_errors="exit_code"><![CDATA[
        Rscript $__tool_directory__/kegg_identification.R  
        
        #if $input.ids == "text"
            --id_list="$input.txt"
        #else
            --input="$input.file"
            --id_column="$input.ncol"
            --header="$input.header"
        #end if
        
        --id_type="$id_type"
        --output="$output1"
        --nb_pathways="$nb_pathways"
        --species="$species"

    ]]></command>
    <inputs>
        <conditional name="input" >
            <param name="ids" type="select" label="Enter your IDs (Entrez gene IDs, KEGG IDs, UniProt Accession number)" help="Copy/paste or from a file (e.g. table)" >
                <option value="text">Copy/paste your IDs</option>
                <option value="file" selected="true">Input file containing your IDs</option>
            </param>
            <when value="text" >
                <param name="txt" type="text" label="Copy/paste your IDs" help='IDs must be separated by tab, space or carriage return into the form field, for example: hsa:3306 hsa:22948' >
                    <sanitizer invalid_char=''>
                        <valid initial="string.printable">
                            <remove value="&apos;"/>
                        </valid>
                        <mapping initial="none">
                            <add source="&apos;" target="__sq__"/>
                        </mapping>
                    </sanitizer>
                </param>
            </when>
            <when value="file" >
                <param name="file" type="data" format="txt,tabular,tsv" label="Select your file" help="" />
                <param name="header" type="boolean" checked="true" truevalue="true" falsevalue="false" label="Does file contain header?" />
                <param name="ncol" type="text" value="c1" label="Column number of IDs" help='For example, fill in "c1" if it is the first column, "c2" if it is the second column and so on'>
                    <validator type="regex" message="Please enter a column number, for example: 'c1' for the first column">[c]{0,1}[0-9]+</validator>
                </param>
            </when>
        </conditional>
        <param name="id_type" type="select" label="Select IDs" >
            <option value="ncbi-geneid" selected="true">Entrez Gene ID</option>
            <option value="kegg-id">KEGG gene ID</option>
            <option value="uniprot">UniProt Accession number</option>
            
        </param>
        <param name="species" type="select" label="Species">
            <option value="hsa">Human (Homo sapiens)</option>
            <option value="mmu">Mouse (Mus musculus)</option>
            <option value="rno">Rat (Rattus norvegicus)</option>
        </param>
        <param type="integer" name="nb_pathways" label="Set number of pathways to be displayed" value="10" help="Pathways are sorted by percent of mapping gene by pathway in descending order"/>
    </inputs>
    <outputs>
        <data name="output1" format="tsv" />
    </outputs>
    <tests>
        <test>
            <conditional name="input" >
                <param name="ids" value="file"/>
                <param name="file" value="SPZ.soluble_kegg_id.txt" />
                <param name="header" value="true" />
                <param name="ncol" value="c2" /> 
            </conditional>
            <param name="id_type" value="kegg-id" />
            <param name="species" value="hsa" />
            <param name="nb_pathways" value="20" />
            <output name="output1" value="test.tsv" />
        </test>
    </tests>
    <help><![CDATA[

**Description**

This tool maps a list of identifiers to all KEGG pathways and returns a list of KEGG pathways sorted by the percentage of coverage for each pathway. This is done by computing the number of KEGG genes IDs from your list divided by the total number of KEGG genes ID of the selected species for each KEGG pathway. 

It allows you to directly identify KEGG pathways that are the most covered by your gene/protein list. 

-----

**Input**

Input can be either a list of IDs or a file containing multiple columns but with at least one column of IDs (e.g. hsa:04970). 
Input IDs type can be Entrez gene ID (e.g. 2243), KEGG gene ID (e.g. hsa:2243 in homo sapiens) or Uniprot accession number (e.g. P02671).

.. class:: warningmark  

If you use Uniprot accession number, it will be converted to KEGG gene ID; this step can be time consuming. KEGG database being "gene-centric" we recommend the use of Entrez gene IDs.

If your input file contains other type of ID (than those allowed), please use the ID_Converter tool.

In copy/paste mode, the number of IDs considered in input is limited to 5000.

-----

**Parameters**

"Set number of pathways to be displayed": by default the number of pathway to be displayed is set to 10 and sorted in descending order. 

"Species": three species are supported: Human (Homo sapiens), Mouse (Mus musculus) and Rat (Rattus norvegicus).

-----

**Output:**

The output is a tabular file (.tsv) with the following columns:

* **Pathway_ID:** KEGG pathway identifier (e.g. hsa04970)
* **Description:** name of the pathway as in KEGG
* **Ratio IDs mapped/total IDs (%):** pathway coverage in percentage
* **nb KEGG genes IDs mapped in the pathway:** number of KEGG genes from your list mapped to the KEGG pathway
* **nb total of KEGG genes IDs present in the pathway:** total number of KEGG genes present in the KEGG pathway 

-----

.. class:: infomark

**Data source (release date)**

Pathways and KEGG genes IDs are collected via KEGGREST package. 

User manual / Documentation: KEGGREST Bioconductor package https://bioconductor.org/packages/3.1/bioc/html/KEGGREST.html

-----

.. class:: infomark

**Galaxy integration**

David Christiany, Florence Combes, Yves Vandenbrouck - CEA, INSERM, CNRS, Grenoble-Alpes University, BIG Institute, FR

Sandra Dérozier, Olivier Rué, Valentin Loux - INRA, Paris-Saclay University, MAIAGE Unit, Migale Bioinformatics platform, FR

This work has been partially funded through the French National Agency for Research (ANR) IFB project.

Help: contact@proteore.org for any questions or concerns about this tool.

    ]]></help>
    <citations>
        <citation type="bibtex">
@misc{githubKEGGREST,
  title = {KEGGREST: Client-side REST access to KEGG},
  author = {Dan Tenenbaum},
  year = {2018},
  note = {R package version 1.18.1},
  publisher = {GitHub},
  journal = {GitHub repository},
  url = {https://github.com/Bioconductor/KEGGREST},
}</citation>
    </citations>
</tool>