<?xml version="1.0"?>
<!--
# Copyright (C) 2015 INRA
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program.  If not, see <http://www.gnu.org/licenses/>.
-->
<tool id="FROGS_clustering" name="FROGS Clustering swarm" version="2.3.0">
	<description>Step 2 in metagenomics analysis : clustering.</description>
 	<requirements>
                <requirement type="package" version="2.0.1">frogs</requirement>
        </requirements>
        <stdio>
                <exit_code range="1:" />
                <exit_code range=":-1" />
        </stdio>
	<command>
		clustering.py 
		                --nb-cpus $nb_cpus
		                --distance $maximal_distance
		                --input-fasta $sequence_file
		                --input-count $count_file
		                --output-biom $abundance_biom
		                --output-fasta $seed_file
		                --output-compo $swarms_composition
		                $denoising     
	</command>
	<inputs>
		<!-- Files -->
		<param format="fasta" name="sequence_file" type="data" label="Sequences file" help="The sequences file (format: fasta)." optional="false" />
		<param format="tabular" name="count_file" type="data" label="Count file" help="It contains the count by sample for each sequence (format: TSV)." optional="false" />
		<!-- Parameters -->
		<param name="nb_cpus" type="hidden" label="CPU number" help="The maximum number of CPUs used." value="1" />
		<param name="maximal_distance" type="integer" label="Aggregation distance" help="Maximum number of differences between sequences in each aggregation step." value="3" min="1" max="15" optional="false" />
		<param name="denoising" type="boolean" checked="true" truevalue="--denoising" falsevalue="" label="Performe denoising clustering step?" help="If checked, clustering will be perform in two steps, first with distance = 1 and then with your input distance"/>
	</inputs>
	<outputs>
		<data format="fasta" name="seed_file" label="${tool.name}: seed_sequences.fasta" from_work_dir="seeds.fasta"/>
		<data format="biom1" name="abundance_biom" label="${tool.name}: abundance.biom" from_work_dir="abundance.biom" />
		<data format="tabular" name="swarms_composition" label="${tool.name}: swarms_composition.tsv" from_work_dir="swarms.tsv"/>
	</outputs>
	<tests>
		<test>
			<param name="sequence_file" value="references/01-prepro.fasta"/>
			<param name="count_file" value="references/01-prepro.tsv"/>
			<param name="maximal_distance" value="3"/>
			<param name="denoising" value="true"/>
			<output name="seed_file" file="references/02-clustering.fasta" compare="sim_size" delta="0" />
                        <!-- output name="abundance_biom" file="references/02-clustering.biom"  -->
                        <!-- Voila deux autres facon de comparer: (Mais ca ne marche pas dans ce cas car les fichiers générés par planemo sont vraiments différents comparé à nos test manuels (cf. /tmp/frogs-test-result-olivier /tmp/frogs-test-result-olivier2) -->
                        <!-- cf. https://docs.galaxyproject.org/en/latest/dev/schema.html#tool-tests-test-output -->
			<!--output name="abundance_biom" file="references/02-clustering.biom" compare="sim_size" delta="10"/-->                    
			<!--output name="abundance_biom" file="references/02-clustering.biom" compare="diff" lines_diff="1"/-->
			<output name="swarms_composition" file="references/02-clustering_compo.tsv" compare="sim_size" delta="0"  />
		</test>	
	</tests>
	<help>

.. image:: static/images/FROGS_logo.png 
   :height: 144
   :width: 110


.. class:: infomark page-header h2

What it does

Single-linkage clustering on sequences.


.. class:: infomark page-header h2

Inputs/Outputs

.. class:: h3

Inputs

**Sequences file**:

The sequence file with all samples sequences (format `FASTA &lt;https://en.wikipedia.org/wiki/FASTA_format&gt;`_). These sequences are dereplicated: strictly identical sequence are represented only one and the initial count is kept in count file.

The sequence ID must be "sequenceID;size=X" with X equal to the total abundance among all samples.

*It corresponds to one output of FROGS Pre-process tools.*

**Count file**:

This file contains the count of all uniq sequences in each sample (format `TSV &lt;https://en.wikipedia.org/wiki/Tab-separated_values&gt;`_).
 
Example::

     #id	splA	splB
     seq1	1289	2901
     seq2	3415	0	
 

.. class:: h3

Outputs

**Abundance file** (abundance.biom):

 The abundance of each cluster in each sample (format `BIOM &lt;http://biom-format.org/&gt;`_). This format is widely used in metagenomic softwares.


**Clusters seeds** (seed_sequences.fasta):

 The clusters representative sequences (format `FASTA &lt;https://en.wikipedia.org/wiki/FASTA_format&gt;`_).

   
**Clusters composition** (swarms_composition.tsv):

 A text file representing the read composition of each cluster (format txt). Each line represents one cluster and is composed of read identifier separated by space.


.. class:: infomark page-header h2

How it works

.. csv-table:: 
   :header: "Steps", "With denoising", "Without denoising"
   :widths: 5, 150, 150
   :class: table table-striped

   "1", "Sorting the reads by their abundance", "Sorting the reads by their abundance"
   "2", "Clusters the reads (`Swarm &lt;https://github.com/torognes/swarm&gt;`_). The distance parameter is 1", "/"
   "3", "Sorting the pre-clusters by their abundance", "/"
   "4", "Clusters the pre-clusters (`Swarm &lt;https://github.com/torognes/swarm&gt;`_) with the distance you specify", "Clusters the reads (`Swarm &lt;https://github.com/torognes/swarm&gt;`_) with the distance you specify"

**Swarm focus**

Swarm use an iterative growth process and the use of sequence abundance values to delineate OTUs.
  
.. image:: static/images/FROGS_cluster_swarm.png
   :height: 223
   :width: 666	

In each groth step the sequence of the previous step is used to find the others sequences with a number of differences inferior or equal to the "Aggregation distance".

After agregation Swarm refines the clusters by looking at the abundancies along the connections. Theoritically the abundances must decrease when you are going away from the seed (which is often the most abundant sequence). If this abundance raises again it means that two different clusters are connected by some poorly abundant sequences, so swarm cut the connection.

	
.. class:: infomark page-header h2

Advices

The denoising step allows to build very fine clusters with minimal differences. In this case, the number of differences is equal at 1 between sequences of each crowns. This first clustering is extremly quick. After the denoising, a second swarm is run with an aggregation distance >1 as you have configured, between seeds from this first clustering.
		
To have some metrics on your clusters, you can use the tool **FROGS Clusters Stat**.


----

**Contact**

Contacts: frogs@inra.fr

Repository: https://github.com/geraldinepascal/FROGS

Please cite the FROGS Publication: *Escudie F., Auer L., Bernard M., Cauquil L., Vidal K., Maman S., Mariadassou M., Hernadez-Raquet G., Pascal G., 2015. FROGS: Find Rapidly OTU with Galaxy Solution. In: The environmental genomic Conference, Montpellier, France,* http://bioinfo.genotoul.fr/fileadmin/user_upload/FROGS_2015_GE_Montpellier_poster.pdf

Depending on the help provided you can cite us in acknowledgements, references or both.
	</help>
	<citations>
		<citation type="doi">10.7287/peerj.preprints.386v1</citation>
	</citations>
</tool>