--- a/macros.xml	Fri Feb 04 08:31:26 2022 +0000
+++ b/macros.xml	Fri Feb 11 14:14:38 2022 +0000
@@ -32,69 +32,39 @@
 
     <xml name="parameters_csv">
         <section name="ms_csv" title="Input MS Data as CSV" expanded="true">
-            <param label="ms" name="ms" type="data" format="csv"
-                   help="Features as columns, rows as samples. Column header mz_rt"/>
-            <param label="idmsms" name="idmsms" type="data" format="csv" optional="true"
-                   help="Optional idMSMS / MSe csv data.  same dim and names as ms required"/>
-            <param label="sample_name_column" name="sample_name_column" type="integer" value="1"
-                   help="Which column from the csv file contains sample names?"/>
-            <param label="feature_delimiter" name="feature_delimiter" type="text" value="_"
-                   help="Only required if ms input is set! How feature mz and rt are delimited in csv import column header e.g. ='-'"/>
-            <param label="retention_time_column" name="retention_time_column" type="integer" value="2"
-                   help="Which position in delimited column header represents the retention time (csv only)"/>
-            <param label="st" name="st" type="float" value="1" help="Sigma t - time similarity decay value.
-                   A recommended starting point is half the value of your average chromatographic peak width at half max (seconds))."/>
+            <param label="Input CSV" name="ms" type="data" format="csv"
+                   help="Features as columns, rows as samples. Column header in format mz_rt."/>
+            <param label="idMSMS" name="idmsms" type="data" format="csv" optional="true"
+                   help="Optional idMSMS / MSe csv data. Same dimension and names as in input CSV are required."/>
         </section>
     </xml>
 
-    <xml name="parameters_excluded">
-        <param label="MStag" name="MStag" type="text" optional="true"
-               help="Character string in 'taglocation' to designat MS / MSe files e.g. '01.cdf'"/>
-        <param label="idMSMStag" name="idMSMStag" type="text" optional="true"
-               help="Character string in 'taglocation' to designat idMSMS / MSe files e.g. '02.cdf'"/>
-        <param label="taglocation" name="taglocation" type="text" value="filepaths"
-               help="'filepaths' by default, 'phenoData[,1]' is another option. refers to xcms slot"/>
+    <xml name="parameters_xcms">
+        <section name="xcms" title="Input MS Data as XCMS" expanded="true">
+            <param name="input_xcms" label="Input XCMS" type="data" format="rdata.xcms.fillpeaks"
+                   help="Grouped feature data for clustering." />
+            <param label="Preserve phenotype" name="usePheno" type="boolean" truevalue="TRUE" falsevalue="FALSE" checked="true"
+                   help="Transfer phenotype data from XCMS object to Spec abundance file."/>
+        </section>
     </xml>
 
     <xml name="parameters_required">
-        <section name="required" title="Required Parameters" expanded="true">
-            <param label="sr" name="sr" type="float" value="0.5" help="Sigma r - correlational similarity decay value"/>
-            <param label="deepSplit" name="deepSplit" type="boolean" truevalue="TRUE" falsevalue="FALSE" checked="false"
-                   help="Controls how agressively the HCA tree is cut - see ?cutreeDynamicTree"/>
-            <param label="blocksize" name="blocksize" type="integer" value="2000"
-                   help="Number of features (scans?) processed in one block  =1000,"/>
-            <param label="mult" name="mult" type="integer" value="5"
-                   help="Internal value, can be used to influence processing speed/ram usage"/>
-            <param label="hmax" name="hmax" type="float" value="0.3"
-                   help="Precut the tree at this height, default 0.3 - see ?cutreeDynamicTree"/>
-            <param label="collapse" name="collapse" type="boolean" truevalue="TRUE" falsevalue="FALSE" checked="true"
-                   help="Reduce feature intensities to spectrum intensities?"/>
-            <param label="usePheno" name="usePheno" type="boolean" truevalue="TRUE" falsevalue="FALSE" checked="true"
-                   help="Transfer phenotype data from XCMS object to SpecAbund dataset?"/>
-            <!--
-            Currently not forwarded because the MSP is exported always manually afterwards
-            <param label="mspout" name="mspout" type="boolean" truevalue="TRUE" falsevalue="FALSE" checked="true" help="write msp formatted spectra to file?" />
-            -->
-            <param label="normalize" name="normalize" type="select" display="radio"
-                   help="Either 'none', 'TIC', 'quantile', or 'batch.qc' normalization of feature intensities.  see batch.qc overview in details. ">
-                <option value="none" selected="true">none</option>
-                <option value="TIC">TIC</option>
-                <option value="quantile">quantile</option>
-                <option value="batch.qc">batch.qc</option>
-            </param>
-            <param label="qc_inj_range" name="qc_inj_range" type="integer" value="20"
-                   help="How many injections around each injection are to be scanned for presence of QC samples when
-                         using batch.qc normalization? A good rule of thumb is between 1 and 3 times the typical
-                         injection span between QC injections. i.e. if you inject QC ever 7 samples, set this to
-                         between 7 and 21. Smaller values provide more local precision but make normalization sensitive
-                         to individual poor outliers (though these are first removed using the boxplot function outlier
-                         detection), while wider values provide less local precision in normalization but better
-                         stability to individual peak areas."/>
+        <param label="Sigma r" name="sr" type="float" value="0.5" help="Correlational similarity between features."/>
+        <param label="Correlation method" name="cor_method" type="select" display="radio"
+               help="Choose correlational method to be used - see [1] for details.">
+            <option value="pearson" selected="true">pearson</option>
+            <option value="everything">everything</option>
+            <option value="spearman">spearman</option>
+            <option value="kendall">kendall</option>
+        </param>
+        <param label="Maximum RT difference" name="maxt" value="60" type="float"
+               help="Maximum difference to calculate RT similarity - values beyond this are assigned zero similarity."/>
+    </xml>
 
-            <param label="minModuleSize" name="minModuleSize" type="integer" value="2"
-                   help="How many features must be part of a cluster to be returned? default = 2"/>
-            <param label="linkage" name="linkage" type="select" display="radio" value="average"
-                   help="Hierarchical clustering linkage method - see ?hclust">
+    <xml name="main_parameters">
+        <section name="clustering" title="Clustering" expanded="true">
+            <param label="Clustering linkage method" name="linkage" type="select" display="radio"
+                   help="Choose hierarchical clustering linkage method - see [2] for details.">
                 <option value="average" selected="true">average</option>
                 <option value="ward.D">ward.D</option>
                 <option value="ward.D2">ward.D2</option>
@@ -104,68 +74,82 @@
                 <option value="median">median</option>
                 <option value="centroid">centroid</option>
             </param>
+            <param label="Minimal cluster size" name="minModuleSize" type="integer" value="2"
+                   help="Minimal size (number of features) of a cluster."/>
+            <param label="Maximal tree height" name="hmax" type="float" value="0.3"
+                   help="Cut the Hierarchical Cluster Analysis tree at this height, see [3] for details."/>
+            <param label="Use deepSplit" name="deepSplit" type="boolean" truevalue="TRUE" falsevalue="FALSE" checked="false"
+                   help="Check to produce more smaller clusters, uncheck for fewer bigger clusters, see [3] for details."/>
+        </section>
 
-            <param label="mzdec" name="mzdec" type="integer" value="3"
-                   help="Number of decimal places used in printing m/z values"/>
-            <param label="cor_method" name="cor_method" type="select" display="radio" value="pearson"
-                   help="Which correlational method used to calculate 'r' - see ?cor">
-                <option value="pearson" selected="true">pearson</option>
-                <option value="everything">everything</option>
-                <option value="spearman">spearman</option>
-                <option value="kendall">kendall</option>
-            </param>
+        <section name="normalisation" title="Normalisation" expanded="true">
+            <conditional name="normalisation_method">
+                <param label="Normalisation method" name="normalize" type="select" display="radio"
+                       help="Choose method for normalization of feature intensities.">
+                    <option value="none" selected="true">none</option>
+                    <option value="TIC">TIC</option>
+                    <option value="quantile">quantile</option>
+                    <option value="batch.qc">batch.qc</option>
+                </param>
+                <when value="batch.qc">
+                    <param label="Metadata details" name="batch_order_qc" type="data" format="csv" optional="true"
+                           help="CSV with sample names (or indices, currently not handled) on rows and columns with:
+                           batch number ('batch'), position in sequence ('order'), and whether it is a QC sample or not
+                           ('qc' with true/false OR 'sampleType' with 'sample/qc/blank')."/>
+                    <param label="QC injection range" name="qc_inj_range" type="integer" value="20"
+                             help="How many injections around each injection are to be scanned for presence of QC samples?
+                             A good rule of thumb is between 1 and 3 times the typical
+                             injection span between QC injections. i.e. if you inject QC ever 7 samples, set this to
+                             between 7 and 21. Smaller values provide more local precision but make normalization sensitive
+                             to individual poor outliers (though these are first removed using the boxplot function outlier
+                             detection), while wider values provide less local precision in normalization but better
+                             stability to individual peak areas."/>
+                </when>
+            </conditional>
+        </section>
 
-            <param label="rt_only_low_n" name="rt_only_low_n" type="boolean" truevalue="TRUE" falsevalue="FALSE"
+        <section name="performance" title="Performance">
+            <param label="Blocksize" name="blocksize" type="integer" value="2000"
+                   help="Number of features processed in one block."/>
+            <param label="Blocksize factor" name="mult" type="integer" value="5"
+                   help="Factor to scale blocksize to influence processing speed."/>
+        </section>
+
+        <section name="msp_output_details" title="MSP output">
+            <param label="Merge MSP Files" name="merge_msp" type="boolean" truevalue="TRUE" falsevalue="FALSE"
+                   checked="true" help="Merge all MSP in one file or export one MSP per spectra."/>
+            <param label="m/z decimal places" name="mzdec" type="integer" value="6"
+                   help="Number of decimal places used in printing m/z values."/>
+            <!--
+            Currently not forwarded because the MSP is exported always manually afterwards
+            <param label="mspout" name="mspout" type="boolean" truevalue="TRUE" falsevalue="FALSE" checked="true" help="write msp formatted spectra to file?" />
+            -->
+        </section>
+
+        <section name="extras" title="Extras">
+            <param label="RT only low n" name="rt_only_low_n" type="boolean" truevalue="TRUE" falsevalue="FALSE"
                    checked="true"
                    help="At low injection numbers, correlational relationships of peak intensities may be unreliable.
-                   By defualt ramclustR will simply ignore the correlational r value and cluster on retention time alone.
+                   By default, RAMClustR will simply ignore the correlational Sigma r value and cluster on retention time alone.
                    If you wish to use correlation with at n less than 5, set this value to FALSE."/>
-            <param label="replace_zeros" name="replace_zeros" type="boolean" truevalue="TRUE" falsevalue="FALSE"
+            <param label="Replace zeros" name="replace_zeros" type="boolean" truevalue="TRUE" falsevalue="FALSE"
                    checked="true"
                    help="NA, NaN, and Inf values are replaced with zero, and zero values are sometimes returned from
                    peak peaking. When TRUE, zero values will be replaced with a small amount of noise, with noise level
-                   set based on the detected signal intensities for that feature. "/>
-            <param label="Merge MSP Files" name="merge_msp" type="boolean" truevalue="TRUE" falsevalue="FALSE"
-                   checked="true" help="Whether to merge all msp in one file or export one msp per spectra"/>
-        </section>
-    </xml>
-
-    <xml name="parameters_optional_xcms">
-        <section name="optional" title="Optional Parameters" expanded="false">
-            <param label="st" name="st" type="float" optional="true" help="Sigma t - time similarity decay value.
-                   A recommended starting point is half the value of your average chromatographic peak width at half max (seconds))."/>
-            <param label="fftempdir" name="fftempdir" type="text" optional="true"
-                   help="Valid path: if there are file size limitations on the default ff pacakge temp directory -
-                   getOptions('fftempdir') - you can change the directory used as the fftempdir with this option."/>
-            <param label="maxt" name="maxt" type="integer" optional="true"
-                   help="Maximum time difference to calculate retention similarity for - all values beyond this are assigned similarity of zero"/>
-        </section>
-    </xml>
-
-    <xml name="parameters_optional_csv">
-        <section name="optional" title="Optional Parameters" expanded="false">
-            <param label="fftempdir" name="fftempdir" type="text" optional="true"
-                   help="Valid path: if there are file size limitations on the default ff pacakge temp directory -
-                   getOptions('fftempdir') - you can change the directory used as the fftempdir with this option."/>
-            <param label="maxt" name="maxt" type="integer" optional="true"
-                   help="Maximum time difference to calculate retention similarity for - all values beyond this are assigned similarity of zero"/>
-        </section>
-    </xml>
-
-    <xml name="parameters_optional_metadata">
-        <section name="metadata" title="Optional Metadata" expanded="false">
-            <param label="metadata" name="batch_order_qc" type="data" format="csv" optional="true"
-                   help="CSV with sample names (or indices, currently not handled) on rows and columns with: batch
-                   number ('batch'), position in sequence ('order') and whether it is a qc sample or not
-                   ('qc' with true/false OR 'sampleType' with 'sample/qc/blank')."/>
-             <param label="Experimental design" name="ExpDes" type="data" format="csv" optional="true" help="Definition of experimental design in CSV format." />
+                   set based on the detected signal intensities for that feature."/>
+            <param label="Experimental design metadata" name="ExpDes" type="data" format="csv" optional="true"
+                   help="Definition of experimental design in CSV format." />
         </section>
     </xml>
 
     <xml name="output_msp">
-        <collection label="Mass spectra from ${tool.name} on ${on_string}" name="mass_spectra" type="list">
-            <discover_datasets pattern="__name_and_ext__" directory="spectra" recurse="true" ext="msp"/>
-        </collection>
+       <collection label="Mass spectra from ${tool.name} on ${on_string}" name="mass_spectra_collection" type="list">
+           <discover_datasets pattern="__name_and_ext__" directory="spectra" recurse="true" ext="msp"/>
+           <filter>not msp_output_details['merge_msp']</filter>
+       </collection>
+       <data label="Mass spectra from ${tool.name} on ${on_string}" name="mass_spectra_merged" format="msp">
+           <filter>msp_output_details['merge_msp']</filter>
+       </data>
     </xml>
 
     <xml name="citations">
@@ -234,7 +218,22 @@
                     (2) feature names that contain the mass and retention times, separated by a constant delimiter; and
                     (3) features in columns and samples in rows.
 
+                    +----------------------+-------------------+-------------------+--------------------+--------------------+
+                    | sample               |    100.88_262.464 |    100.01_423.699 |    100.003_128.313 |   100.0057_154.686 |
+                    +======================+===================+===================+====================+====================+
+                    | 10_qc_16x_dil_milliq |    0              |    195953.6376	   |     0              |   0                |
+                    +----------------------+-------------------+-------------------+--------------------+--------------------+
+                    | 11_qc_8x_dil_milliq  |    0              |    117742.1828    |    4247300.664     |   0                |
+                    +----------------------+-------------------+-------------------+--------------------+--------------------+
+                    | 12_qc_32x_dil_milliq |    4470859.38     |    0              |    2206092.112     |   0                |
+                    +----------------------+-------------------+-------------------+--------------------+--------------------+
+                    | 15_qc_16x_dil_milliq |    0              |    0              |    2767477.481     |   0                |
+                    +----------------------+-------------------+-------------------+--------------------+--------------------+
+
+
                 Downstream Tools
+                    The output is a msp file or a collection of msp files, with additional Spec Abundance file.
+
                     +---------+--------------+----------------------+
                     | Name    | Output File  | Format               |
                     +=========+==============+======================+
@@ -266,16 +265,16 @@
 
             RAMClustR approach
                 RAMClustR was designed to group features designed from the same compound using an approach which is
-                __1.__ unsupervised, __2.__ platform agnosic, and __3.__ devoid of curated rules, as the depth of
-                understanding of these processes is insufficent to enable accurate curation/prediction of all phenomenon
-                that may occur. We acheive this by making two assumptions. The first is that two features derived
+                **1.** unsupervised, **2.** platform agnostic, and **3.** devoid of curated rules, as the depth of
+                understanding of these processes is insufficient to enable accurate curation/prediction of all phenomenon
+                that may occur. We achieve this by making two assumptions. The first is that two features derived
                 from the same compound with have (approximately) the same retention time. The second is that two
                 features derived from the same compound will have (approximately) the same quantitative trend across
                 all samples in the xcms sample set. From these assumptions, we can calculate a retention time
                 similarity score and a correlational similarity score for each feature pair. A high similarity score
                 for both retention time and correlation indicates a strong probability that two features derive from
                 the same compound. Since both conditions must be met, the product of the two similarity scores provides
-                the best approximatio of the total similarity score - i.e. a feature pair with retention time similarity
+                the best approximation of the total similarity score - i.e. a feature pair with retention time similarity
                 of 1 and correlational similarity of 0 is unlikely to derive from one compound - 1 x 0 = 0, the final
                 similarity score is zero, indicating the two features represent two different compounds. Similarly, a
                 feature pair with retention time similarity of 0 and correlational similarity of 1 is unlikely to derive
@@ -283,11 +282,11 @@
                 correlational similarity of 1 is likely to derive from one compound - 1 x 1 = 1.
 
         The RAMClustR algorithm is built on creating similarity scores for all pairs of features, submitting
-        this score matrix for heirarchical clustering, and then cutting the resulting dendrogram into neat
+        this score matrix for hierarchical clustering, and then cutting the resulting dendrogram into neat
         chunks using the dynamicTreeCut package - where each 'chunk' of the dendrogram results in a group of
-        features likely to be derived from a single compound. Importantly, this is acheived without looking for
+        features likely to be derived from a single compound. Importantly, this is achieved without looking for
         specific phenomenon (i.e. sodiation), meaning that grouping can be performed on any dataset, whether it
-        is poisitive or negative ionization mode, EI or ESI, LC-MS GC-MS or CE-MS, in-source fragment or complex
+        is positive or negative ionization mode, EI or ESI, LC-MS GC-MS or CE-MS, in-source fragment or complex
         adduction event, and predictable or unpredictable signals.
     </token>