--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/raceid_clustering.xml	Thu Nov 22 04:43:57 2018 -0500
@@ -0,0 +1,213 @@
+<tool id="raceid_clustering" name="Clustering using RaceID" version="@VERSION_RACEID@.@VERSION_PACKAGE@.1" >
+    <description>performs clustering, outlier detection, dimensional reduction</description>
+    <macros>
+        <import>macros.xml</import>
+        <import>macros_cluster.xml</import>
+    </macros>
+    <expand macro="requirements" />
+    <version_command><![CDATA[
+Rscript '$__tool_directory__/scripts/cluster.R' @GET_VERSION@
+]]></version_command>
+
+    <command detect_errors="exit_code"><![CDATA[
+#set bin = 'cluster.R'
+Rscript '$__tool_directory__/scripts/$bin' '$userconf' 2>&1 > '$outlog'
+    ]]></command>
+
+    <configfiles>
+        <configfile name="userconf" ><![CDATA[
+@STRING2VECTOR@
+
+@CLUSTER_CHEETAH@
+
+]]></configfile>
+    </configfiles>
+    <inputs>
+        <param name="inputrds" type="data" format="rdata" label="Input RaceID RDS" help="Requires the RDS output from the normalisation stage" />
+        <section name="clust" title="Clustering" expanded="true" >
+            <!-- CompDist -->
+            <param name="metric" type="select" label="Distance Metric" >
+                <option value="pearson" selected="true" >Pearson</option>
+                <option value="spearman">Spearman</option>
+                <option value="logpearson">Log Pearson</option>
+                <option value="euclidean">Euclidean</option>
+            </param>
+            <!-- ClustExp -->
+            <param name="funcluster" type="select" label="Clustering method" >
+                <option value="kmedoids" selected="true" >K-medoids</option>
+                <option value="kmeans">K-means</option>
+                <option value="hclust">H-Clust</option>
+            </param>
+            <expand macro="use_defaults_no" >
+                <!-- CompDist -->
+                <param name="fselect" type="boolean" value="true" label="Perform feature selection" />
+                <param name="knn" type="integer" min="0" optional="true" label="KNN" help="Number of nearest neighbours for imputing gene expression" /><!-- 0: NULL -->
+                <!-- ClustExp -->
+                <param name="sat" type="boolean" checked="true" label="Saturation-based clustering?" help="Determine number of clusters on saturation point of the mean within-cluster dispersion as a function of the cluster number." />
+                <param name="clustnr" type="integer" min="0" value="30" label="Max number of clusters using Saturation-by-mean" help="Max number of clusters for the derivation of the cluster number by the saturation of mean within-cluster-dispersion." />
+                <param name="samp" type="integer" min="0" optional="true" label="Sample random number of cells" help="Number of random sample of cells used for the inference of cluster number and Jaccard similarity" /><!-- 0:NULL -->
+                <param name="cln" type="integer" min="0" optional="true" label="Number of clusters" /><!-- 0:Null -->
+                <param name="bootnr" type="integer" min="0" value="50" label="Number of booststrapping runs" />
+                <param name="rseed" type="integer" value="17000" label="Random seed" />
+            </expand>
+        </section>
+        <section name="outlier" title="Outliers" expanded="true" >
+            <!-- Find Outliers -->
+            <param name="outminc" type="integer" min="0" value="5" label="Minimum Transcripts" help="minimal transcript count of a gene in a clusters to be tested for being an outlier gene" />
+            <param name="outlg" type="integer" min="1" value="2" label="Minimum Genes" help="Minimum number of outlier genes required for being an outlier cell" />
+            <!-- RFCorrect -->
+            <param name="final" type="boolean" value="true" label="Plot Final Clusters?" help="Reclassification of cell types using out-of-bag analysis is performed based on the final clusters after outlier identification. If 'FALSE', then the cluster partition prior to outlier identification is used for reclassification." />
+            <expand macro="use_defaults_no" >
+                <!-- Find Outliers -->
+                <param name="probthr" type="float" min="0" value="0.001" label="Outlier Probability Threshold" help="Probability threshold for the above specified minimum number of genes to be an outlier cell. This probability is computed from a negative binomial background model of expression in a cluster" />
+                <param name="outdistquant" type="float" min="0" max="1" value="0.95" label="Outlier Distance Quantile" help="Outlier cells are merged to outlier clusters if their distance smaller than the outdistquant-quantile of the distance distribution of pairs of cells in the orginal clusters after outlier removal" />
+                <!-- RFCorrect -->
+                <param name="nbtree" type="integer" optional="true" label="Number of trees to be built" /><!-- 0:Null -->
+                <param name="nbfactor" type="integer" min="0" value="5" label="Tree Factor" help="Number of trees based on the number of cells multiplied by this factor. Effective only if the number of trees parameter is set to 0" />
+                <param name="rfseed" type="integer" value="12345" label="Random Seed" />
+            </expand>
+        </section>
+        <section name="tsne" title="tSNE and FR" expanded="true" >
+            <!-- CompTSNE -->
+            <param name="perplexity" type="integer" min="0" value="30" label="Perplexity" help="Perplexity of the t-SNE map" />
+            <!-- CompFR -->
+            <param name="knn" type="integer" min="0" value="10" label="KNN" help="Number of nearest neighbours used for the inference of the Fruchterman-Rheingold layout" />
+            <expand macro="use_defaults_no" >
+                <!-- CompTSNE -->
+                <param name="initial_cmd" type="boolean" checked="true" label="tSNE map initialised by classical multidimensional scaling" />
+                <param name="rseed_tsne" type="integer" value="15555" label="Random Seed (tSNE)" />
+                <!-- CompFR -->
+                <param name="rseed_fr" type="integer" min="0" value="15555" label="Random Seed (FR)" />
+            </expand>
+        </section>
+        <section name="extra" title="Extra Parameters" expanded="false" >
+            <param name="tablelim" type="integer" min="1" value="25" label="Table Limit" help="Top N genes to print per cluster" />
+            <param name="plotlim" type="integer" min="1" value="10" label="Plot Limit" help="Top N genes to plot. Must be less than or equal to the Table Limit" />
+            <param name="foldchange" type="float" min="0" value="1" label="Fold change" />
+            <param name="pvalue" type="float" min="0" max="1" value="0.01" label="P-value Cutoff" help="P-value cutoff for the inference of differential gene expression" />
+        </section>
+    </inputs>
+    <outputs>
+        <data name="outpdf" format="pdf" label="${tool.name} on ${on_string}: PDF Report" />
+        <data name="outrdat" format="rdata" label="${tool.name} on ${on_string}: RDS" />
+        <data name="outgenelist" format="tabular" label="${tool.name} on ${on_string}: Cluster - Genes per Cluster" />
+        <data name="outlog" format="txt" label="${tool.name} on ${on_string}: Log" >
+            <filter>use_log</filter>
+        </data>
+    </outputs>
+
+    <tests>
+        <test>
+            <param name="inputrds" value="matrix.filter.rdat" />
+            <output name="outgenelist" value="matrix2.genelist" />
+            <output name="outrdat" value="matrix2.rdat" compare="sim_size" delta="15" />
+            <output name="outpdf" value="matrix2.pdf" compare="sim_size" delta="10" />
+        </test>
+        <test>
+            <!-- defaults, but manually specified. No opts, no CC. Generates identical to above -->
+            <param name="inputrds" value="matrix.filter.rdat" />
+            <section name="clust" >
+                <param name="metric" value="pearson" />
+                <param name="funcluster" value="kmedoids" />
+                <expand macro="test_nondef" >
+                    <param name="fselect" value="true" />
+                    <param name="sat" value="true" />
+                    <param name="clustnr" value="30" />
+                    <param name="bootnr" value="50" />
+                    <param name="rseed" value="17000" />
+                </expand>
+            </section>
+            <section name="outlier" >
+                <param name="outminc" value="5" />
+                <param name="outlg" value="2" />
+                <param name="final" value="false" />
+                <expand macro="test_nondef" section_name="outlier" >
+                    <param name="probthr" value="0.001" />
+                    <param name="outdistquant" value="0.95" />
+                    <param name="rfseed" value="12345" />
+                    <param name="nbfactor" value="5" />
+                </expand>
+            </section>
+            <section name="tsne" >
+                <param name="perplexity" value="30" />
+                <param name="knn" value="10" />
+                <expand macro="test_nondef" section_name="tsne" >
+                    <param name="initial_cmd" value="true" />
+                    <param name="rseed_tsne" value="15555" />
+                    <param name="rfseed_fr" value="15555" />
+                </expand>
+            </section>
+            <output name="outgenelist" value="intestinal.genelist" />
+            <output name="outpdf" value="intestinal.pdf" compare="sim_size" delta="50" />
+        </test>
+        <test>
+            <!-- Advanced. Opts, CC used  -->
+            <param name="inputrds" value="matrix.filter.rdat" />
+            <section name="clust" >
+                <param name="metric" value="euclidean" />
+                <param name="funcluster" value="hclust" />
+                <expand macro="test_nondef" >
+                    <param name="fselect" value="false" />
+                    <param name="knn" value="5" />
+                    <param name="sat" value="false" />
+                    <param name="samp" value="10" />
+                    <param name="cln" value="10" />
+                    <param name="clustnr" value="10" />
+                    <param name="bootnr" value="30" />
+                    <param name="rseed" value="17000" />
+                </expand>
+            </section>
+            <section name="outlier" >
+                <param name="outminc" value="3" />
+                <param name="outlg" value="5" />
+                <param name="final" value="true" />
+                <expand macro="test_nondef" >
+                    <param name="probthr" value="0.01" />
+                    <param name="outdistquant" value="0.5" />
+                    <param name="rfseed" value="12345" />
+                    <param name="nbfactor" value="5" />
+                    <param name="nbtree" value="10" />
+                </expand>
+            </section>
+            <section name="tsne" >
+                <param name="perplexity" value="20" />
+                <param name="knn" value="6" />
+                <expand macro="test_nondef" >
+                    <param name="initial_cmd" value="false" />
+                    <param name="rseed_tsne" value="15555" />
+                    <param name="rfseed_fr" value="15555" />
+                </expand>
+            </section>
+            <output name="outgenelist" value="intestinal_advanced.genelist" />
+            <output name="outpdf" value="intestinal_advanced.pdf" compare="sim_size" delta="150" />
+        </test>
+    </tests>
+    <help><![CDATA[
+RaceID3
+=========
+
+RaceID is a clustering algorithm for the identification of cell types from single-cell RNA-sequencing data. It was specifically designed for the detection of rare cells which correspond to outliers in conventional clustering methods.
+
+This module performs clustering, and outlier detection and ultimately tells you how well defined your clusters are (even if the resultant tSNE plots look messy).
+
+The tool generates the following:
+
+ * A list of the most differentially expressed genes in each cluster
+ * Cluster stability plots:
+     * The mean within-cluster dispersion as a function of the cluster number and highlights the saturation point inferred based on the saturation criterion applied by RaceID3. The number of clusters where the change in within-cluster dispersion upon adding further clusters approaches linear behaviour demarcates the saturation point is highlighted in blue.
+         * The point where this flattens out gives you a rough estimate of how many clusters there are in your analysis.
+     * A scatter plot showing the gene expression variance as a function of the mean and the inferred polynomial fit of the background model, as well as a local regression.
+        * This tells you which genes are the most significant against a background model of random expression.
+     * A Jaccard stability plot which tells you how well defined your clusters are prior to outlier identification.
+        * Good stable clusters should near the 0.8 mark, but 0.6 is acceptable, and for a large number of clusters, one or two low scoring clusters are also acceptable.
+ * Heatmaps:
+     * The initial and final clustering (as determined using random forest)
+     * For each of the most differentially expressed genes in each cluster
+
+The tool requires the RData input from the previous filtering / normalisation / confounder removal step to work.
+
+
+]]>
+    </help>
+    <expand macro="citations" />
+</tool>