<tool id="csem" name="CSEM: Multi-read Allocation for ChIP-seq" version="1.0.0">
  
  <description></description>
  
  <parallelism method="basic"></parallelism>
  
  <requirements>
	  <requirement type="binary">csem</requirement>
	  <requirement type="package">bowtie</requirement>
  </requirements>

  <command interpreter="perl">
    csem_wrapper.pl 
      ## Input file name
      $InputParams.Input
      ## Input file format (FASTA or FASTQ)
      $InputParams.InfileFormat
      ## Output file name
      $out_csem
      ## Output file format
      $OutfileFormat
      ## Reference genome idnex for Bowtie
      $index.fields.path$index
      ## Generate pseudo-tags?
      $pseudoTag
      ## Bowtie settings (Max num of mismatches, Max num of aligned positions)
      #if $bowtieParams.bSettingsType == "preSet"
	2
	99
      #else
	$bowtieParams.Mismatch
	$bowtieParams.SuppressAlign
      #end if
      ## CSEM settings (window size, number of iterations)
      #if $csemParams.cSettingsType == "preSet"
      	101
	200
      #else
	$csemParams.windowSize
	$csemParams.nIteration
      #end if
      ## Number of cores to use
      8
  </command>

  <inputs>
	<param name="index" type="select" label="Select a reference genome" help="If your genome of interest is not listed - contact Galaxy team.">
		<options from_data_table="bowtie_indexes">
			<filter type="sort_by" column="2" />
			<validator type="no_options" message="No indexes are available" />
		</options>
	</param>
	<param name="InfileFormat" type="select" label="Select file format to process" help="Bowtie accepts FASTA or FASTQ file formats.">
		<option value="fasta">FASTA</option>
		<option value="fastq">FASTQ</option>
	</param>
	<conditional name="InputParams">
		<when value="fasta">
			<param name="Input" type="data" format="fasta" label="FASTA file"/>
		</when>
		<when value="fastq">
			<param name="Input" type="data" format="fastq,fastqsanger,fastqillumina,fastqsolexa" label="FASTQ file"/>
		</when>
	</conditional> <!-- InputParams -->
	<param name="OutfileFormat" type="select" label="Select file format to export" help="Multi-read allocator can export results into BED or GFF file formats, or as a table.">
		<option value="bed">BED</option>
		<option value="gff">GFF</option>
		<option value="table">table</option>
	</param>
	<param name="pseudoTag" type="select" label="Generate pseudo-tags?" help="See section 'Pseudo-tags' in the help below for more details.">
		<option value="N">NO</option>
		<option value="Y">YES</option>
	</param>
	<param name="bSettingsType" type="select" label="Bowtie settings to use" help="For most mapping applications, use the 'Commonly used' settings. If you want full control, use 'Full parameter list'.">
		<option value="preSet">Commonly used</option>
		<option value="full">Full parameter list</option>
	</param>		
	<conditional name="bowtieParams">
		<when value="preSet" />
		<when value="full">
			<param name="Mismatch" type="integer" value="2" label="Maximum number of mismatches permitted (-v)" help="May be 0, 1, 2, or 3." />
			<param name="SuppressAlign" type="integer" value="99" label="Suppress all alignments for a read if more than n reportable alignments exist (-m)" help="99 is appropriate for most cases. Use -1 for no limit." />
		</when> <!-- full -->
	</conditional> <!-- bowtieParams -->
	<param name="cSettingsType" type="select" label="CSEM settings to use" help="For most multi-read allocation applications, use the 'Commonly used' settings. If you want full control, use 'Full parameter list'.">
		<option value="preSet">Commonly used</option>
		<option value="full">Full parameter list</option>
	</param>		
	<conditional name="csemParams">
		<when value="preSet" />
		<when value="full">
			<param name="windowSize" type="integer" value="101" label="Window size for the multi-read allocator" help="Set window size to some odd number close to the half of average fragment length." />
			<param name="nIteration" type="integer" value="200" label="Number of iterations for the multi-read allocator" help="200 is appropriate for most cases." />
		</when> <!-- full -->
	</conditional> <!-- csemParams -->
  </inputs>

  <outputs>
	<data format="tabular" name="out_csem">
		<change_format>
			<when input="OutfileFormat" value="bed" format="bed" />
			<when input="OutfileFormat" value="gff" format="gff" />
		</change_format>
	</data>
  </outputs>

  <tests>
  	<test>
		<param name="index" value="eschColi_K12" />
		<param name="InfileFormat" value="fasta" />
		<param name="Input" ftype="fasta" value="csem_test1_in.fa" />
		<param name="OutfileFormat" value="bed" />
		<param name="pseudoTag" value="N" />
		<param name="bSettingsType" value="preSet" />
		<param name="cSettingsType" value="preSet" />
		<output name="out_csem" ftype="bed" file="csem_test1_out_original_sorted.bed" sort="True" />
	</test>
	<test>
		<param name="index" value="eschColi_K12" />
		<param name="InfileFormat" value="fastq" />
		<param name="Input" ftype="fastq" value="csem_test1_in.fq" />
		<param name="OutfileFormat" value="bed" />
		<param name="pseudoTag" value="Y" />
		<param name="bSettingsType" value="preSet" />
		<param name="cSettingsType" value="preSet" />
		<output name="out_csem" ftype="bed" file="csem_test1_out_pseudo_sorted.bed" sort="True" />
	</test>
  </tests>

  <help>

**What it does**

CSEM (ChIP-Seq multi-read allocation using E-M algorithm) is a multi-read allocation algorithm. *Multi-reads* are the reads that map to multiple locations on the reference genome. Most common analysis of ChIP-seq data relies on using only reads that map uniquely to relevant reference genome (*uni-reads*). This can lead to the omission of up to 30 % of alignable reads. Chung et al. (2011) illustrated that incorporation of multi-reads significantly increases sequencing depths, leads to detection of novel peaks that are not otherwise identifiable with uni-reads, and improves detection of peaks in low mappable regions. The computational and experimental results established that multi-reads can be of critical importance for studying DNA-protein interactions in highly repetitive regions of genomes with ChIP-seq experiments. Output from CSEM can be used with other peak callers such as MOSAiCS and MACS to identify peaks that are in both high and low mappable regions of genomes.

Please cite: Chung D, Kuan PF, Li B, SanalKumar R, Liang K, Bresnick E, Dewey C, and Keles S (2011),
"Discovering transcription factor binding sites in highly repetitive regions of genomes
with multi-read analysis of ChIP-Seq data," PLoS Computational Biology, 7(7): e1002111.

------

**Input formats**

CSEM accepts short reads aligned using bowtie as input. Bowtie accepts single-end reads, in FASTA or FASTQ format, as input. Quality scores of reads are ignored.

------

**Pseudo-tags**

For each read in the alignment file, CSEM estimates the fraction of the read allocated to each of its alignments. This fraction reflects the degree of confidence in each particular alignment. Currently, only the peak caller MOSAiCS can accept fractional of reads as input. However, you can incorporate multi-reads into ChIP-seq analysis with your favoriate peak-caller by utilizing this pseudo-tag functionality. Pseudo-tags are generated by assigning each multi-read to the location it maps to with the largest weight and filtering out multi-reads with weights less than 0.5. Although summarizing CSEM output as pseudo-tags decreases the number of utilized multi-reads, it still leads to a significant increase in the sequencing depth compared to using uni-reads alone and facilitates identification of  peaks in repetitive regions.

------

**Outputs**

Currently, results from CSEM can be exported into BED or GFF file formats, or as a table. Each line of the output file specifies a single alignment. The lines of the output file are ordered such that all of the unique read alignments appear first. If pseudo-tags are generated, *FRAC* equals to 1 for all reads if the output is a table and *score* is set to 1000 for all the reads in the BED and GFF formats.

If the output is a table, it has the following columns::

   Column    Description
   --------  --------------------------------------------------------
    1 RID    ID of a read
    2 CID    Chromosome of the alignment
    3 DIR    Strand of the alignment (+ or -)
    4 POS    Left-most position of the aligned read (the first base in a chromosome is numbered 1)
    5 FRAC   Fraction of the read allocated to the alignment (which is 1 for uni-reads)

If the output is in BED format, it has the following columns::

    Column        Description
    ------------  --------------------------------------------------------
    1 chrom       Chromosome of the alignment
    2 chromStart  Start position of the aligned read (the first base in a chromosome is numbered 0)
    3 chromEnd    End position of the aligned read (the first base in a chromosome is numbered 0)
    4 name        ID of a read
    5 score       1000 * fraction of the read allocated to the alignment (which is 1000 for uni-reads)
    6 strand      Strand of the alignment (+ or -)

If the output is in GFF format, it has the following columns::

    Column     Description
    ---------  --------------------------------------------------------
    1 seqname  Chromosome of the alignment
    2 source   Always "CSEM"
    3 feature  ID of a read
    4 start    Start position of the aligned read (the first base in a chromosome is numbered 1)
    5 end      End position of the aligned read (the first base in a chromosome is numbered 1)
    6 score    1000 * fraction of the read allocated to the alignment (which is 1000 for uni-reads)
    7 strand   Strand of the alignment (+ or -)
    8 frame    Always "."
    9 group    Always "."

    
  </help>
</tool>