comparison w4mclassfilter.xml @ 14:87ec0d3c2266 draft

"planemo upload for repository https://github.com/HegemanLab/w4mclassfilter_galaxy_wrapper/tree/master commit a9664e9a04e49d436ebbb643ba1755397ab759dc"

13:c18040b6e8b9

<tool id="w4mclassfilter" name="W4m Data Subset" version="0.98.14">
    <description>Filter W4m data by values or metadata</description>
    <!-- Here is the hyphenation standard that I *try* to apply consistently in my documentation: http://www.sandranoonan.com/dont-let-hyphenation-drive-crazy/ -->
    <requirements>
        <requirement type="package" version="3.6.1">r-base</requirement>
        <requirement type="package" version="1.1_5">r-batch</requirement>
        <requirement type="package" version="0.98.14">w4mclassfilter</requirement>
    </requirements>
    <command detect_errors="aggressive"><![CDATA[
    unset R_HOME;
    Rscript $__tool_directory__/w4mclassfilter_wrapper.R
    dataMatrix_in         '$dataMatrix_in'
    sampleMetadata_in     '$sampleMetadata_in'
    variableMetadata_in   '$variableMetadata_in'
    sampleclassNames      '$sampleclassNames'
    inclusive             '$inclusive'
    wildcards             '$wildcards'
    classnameColumn       '$classnameColumn'
    samplenameColumn      'sampleMetadata'
    variable_range_filter '$variableRangeFilter'
    transformation        '$transformation'
    imputation            '$imputation'
    dataMatrix_out        '$dataMatrix_out'
    sampleMetadata_out    '$sampleMetadata_out'
    variableMetadata_out  '$variableMetadata_out'
    order_vrbl            '$order_vrbl'
    order_smpl            '$order_smpl'
    ]]></command>
    <inputs>
        <param name="dataMatrix_in" format="tabular" label="Data matrix file" type="data"
            help="data matrix, with sample names in first row and feature names in first column" />
        <param name="sampleMetadata_in" format="tabular" label="Sample metadata file" type="data"
            help="sample metadata, with one row per sample" />
        <param name="variableMetadata_in" format="tabular" label="Variable metadata file" type="data"
            help="variable metadata, with one row per feature" />
        <param name="classnameColumn" label="Column that names the sample-class" type="text" value = "class"
            help="name of the column in sample metadata that has the values to be tested against the 'Names of sample-classes' input parameter">
            <sanitizer>
                <valid initial="string.letters">
                    <add preset="string.digits"/>
                    <add value="&#46;"    /> <!-- dot, period -->
                    <add value="&#95;"    /> <!-- underscore -->
                </valid>
            </sanitizer>
        </param>
        <param name="sampleclassNames" label="Names of sample-classes" type="text" value = ""
            help="comma-separated names (or regular expressions to match names) of sample-classes to filter in or out (Leave empty to match no names.)">
            <sanitizer>
                <valid initial="string.letters">
                    <add preset="string.digits"/>
                    <add value="&#123;"   /> <!-- l-cube, left-curly-bracket -->
                    <add value="&#124;"   /> <!-- pipe -->
                    <add value="&#125;"   /> <!-- r-cube, right-curly-bracket -->
                    <add value="&#36;"    /> <!-- dollar, dollar-sign -->
                    <add value="&#40;"    /> <!-- left-paren -->
                    <add value="&#41;"    /> <!-- right-paren -->
                    <add value="&#42;"    /> <!-- splat, asterisk -->
                    <add value="&#43;"    /> <!-- plus -->

                    <add value="&#44;"    /> <!-- comma -->
                    <add value="&#46;"    /> <!-- dot, period -->
                    <add value="&#58;"    /> <!-- colon -->
                    <add value="&#59;"    /> <!-- semi, semicolon -->
                    <add value="&#63;"    /> <!-- what, question mark -->
                    <add value="&#91;"    /> <!-- l-squib, left-squre-bracket -->
                    <add value="&#92;"    /> <!-- whack, backslash -->
                    <add value="&#93;"    /> <!-- r-squib, right-squre-bracket -->
                    <add value="&#94;"    /> <!-- hat, caret -->
                    <add value="&#95;"    /> <!-- underscore -->
                </valid>
            </sanitizer>
        </param>
        <param name="wildcards" label="Use 'wild cards' or 'regular expressions'" type="select"
            help="'wild-cards' - use '*' and '?' to match class names; &#160;&#160; 'regular-expressions' - use regular expressions to match class names">
            <option value="TRUE" selected="true">wild-cards</option>
            <option value="FALSE">regular-expressions</option>
        </param>
        <param name="inclusive" label="Exclude/include named classes" type="select"
            help="'filter-out' - exclude only the named sample-classes; &#160;&#160;  'filter-in' - include only the named sample-classes">
            <option value="TRUE">filter-in</option>
            <option value="FALSE" selected="true">filter-out</option>
        </param>
        <param name="variableRangeFilter" label="Variable-range filters" type="text" value = ""
            help="comma-separated filters, each specified as 'variableMetadataColumnName:min:max' (leave empty for no filtering, as described in help below.)">
            <sanitizer>
                <valid initial="string.letters">
                    <add preset="string.digits"/>
                    <add value="&#44;"    /> <!-- comma -->
                    <add value="&#46;"    /> <!-- dot, period -->
                    <add value="&#58;"    /> <!-- colon -->
                    <add value="&#95;"    /> <!-- underscore -->
                </valid>
            </sanitizer>
        </param>
        <param name="transformation" label="Data-transformation" type="select"
            help="'none' - do not transform data; &#160;&#160;  'log2' - log base 2 of data; &#160;&#160;  'log10' - log base 10 of data; &#160;&#160;  in all cases, negative and missing values are imputed to zero">
            <option value="none" selected="true">none</option>
            <option value="log2">log2</option>
            <option value="log10">log10</option>
        </param>
        <param name="imputation" label="Imputation of missing values" type="select"
            help="'zero' - replace missing values with zero; &#160;&#160;  'center' - replace missing values with feature-median; &#160;&#160;  'none' - perform no imputation">
            <option value="zero" selected="true">zero</option>
            <option value="center">center</option>
            <option value="none">none</option>
        </param>
        <param name="order_smpl" label="Column that specifies order for samples" type="text" value = "sampleMetadata"
            help="name of the column in sample metadata that is used to sort samples">
            <sanitizer>
                <valid initial="string.letters">
                    <add preset="string.digits"/>
                    <add value="&#46;"    /> <!-- dot, period -->
                    <add value="&#95;"    /> <!-- underscore -->
                </valid>
            </sanitizer>
        </param>
        <param name="order_vrbl" label="Column that specifies order for features" type="text" value = "variableMetadata"
            help="name of the column in variable metadata that is used to sort features">
            <sanitizer>
                <valid initial="string.letters">
                    <add preset="string.digits"/>
                    <add value="&#46;"    /> <!-- dot, period -->
                    <add value="&#95;"    /> <!-- underscore -->
                </valid>
            </sanitizer>
        </param>
    </inputs>
    <outputs>
        <data name="dataMatrix_out" format="tabular" label="${dataMatrix_in.name}.subset" ></data>
        <data name="sampleMetadata_out" format="tabular" label="${sampleMetadata_in.name}.subset" ></data>

            <not_has_text text="HMDB59717" />
          </assert_contents>
        </output>
      </test>
      <!-- test 2 -->
	  <test>
        <param name="dataMatrix_in" value="input_dataMatrix.tsv"/>
        <param name="sampleMetadata_in" value="input_sampleMetadata.tsv"/>
        <param name="variableMetadata_in" value="input_variableMetadata.tsv"/>
        <!-- test that hyphens in regular expressions work -->
        <param name="sampleclassNames" value="HU_[0-9][0-9][0-9]"/>
        <param name="inclusive" value="TRUE"/>
        <param name="wildcards" value="FALSE"/>
        <param name="classnameColumn" value="sampleMetadata"/>
		<!-- test that variableRangeFilter works with tranformation -->
		<param name="variableRangeFilter" value="FEATMAX:6.30103:,mz:200:,rt::800"/>
        <param name="transformation" value="log10"/>
        <param name="imputation" value="zero"/>
        <output name="dataMatrix_out" md5="5644d2ea01d072ee1d0c40e29e9d0089">
          <assert_contents>
			<has_text text="5.8733671" />
          </assert_contents>
        </output>
        <output name="sampleMetadata_out">
          <assert_contents>
            <has_text text="HU_017" />

        <param name="classnameColumn" value="gender"/>
        <param name="sampleclassNames" value="*"/>
        <param name="wildcards" value="TRUE"/>
        <param name="inclusive" value="TRUE"/>
        <param name="imputation" value="none"/>
        <output name="dataMatrix_out" md5="cc9ab8bdb70b68b43b19b7327d285166">
          <assert_contents>
            <not_has_text text="HU_204" />
            <has_text text="NA" />
            <has_text text="HU_028" />
          </assert_contents>

        <param name="classnameColumn" value="gender"/>
        <param name="sampleclassNames" value="*"/>
        <param name="wildcards" value="TRUE"/>
        <param name="inclusive" value="TRUE"/>
        <param name="imputation" value="center"/>
        <output name="dataMatrix_out" md5="75a4802bb8887709e4d4dec8c2c3d3cf">
          <assert_contents>
            <not_has_text text="HU_204" />
            <not_has_text text="NA" />
            <has_text text="HU_028" />
          </assert_contents>

            <not_has_text text="HU_204" />
            <has_text text="HU_028" />
          </assert_contents>
        </output>
      </test>
    </tests>
    <help><![CDATA[


**Author** Arthur Eschenlauer (University of Minnesota, [e-mail])

--------------------------------------------------------------------------


**R package**

The *w4mclassfilter* package (which is used by the W4m Data Subset tool) is available from the Hegeman lab github repository (https://github.com/HegemanLab/w4mclassfilter/releases).

-----------------------------------------------------------------------------------------------------------------------------------------


**Tool updates**

See https://github.com/HegemanLab/w4mclassfilter_galaxy_wrapper#news

---------------------------------------------------

===========================================================
"W4m Data Subset" - Filter Workflow4Metabolomics data files
===========================================================

----------
Motivation
----------

GC-MS and LC-MS experiments seek to resolve as features chemicals that have distinct chromatographic retention-time ("rt") and (after ionization) mass-to-charge ratio ("m/z" or "mz").
(If the MS protocol includes fragmentation, several features may result for each chemical.)
Data for a sample are collected as MS intensities, each of which is associated with a position on a 2D plane with dimensions of rt and m/z.
Ideally, features would be sufficiently reproducible among sample-runs to distinguish features that are commmon among samples from those that differ.

The chromatographic retention-time for a chemical can vary from one chromatography run to the next.
Workflow4Metabolomics (W4m, [Giacomoni *et al.*, 2014, Guitton *et al.* 2017]) is a "flavor" of Galaxy that uses the XCMS preprocessing tools for "retention-time correction" to align features among samples.
Features may be better aligned if pooled samples and blanks are included.

Multivariate statistical techniques may be used to discover clusters of similar samples (Th]]>&#233;<![CDATA[venot *et al.*, 2015).
However, once retention-time alignment of features has been achieved among samples in GC-MS and LC-MS datasets:

- The presence of pools and blanks may confound identification and separation of clusters.
- Multivariate statistical algorithms may be impacted by missing values or dimensions that have zero variance.

-----------
Description
-----------

The **W4m Data Subset** tool **selects subsets of samples, features, or data values** for further analysis.

- The tool takes as input the data matrix, sample metadata, and variable metadata datasets produced by W4m's XCMS [Smith *et al.*, 2006] and CAMERA [Kuhl *et al.*, 2012] tools.
- The tool produces the same trio of output datasets, modified as follows.

This tool can perform several operations to reduce the number samples or features to be analyzed (although **this should be done only in a statistically sound manner** consistent with the nature of the experiment):

- Samples may be eliminated by filtering on a designated “sample class” column in sampleMetadata.
- Features may be eliminated by specifying minimum or maximum value (or both) allowable in columns of variableMetadata.
- Features may be eliminated by “range of row-maximum for each feature”, i.e., by specifying minimum or maximum intensity (or both) allowable in each row of the dataMatrix (i.e., for the feature across all samples).

This tool also performs several operations to address several data issues that may impede downstream statistical analysis:

- Samples that are missing from either sampleMetadata or dataMatrix are eliminated.
- Features that are missing from either variableMetadata or dataMatrix are eliminated.
- Features and samples that have zero variance are eliminated.
- Samples and features have consistent order in `variableMetadata`, `sampleMetadata`, and `dataMatrix`.
  (The column for sorting `variableMetadata` or `sampleMetadata` may be specified.)
- The names of the first columns of variableMetadata and sampleMetadata are set respectively to "variableMetadata" and "sampleMetadata".
- If desired, the values in the dataMatrix may be log-transformed.
- If desired, each missing value in dataMatrix is replaced with zero or the median value observed for the corresponding feature.

This tool may be applied several times sequentially, which may be useful for:

- analyzing subsets of samples for progressively smaller sets of treatment-levels, or
- choosing subsets of samples based on criteria in several columns of the sampleMetadata table.

-----------------
Workflow Position
-----------------

-----------
Input files
-----------

+---------------------------+------------+
| File                      |   Format   |
+===========================+============+
|     Data matrix           |   tabular  |
+---------------------------+------------+
|     Sample metadata       |   tabular  |
+---------------------------+------------+
|     Variable metadata     |   tabular  |
+---------------------------+------------+


----------
Parameters
----------

Data matrix file
	| feature x sample **dataMatrix** (tabular separated values) file of the numeric data matrix, with period-character ('.') as decimal, and 'NA' for missing values; the table must not contain metadata apart from the required row and column names; the row and column names must be identical (with regard to both content or order) to the respective rownames of the sample metadata file and variable metadata file
	|

Sample metadata file
	| sample x metadata **sampleMetadata** (tabular separated values) file of the numeric and/or character sample metadata, with . as decimal and NA for missing values
	|

Variable metadata file
	| variable x metadata **variableMetadata** (tabular separated values) file of the numeric and/or character variable metadata, with . as decimal and NA for missing values
	|

Column that names the sample-class (default = '``class``')
	| name of the column in **sampleMetadata** that has the values to be tested against the '``Names of sample-classes``' input parameter; only letters, digits, periods, and underscores are permitted.
	|

Names of sample-classes (default = no names)
	| comma-separated names (or regular expressions to match names) of sample-classes to include or exclude
	|

'Wild cards' or 'regular expressions' (default = '``wild-cards``')
	| '``wild-cards``' - use wild cards to match names of sample-classes (see the 'Wild card patterns to match class-names' section below)
	| '``regular-expressions``' - use regular expressions to match the named sample-classes (see the 'Regular expression patterns to match class-names' section below)
	|

Exclude/include named classes (default = '``filter-out``')
	| '``filter-in``' - include only the named sample-classes
	| '``filter-out``' - exclude only the named sample-classes
	|

Variable-range filters (default = no filters)
	| comma-separated names of variable-range filters (see the 'Variable-range filters' section below)
	|

Data-transformation (default = '``none``')
	| '``none``' - Do not transform data matrix values.
	| '``log2``' - Take the log base 2 of the values in the data matrix.
	| '``log10``' - Take the log base 10 of the values in the data matrix.
	|

Data-imputation (default = '``zero``')
	| '``none``' - Do not impute data matrix values.
	| '``zero``' - Negative and missing values are imputed to zero.
	| '``center``' - For each feature, negative and missing values are imputed to the median of other values.
	|

Column that specifies order for samples (default = 'sampleMetadata')
	| name of the column in **sampleMetadata** that is used to sort samples; only letters, digits, periods, and underscores are permitted.
	|

Column that specifies order for features (default = 'variableMetadata')
	| name of the column in **variableMetadata** that is used to sort features; only letters, digits, periods, and underscores are permitted.
	|

------------
Output files
------------

sampleMetadata
	| (tabular separated values) file identical to the **sampleMetadata** file given as an input argument, excepting lacking rows for samples that have been filtered out (by the sample-class filter, or because of zero variance, or because they were missing in the input data matrix)
	|

variableMetadata
	| (tabular separated values) file identical to the **variableMetadata** file given as an input argument, excepting lacking rows for variables (xC-MS features) that have been filtered out (by the variable-range filter, or because of zero variance, or because they were missing in the input data matrix)
	|

dataMatrix
	| (tabular separated values) file identical to the **dataMatrix** file given as an input argument, excepting lacking rows and columns for variables and samples that have been filtered out, respectively
	|


-----------------------------------------
'Wild card' patterns to match class-names
-----------------------------------------

W4m Data Subset supports use of R "wild card" patterns to select class-names.

- use '``?``' to match a single character
- use '``*``' to match zero or more characters
- the entire pattern must match the sample name

- '``??.samp*``' matches '``my.sample``' but not '``my.own.sample``'
- '``*.sample``' matches '``my.sample``' and '``my.own.sample``'
- '``*.sampl``' matches neither '``my.sample``' nor '``my.own.sample``'

--------------------------------------------------
'Regular expression' patterns to match class-names
--------------------------------------------------

W4m Data Subset supports use of R "regular expression" patterns to select class-names.

R uses POSIX 1003.2 standard regular expressions, which allow precise pattern-matching and are exhaustively defined at:
http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap09.html

However, only a few basic building blocks of regular expressions need to be mastered for most cases:

- '``^``' matches the beginning of a class-name
- '``$``' matches the end of a class-name

- The regular expression '``^[a-z][a-z]12$``' will match the same sample-classes as '``front12,marq12``'
- The regular expression '``^[a-z][a-z][0-9]$``' will match the same sample-classes as '``front3,front6,front9,marq3,marq6,marq9``'

Second Example: Consider these regular expression patterns as possible matches to a sample-class name '``AB0123``':

- '``^[A-Z][A-Z][0-9][0-9]*$``' - MATCHES '``**^AB0123$**``'
- '``^[A-Z][A-Z]*[0-9][0-9]*$``' - MATCHES '``**^AB0123$**``'
- '``^[A-Z][0-9]*``' - MATCHES  '``**^A** B0123$``' - first character is a letter, '``*``' can specify zero characters, and end of line did not need to be matched.
- '``^[A-Z][A-Z][0-9]``' - MATCHES  '``**^AB0** 123$``' - first two characters are letters aind the third is a digit.
- '``^[A-Z][A-Z]*[0-9][0-9]$``' - NO MATCH - the name does not end with the pattern '``[A-Z][0-9][0-9]$``', i.e., it ends with four digits, not two.
- '``^[A-Z][0-9]*$``' - NO MATCH - the pattern specifies that second character and all those that follow, if present, must be digits.

----------------------
Variable-range filters
----------------------

An array of range-specification strings may be supplied in the `variableRangeFilter`
argument.  If supplied, only features having numerical values in the specified column
of `variableMetadata` that fall within the specified ranges will be retained
in the output.  Each range is a string of three colon-separated values (e.g., "mz:200:800") in the
following order:

- the **name of a column of `variableMetadata`** which must have numerical data (only letters, digits, periods, and underscores are permitted in the name itself), e.g., 'mz';
- the **minimum allowed value** in that column for the feature to be retained, e.g., '200';
- the **maximum allowed value**, e.g., '800'.

Note for the range specification strings:

- **If the "maximum" is less than the "minimum", then the range is exclusive**  (e.g., "mz:800:200" means retain only features whose mz is NOT in the range 200-800)
- **If the name supplied in the first field is 'FEATMAX',**  then the string is defining the minimum (and possibly, though less useful, maximum) intensity for each feature in the dataMatrix.  For example, "FEATMAX:1e6:" would specify  that any feature would be excluded if no sample had an intensity for that feature greater than 1000000.

  - Note, however, that when the "maximum" is greater than the "minimum" for the FEATMAX range specification, then the specification is ignored.

----------------------------------
Data transformation and imputation
----------------------------------

Data may optionally be log2- or log10-transformed.

Negative intensity values are always substituted with zeros.

Missing intensity data values may optionally be imputed.  Missing values may be substituted with zeros (as may be appropriate for univariate analysis) or with the median for the feature (as may be appropriate for multivariate analysis).  (Note that the median feature-intensity is computed for the samples *before* variable-range filters are applied.)

-----------------------------------------------------------------------------

----------------
WORKING EXAMPLES

+------------------------------------------------------------------------------------------------------------------------------------------------------+
| https://raw.githubusercontent.com/HegemanLab/w4mclassfilter_galaxy_wrapper/master/tools/w4mclassfilter/test-data/input_variableMetadata.tsv          |
+------------------------------------------------------------------------------------------------------------------------------------------------------+

-------------------------------
Running Without Range-Filtering
-------------------------------

This example retains only samples whose 'gender' attribute is 'M'.

**Input parameters**

+---------------------------------------------+-------------------------------+
| Input Parameter                             | Value                         |
+=============================================+===============================+
| Column that names the sample-class          | gender                        |
+---------------------------------------------+-------------------------------+
| Names of sample-classes                     | M                             |
+---------------------------------------------+-------------------------------+
| Use 'wild-cards' or 'regular expressions'   | wild-cards                    |
+---------------------------------------------+-------------------------------+
| Exclude/include named classes               | filter-in                     |
+---------------------------------------------+-------------------------------+
| Variable range-filters                      | (Leave this field empty.)     |
+---------------------------------------------+-------------------------------+
| Data transforamtion                         | none                          |
+---------------------------------------------+-------------------------------+
| Missing-value imputation                    | center                        |
+---------------------------------------------+-------------------------------+
| Sample-sort column                          | sampleMetadata                |
+---------------------------------------------+-------------------------------+
| Feature-sort column                         | variableMetadata              |
+---------------------------------------------+-------------------------------+

**Expected outputs**

+-------------------+-------------------------------------------------------------------------------------------------------------------------------------------------+

+-------------------+-------------------------------------------------------------------------------------------------------------------------------------------------+
| Variable metadata | https://raw.githubusercontent.com/HegemanLab/w4mclassfilter_galaxy_wrapper/master/tools/w4mclassfilter/test-data/expected_variableMetadata.tsv  |
+-------------------+-------------------------------------------------------------------------------------------------------------------------------------------------+

----------------------------
Running With Range-Filtering
----------------------------

This example retains only features whose mz is greater than 200, whose rt is less than 800, and whose maximum intensity across all samples is 2,000,000.
This example retains all samples (except those having zero variance for all feature), although it would be possible to filter on samples as well.

**Input parameters**

+---------------------------------------------+-----------------------------------+
| Input Parameter                             | Value                             |
+=============================================+===================================+
| Column that names the sample-class          | sampleMetadata                    |
+---------------------------------------------+-----------------------------------+
| Names of sample-classes                     | HU_13[48]                         |
+---------------------------------------------+-----------------------------------+
| Use 'wild-cards' or 'regular expressions'   | regular-expressions               |
+---------------------------------------------+-----------------------------------+
| Exclude/include named classes               | filter-out                        |
+---------------------------------------------+-----------------------------------+
| Variable range-filters                      | FEATMAX:20.93157:,mz:200:,rt::800 |
+---------------------------------------------+-----------------------------------+
| Data transforamtion                         | log2                              |
+---------------------------------------------+-----------------------------------+
| Missing-value imputation                    | zero                              |
+---------------------------------------------+-----------------------------------+
| Sample-sort column                          | sampleMetadata                    |
+---------------------------------------------+-----------------------------------+
| Feature-sort column                         | variableMetadata                  |
+---------------------------------------------+-----------------------------------+

**Expected outputs**

+-------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+

+-------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
| Sample metadata   | https://raw.githubusercontent.com/HegemanLab/w4mclassfilter_galaxy_wrapper/master/tools/w4mclassfilter/test-data/rangefilter_sampleMetadata.tsv   |
+-------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
| Variable metadata | https://raw.githubusercontent.com/HegemanLab/w4mclassfilter_galaxy_wrapper/master/tools/w4mclassfilter/test-data/rangefilter_variableMetadata.tsv |
+-------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
    ]]></help>
    <citations>
        <!-- Giacomoni_2014 W4m 2.5 -->
        <citation type="doi">10.1093/bioinformatics/btu813</citation>
        <!-- Guitton_2017 W4m 3.0 -->
        <citation type="doi">10.1016/j.biocel.2017.07.002</citation>
        <!-- Kuhl_2012 CAMERA -->
        <citation type="doi">10.1021/ac202450g</citation>
        <!-- Smith_2006 XCMS -->
        <citation type="doi">10.1021/ac051437y</citation>

14:87ec0d3c2266

<tool id="w4mclassfilter" name="W4m Data Subset" version="0.98.18">
    <description>Filter W4M data by values or metadata</description>
    <!-- Here is the hyphenation standard that I *try* to apply consistently in my documentation: 
         https://web.archive.org/web/20161014025757/http://www.sandranoonan.com/dont-let-hyphenation-drive-crazy/
    -->
    <requirements>
        <requirement type="package" version="3.6.2">r-base</requirement>
        <requirement type="package" version="1.1_5">r-batch</requirement>
        <requirement type="package" version="0.98.18">w4mclassfilter</requirement>
    </requirements>
    <command detect_errors="aggressive"><![CDATA[
    unset R_HOME;
    if [ '$centering' == 'medoid' -a '$imputation' == 'none' ]; then
    (echo 'medoid' centering may not be chosen with imputation 'none' 1>&2);
        [ ! 1 ];
    else
        Rscript
        $__tool_directory__/w4mclassfilter_wrapper.R
        dataMatrix_in         '$dataMatrix_in'
        sampleMetadata_in     '$sampleMetadata_in'
        variableMetadata_in   '$variableMetadata_in'
        sampleclassNames      '$sampleclassNames'
        inclusive             '$inclusive'
        wildcards             '$wildcards'
        classnameColumn       '$classnameColumn'
        samplenameColumn      'sampleMetadata'
        variable_range_filter '$variableRangeFilter'
        transformation        '$transformation'
        imputation            '$imputation'
        dataMatrix_out        '$dataMatrix_out'
        sampleMetadata_out    '$sampleMetadata_out'
        variableMetadata_out  '$variableMetadata_out'
        order_vrbl            '$order_vrbl'
        order_smpl            '$order_smpl'
        centering             '$centering';
    fi
    ]]></command>
    <inputs>
        <param name="dataMatrix_in" format="tabular" label="Data matrix" type="data"
            help="Choose data-matrix file (tab-separated values with sample names in first row and feature names in first column)." />
        <param name="sampleMetadata_in" format="tabular" label="Sample metadata" type="data"
            help="Choose sample-metadata file (tab-separated values with one row per sample, sample name in first column)." />
        <param name="variableMetadata_in" format="tabular" label="Variable metadata" type="data"
            help="Choose variable-metadata file (tab-separated values with one row per feature, feature name in first column)." />
        <param name="classnameColumn" label="Column containing the sample-class names (or treatment names)" type="text" value = "class"
            help="Name the column in 'Sample metadata' that has the values to be referenced by 'Sample-class names' and 'Compute centers for classes'. [default: 'class']">
            <sanitizer>
                <valid initial="string.letters">
                    <add preset="string.digits"/>
                    <add value="&#46;"    /> <!-- dot, period -->
                    <add value="&#95;"    /> <!-- underscore -->
                </valid>
            </sanitizer>
        </param>
        <param name="sampleclassNames" label="Sample-class names (or patterns)" type="text" value = ""
            help="List of names (or patterns to match names) of sample classes to include or exclude.  List should be comma-separated with no stray space characters. (Leave this empty to match no names.) [default: empty]">
            <sanitizer>
                <valid initial="string.letters">
                    <add preset="string.digits"/>
                    <add value="&#123;"   /> <!-- l-curb, left-curly-bracket -->
                    <add value="&#124;"   /> <!-- pipe -->
                    <add value="&#125;"   /> <!-- r-curb, right-curly-bracket -->
                    <add value="&#36;"    /> <!-- dollar, dollar-sign -->
                    <add value="&#40;"    /> <!-- left-paren -->
                    <add value="&#41;"    /> <!-- right-paren -->
                    <add value="&#42;"    /> <!-- splat, asterisk -->
                    <add value="&#43;"    /> <!-- plus -->

                    <add value="&#44;"    /> <!-- comma -->
                    <add value="&#46;"    /> <!-- dot, period -->
                    <add value="&#58;"    /> <!-- colon -->
                    <add value="&#59;"    /> <!-- semi, semicolon -->
                    <add value="&#63;"    /> <!-- what, question mark -->
                    <add value="&#91;"    /> <!-- l-squib, left-square-bracket -->
                    <add value="&#92;"    /> <!-- whack, backslash -->
                    <add value="&#93;"    /> <!-- r-squib, right-square-bracket -->
                    <add value="&#94;"    /> <!-- hat, caret -->
                    <add value="&#95;"    /> <!-- underscore -->
                </valid>
            </sanitizer>
        </param>
        <param name="inclusive" label="Exclude/include named (or matched) sample classes" type="select" help="Indicate meaning of preceding list: either to identify classes to exclude from output or to identify classes to include in output. [default: 'filter-out']">
            <option value="TRUE">filter-in: &#160;&#160; Include only the named sample classes.</option>
            <option value="FALSE" selected="true">filter-out: &#160;&#160; Exclude only the named sample classes.</option>
        </param>
        <param name="wildcards" label="Use 'wild card patterns' or 'regular expression patterns' to match sample-class names" type="select"
            help="See '&lt;i&gt;Wild-card patterns to match class names&lt;/i&gt;' and '&lt;i&gt;Regular-expression patterns to match sample-class names&lt;/i&gt;' sections below. [default: 'wild-card patterns']">
            <option value="TRUE" selected="true">wild-card patterns: &#160;&#160; Use '*' and '?' to match sample-class names.</option>
            <option value="FALSE">regular-expression patterns: &#160;&#160; Use regular expressions to match sample-class names.</option>
        </param>
        <param name="variableRangeFilter" label="Variable-range filters" type="text" value = ""
            help="List of filters, each specifying the range of permitted values in a column of 'Variable metadata' (specified as 'column:min:max'), as described in '&lt;i&gt;Variable-range filters&lt;/i&gt;' section below.  List should be comma-separated with no stray space characters.  (Leave this empty for no filtering.) [default: empty]">
            <sanitizer>
                <valid initial="string.letters">
                    <add preset="string.digits"/>
                    <add value="&#44;"    /> <!-- comma -->
                    <add value="&#46;"    /> <!-- dot, period -->
                    <add value="&#58;"    /> <!-- colon -->
                    <add value="&#95;"    /> <!-- underscore -->
                </valid>
            </sanitizer>
        </param>
        <param name="transformation" label="Data transformation" type="select"
            help="Choose transformation.  In all cases, negative intensities become missing values.  See '&lt;i&gt;Data transformation and imputation&lt;/i&gt;' section below. [default: 'none']">
            <option value="none" selected="true">none: &#160;&#160; Do not transform data.</option>
            <option value="log2">log2: &#160;&#160; Perform log base 2 transformation of data.</option>
            <option value="log10">log10: &#160;&#160; Perform log base 10 transformation of data.</option>
        </param>
        <param name="imputation" label="Imputation of missing values" type="select"
            help="Choose imputation for missing values.  See '&lt;i&gt;Data transformation and imputation&lt;/i&gt;' section below. [default: 'zero']">
            <option value="zero" selected="true">zero: &#160;&#160; Replace missing values with zero.</option>
            <option value="center">center: &#160;&#160; Replace missing values with feature-median.</option>
            <option value="none">none: &#160;&#160; Perform no imputation.  Note that 'compute centers' cannot be set to 'medoid'.</option>
        </param>
        <param name="order_smpl" label="Columns that specify order for samples" type="text" value = "sampleMetadata"
            help="List of sample-metadata column names for sorting samples.  List should be comma-separated with no stray space characters.  (This is ignored when 'Compute centers for classes' is set to either 'centroid' or 'median'.) [default: 'sampleMetadata']">
            <sanitizer>
                <valid initial="string.letters">
                    <add preset="string.digits"/>
                    <add value="&#46;"    /> <!-- dot, period -->
                    <add value="&#95;"    /> <!-- underscore -->
                    <add value="&#44;"    /> <!-- comma -->
                </valid>
            </sanitizer>
        </param>
        <param name="order_vrbl" label="Columns that specify order for features" type="text" value = "variableMetadata"
            help="List of feature-metadata column names for sorting features.  List should be comma-separated with no stray space characters. [default: 'variableMetadata']">
            <sanitizer>
                <valid initial="string.letters">
                    <add preset="string.digits"/>
                    <add value="&#46;"    /> <!-- dot, period -->
                    <add value="&#95;"    /> <!-- underscore -->
                    <add value="&#44;"    /> <!-- comma -->
                </valid>
            </sanitizer>
        </param>
        <param name="centering" label="Compute centers for classes (e.g., treatments)" type="select" help="[default: 'none']">
            <option value="none" selected="true">none: &#160;&#160; Do not compute centers for classes/treatments.</option>
            <option value="centroid">centroid: &#160;&#160; For each class, compute the mean for each feature.</option>
            <option value="median">median: &#160;&#160; For each class, compute the median for each feature.</option>
            <option value="medoid">medoid: &#160;&#160; For each class, select only the most central member. Note that 'Imputation of missing values' cannot be 'none'.</option>
        </param>
    </inputs>
    <outputs>
        <data name="dataMatrix_out" format="tabular" label="${dataMatrix_in.name}.subset" ></data>
        <data name="sampleMetadata_out" format="tabular" label="${sampleMetadata_in.name}.subset" ></data>

            <not_has_text text="HMDB59717" />
          </assert_contents>
        </output>
      </test>
      <!-- test 2 -->
      <test>
        <param name="dataMatrix_in" value="input_dataMatrix.tsv"/>
        <param name="sampleMetadata_in" value="input_sampleMetadata.tsv"/>
        <param name="variableMetadata_in" value="input_variableMetadata.tsv"/>
        <!-- test that hyphens in regular expressions work -->
        <param name="sampleclassNames" value="HU_[0-9][0-9][0-9]"/>
        <param name="inclusive" value="TRUE"/>
        <param name="wildcards" value="FALSE"/>
        <param name="classnameColumn" value="sampleMetadata"/>
        <!-- test that variableRangeFilter works with tranformation -->
        <param name="variableRangeFilter" value="FEATMAX:6.30103:,mz:200:,rt::800"/>
        <param name="transformation" value="log10"/>
        <param name="imputation" value="zero"/>
        <output name="dataMatrix_out" md5="5644d2ea01d072ee1d0c40e29e9d0089">
          <assert_contents>
            <has_text text="5.8733671" />
          </assert_contents>
        </output>
        <output name="sampleMetadata_out">
          <assert_contents>
            <has_text text="HU_017" />

        <param name="classnameColumn" value="gender"/>
        <param name="sampleclassNames" value="*"/>
        <param name="wildcards" value="TRUE"/>
        <param name="inclusive" value="TRUE"/>
        <param name="imputation" value="none"/>
        <output name="dataMatrix_out" md5="6200dfa77d09c56e434f80b1a23b3393">
          <assert_contents>
            <not_has_text text="HU_204" />
            <has_text text="NA" />
            <has_text text="HU_028" />
          </assert_contents>

        <param name="classnameColumn" value="gender"/>
        <param name="sampleclassNames" value="*"/>
        <param name="wildcards" value="TRUE"/>
        <param name="inclusive" value="TRUE"/>
        <param name="imputation" value="center"/>
        <output name="dataMatrix_out" md5="a404278c5c9ffd5bdadf346c4f8a0184">
          <assert_contents>
            <not_has_text text="HU_204" />
            <not_has_text text="NA" />
            <has_text text="HU_028" />
          </assert_contents>

            <not_has_text text="HU_204" />
            <has_text text="HU_028" />
          </assert_contents>
        </output>
      </test>
      <!-- test 12 - select medoid for class -->
      <test>
        <param name="dataMatrix_in" value="input_dataMatrix.tsv"/>
        <param name="sampleMetadata_in" value="input_sampleMetadata.tsv"/>
        <param name="variableMetadata_in" value="input_variableMetadata.tsv"/>
        <param name="classnameColumn" value="gender"/>
        <param name="sampleclassNames" value=""/>
        <param name="wildcards" value="TRUE"/>
        <param name="inclusive" value="FALSE"/>
        <param name="imputation" value="zero"/>
        <param name="order_vrbl" value="rt"/>
        <param name="order_smpl" value="gender"/>
        <param name="centering" value="medoid"/>
        <output name="dataMatrix_out" md5="c91bbfbf30004fa24b05a67ec479bfb1">
          <assert_contents>
            <not_has_text text="1013302" />
            <has_text text="4763576" />
            <has_text text="2003278" />
            <has_text text="26222916" />
          </assert_contents>
        </output>
        <output name="sampleMetadata_out">
          <assert_contents>
            <not_has_text text="HU_099" />
            <not_has_text text="HU_185" />
            <has_text text="HU_110" />
            <has_text text="HU_078" />
          </assert_contents>
        </output>
      </test>
    </tests>
    <help><![CDATA[


**Author** Arthur Eschenlauer (University of Minnesota, [e-mail])

--------------------------------------------------------------------------


**R package**

The *w4mclassfilter* package (which is used by the W4M Data Subset tool) is available from the Hegeman lab GitHub repository (https://github.com/HegemanLab/w4mclassfilter/releases).

-----------------------------------------------------------------------------------------------------------------------------------------


**Tool updates**

See https://github.com/HegemanLab/w4mclassfilter_galaxy_wrapper#news

---------------------------------------------------

======================================================
"W4M Data Subset" - Filter Workflow4Metabolomics data 
======================================================

----------
Motivation
----------

LC-MS metabolomics experiments seek to resolve "features", i.e., species that have distinct chromatographic retention time ("rt") and (after ionization) mass-to-charge ratio ("*m/z*" or "mz").
(If a chemical is fragmented or may have a variety of adducts, several features will result.)
Data for a sample are collected as mass-spectral intensities, each of which is associated with a position on a 2D plane with dimensions of rt and *m/z*.
Ideally, features would be sufficiently reproducible among sample-runs to distinguish features that are similar among samples from those that differ.

For liquid chromatography, the retention time for a species can vary considerably from one chromatography run to the next.
The Workflow4Metabolomics suite of Galaxy tools (W4M, [Giacomoni *et al.*, 2014, Guitton *et al.* 2017])
uses the XCMS preprocessing tools [Smith *et al.*, 2006]
for "retention-time correction" to align features among samples.
Features may be better aligned if pooled samples and blanks are included.

Multivariate statistical tools may be used to discover clusters of similar samples [Th]]>&#233;<![CDATA[venot *et al.*, 2015].
However, once retention-time alignment of features has been achieved among samples in LC-MS datasets:

- The presence of pools and blanks may confound identification and separation of sample clusters.
- Multivariate statistical algorithms may be impacted by missing values or dimensions that have zero variance.

-----------
Description
-----------

The **W4M Data Subset** tool **selects subsets of samples, features, or data values** and **conditions the data** for further analysis.

- The tool takes as input the *dataMatrix*, *sampleMetadata*, and *variableMetadata* datasets produced by W4M's XCMS and CAMERA [Kuhl *et al.*, 2012] tools.
- The tool produces the same trio of output datasets, modified as described below.

This tool can perform several operations to reduce the number samples or features to be analyzed (although *this should be done only in a statistically sound manner* consistent with the nature of the experiment):

- *Sample filtering:* Samples may be selected by designating a "sample class" column in *sampleMetadata* and specifying criteria to include or exclude samples based on the contents of this column.
- *Feature filtering:* Features may be selected by specifying minimum or maximum value (or both) allowable in columns of *variableMetadata*.
- *Intensity filtering:* To exclude minimal features from consideration, a lower bound may be specified for the maximum intensity for a feature across all samples (i.e., for a row in *dataMatrix*).

This tool also conditions data for statistical analysis:

- Samples that are missing from either *sampleMetadata* or *dataMatrix* are eliminated.
- Features that are missing from either *variableMetadata* or *dataMatrix* are eliminated.
- Features and samples that have zero variance are eliminated.
- Samples and features are ordered consistently in *variableMetadata*, *sampleMetadata*, and *dataMatrix*.
  (The columns for sorting *variableMetadata* or *sampleMetadata* may be specified.)
- The names of the first columns of *variableMetadata* and *sampleMetadata* are set respectively to "variableMetadata" and "sampleMetadata".
- If desired, the values in *dataMatrix* may be log-transformed.
- Negative intensities become missing values (before missing-value replacement is performed).
- If desired, each missing value in *dataMatrix* may be replaced with zero or the median value observed for the corresponding feature.
- If desired, a "center" for each treatment can be computed in lieu of the samples for that treatment.

This tool may be applied several times sequentially, which may be useful for:

- analyzing subsets of samples for progressively smaller sets of treatment levels, or
- choosing subsets of samples or features, respectively based on criteria in columns of *sampleMetadata* or *variableMetadata*.

-----------------
Workflow Position
-----------------

-----------
Input files
-----------

+------------------------+---------------------------------------+------------+
| File                   | Contents                              |   Format   |
+========================+=======================================+============+
|     Data matrix        | per-feature, per-sample intensities   |   tabular  |
+------------------------+---------------------------------------+------------+
|     Sample metadata    | metadata for samples                  |   tabular  |
+------------------------+---------------------------------------+------------+
|     Variable metadata  | metadata for features                 |   tabular  |
+------------------------+---------------------------------------+------------+


----------
Parameters
----------

Data matrix
	| feature x sample **dataMatrix** (tab-separated values) file of the numeric data matrix, with period-character ('.') as decimal, and 'NA' for missing values.
	| The file must not contain metadata apart from the required row and column names.
	|

Sample metadata
	| sample x metadata **sampleMetadata** (tab-separated values) file of the numeric and/or character sample metadata, with period-character ('.') as decimal, and 'NA' for missing values.
	|

Variable metadata
	| variable x metadata **variableMetadata** (tab-separated values) file of the numeric and/or character variable metadata, with period-character ('.') as decimal, and 'NA' for missing values.
	|

Column containing the sample-class names (default = '``class``')
	| name of the column in **sampleMetadata** that has the values to be tested against the '``Sample-class names``' input parameter or to be referenced by the '``Compute centers for classes``' input parameter.
	| Only letters, digits, periods, and underscores are permitted.
	|

Sample-class names (default = no names)
	| names (or regular expressions to match names) of sample-classes to include or exclude
	| (Separate names with commas, without any extra space characters.)
	|

Exclude/include named (or matched) classes (default = '``filter-out``')
	| '``filter-in``' - include only the named sample-classes
	| '``filter-out``' - exclude only the named sample-classes
	|

Use 'wild card patterns' or 'regular expression patterns' (default = '``wild-card patterns``')
	| '``wild-card patterns``' - use wild cards to match names of sample-classes (see the *'Wild-card patterns to match class names'* section below.)
	| '``regular-expression patterns``' - use regular expressions to match the named sample-classes (see the *'Regular-expression patterns to match class names'* section below.)
	|

Variable-range filters (default = no filters)
	| variable-range filters (see the *'Variable-range filters'* section below)
	| (Separate filter expressions with commas, without any extra space characters.)
	|

Data transformation (default = '``none``')
	| '``none``' - Do not transform data matrix values.
	| '``log2``' - Take the log base 2 of the values in the data matrix.
	| '``log10``' - Take the log base 10 of the values in the data matrix.
	|
	| Note that negative intensities become missing values regardless of the choice made here.
	|

Imputation of missing values (default = '``zero``')
	| '``none``' - Do not impute data matrix values.
	| '``zero``' - Negative and missing values are imputed to zero.
	| '``center``' - For each feature, negative and missing values are imputed to the median of other values.
	|
	| Note well: For '``none``' option, '``Compute centers for classes``' cannot be set to '``medoid``'.
	|

Columns that specify order for samples (default = '``sampleMetadata``')
	| names of the columns in **sampleMetadata** that is used to sort samples; only letters, digits, periods, and underscores are permitted.
	| (Separate column names with commas, without any extra space characters.)
	|

Columns that specify order for features (default = '``variableMetadata``')
	| names of the columns in **variableMetadata** that is used to sort features; only letters, digits, periods, and underscores are permitted.
	| (Separate column names with commas, without any extra space characters.)
	|

Compute centers for classes, e.g., treatments (default = '``none``')
	| '``none``' - Return all samples; do not compute centers for classes/treatments.
	| '``centroid``' - For each treatment, return only the centroid (the treatment-center computed as the mean intensity for each feature).
	| '``median``' - For each treatment, return only the treatment-center computed as the median intensity for each feature.
	| '``medoid``' - For each treatment, return only the medoid (the sample most similar to the other samples for that treatment).
	|
	| Note well: For '``medoid``' option, '``Imputation of missing values``' cannot be set to '``none``'.
	|

------------
Output files
------------

sampleMetadata
	| (tab-separated values) file.
	| If centering is '``none``' or  '``medoid``', this will be identical to the **sampleMetadata** file given as an input argument, excepting lacking rows for samples that have been filtered out (by the sample-class filter, or because of zero variance, or because they were missing in the input data matrix)
	| If centering is '``centroid``' or  '``median``', most columns will be replaced with the treatment name and the number of samples for that treatment.
	|

variableMetadata
	| (tab-separated values) file identical to the **variableMetadata** file given as an input argument, excepting lacking rows for variables (LC-MS features) that have been filtered out (by the variable-range filter, or because of zero variance, or because they were missing in the input data matrix)
	|

dataMatrix
	| (tab-separated values) file identical to the **dataMatrix** file given as an input argument, excepting lacking rows and columns for variables and samples that have been filtered out, respectively
	|


-----------------------------------------
Wild-card patterns to match class names
-----------------------------------------

W4M Data Subset supports use of "wild card" patterns to select class-names.

- use '``?``' to match a single character
- use '``*``' to match zero or more characters
- the entire pattern must match the sample name

- '``??.samp*``' matches '``my.sample``' but not '``my.own.sample``'
- '``*.sample``' matches '``my.sample``' and '``my.own.sample``'
- '``*.sampl``' matches neither '``my.sample``' nor '``my.own.sample``'

--------------------------------------------------
Regular-expression patterns to match class names
--------------------------------------------------

W4M Data Subset supports use of R "extended regular expression" patterns to select class-names.

R extended regular expressions, which allow precise pattern-matching and are exhaustively defined at
https://stat.ethz.ch/R-manual/R-devel/library/base/html/regex.html

However, only a few basic building blocks of regular expressions need to be mastered for most cases:

- '``^``' matches the beginning of a class-name
- '``$``' matches the end of a class-name

- The regular expression '``^[a-z][a-z]12$``' will match the same sample-classes as '``front12,marq12``'
- The regular expression '``^[a-z][a-z][0-9]$``' will match the same sample-classes as '``front3,front6,front9,marq3,marq6,marq9``'

Second Example: Consider these regular expression patterns as possible matches to a sample-class name '``AB0123``':

- '``^[A-Z][A-Z][0-9][0-9]*$``' MATCHES '``**^AB0123$**``'
- '``^[A-Z][A-Z]*[0-9][0-9]*$``' MATCHES '``**^AB0123$**``'
- '``^[A-Z][0-9]*``' MATCHES '``**^A** B0123$``' - first character is a letter, '``*``' can specify zero characters, and end of line did not need to be matched.
- '``^[A-Z][A-Z][0-9]``' MATCHES '``**^AB0** 123$``' - first two characters are letters aind the third is a digit.
- '``^[A-Z][A-Z]*[0-9][0-9]$``' DOES NOT MATCH - the name does not end with the pattern '``[A-Z][0-9][0-9]$``', i.e., it ends with four digits, not two.
- '``^[A-Z][0-9]*$``' DOES NOT MATCH - the pattern specifies that second character and all those that follow, if present, must be digits.

----------------------
Variable-range filters
----------------------

An array of range-specification strings may be supplied in the '``Variable-range filters``'
argument.  If supplied, only features having numerical values in the specified column
of **variableMetadata** that fall within the specified ranges will be retained
in the output.  Each range is a string of three colon-separated values (e.g., '``mz:200:800``') in the
following order:

- the **name of a column** of **variableMetadata** which must have numerical data (only letters, digits, periods, and underscores are permitted in the name itself), e.g., '``mz``';
- the **minimum allowed value** in that column for the feature to be retained, e.g., '``200``';
- the **maximum allowed value**, e.g., '``800``'.

Note for the range specification strings:

- **If the "maximum" is less than the "minimum", then the range is exclusive**  (e.g., '``mz:800:200``' means retain only features whose mz is NOT in the range 200-800)
- **If the name supplied in the first field** is '``FEATMAX``',  then the string is defining the **threshold for the maximum intensity** for each feature in the dataMatrix.

  - For example, '``FEATMAX:1e6:``' would specify  that any feature would be excluded if no sample had an intensity for that feature greater than 1,000,000.
  - Although a maximum may be specified, it seems unlikely that this would be useful. Note that when the "maximum" is less than the "minimum" for the FEATMAX range specification, then the specification is ignored.

----------------------------------
Data transformation and imputation
----------------------------------

Data may optionally be log2- or log10-transformed.

Negative intensities are always substituted with missing values before imputation, even when no transformation is chosen.

Missing intensity data values may optionally be imputed.  Missing values may be substituted:

- with zeros (as may be appropriate for univariate analysis)
- with the median for the feature (as may be appropriate for multivariate analysis).

  - Note that the median feature-intensity is computed for the samples *before* variable-range filters are applied.

-----------------------------------------
Optional Computation of Treatment Centers
-----------------------------------------

A "center" for each treatment may be computed in lieu of all the samples for each treatment.

- '``none``' - Return all samples; do not compute centers.
- '``centroid``' - For each treatment, return only the centroid (the treatment-center computed as the mean intensity for each feature).
- '``median``' - For each treatment, return only the treatment-center computed as the median intensity for each feature.
- '``medoid``' - For each treatment, return only the medoid (the sample most similar to the other samples for that treatment).  This choice requires that the '``Imputation of missing values``' argument must not be set to '``none``'.

The medoid is the sample having the smallest sum of its distances from other samples in the treatment:

- Because principal components are uncorrelated, distances are computed in the space defined by the principal-component scores to minimize the distortion of computed distances by correlated features.
- Because principal components are used to compute distances, no missing values are permitted, which is why the '``Imputation of missing values``' argument must not be set to '``none``'.
- The distances are used to identify the medoid using code adapted from https://web.archive.org/web/20191231012914/https://www.biostars.org/p/11987/#11989

-----------------------------------------------------------------------------

----------------
WORKING EXAMPLES

+------------------------------------------------------------------------------------------------------------------------------------------------------+
| https://raw.githubusercontent.com/HegemanLab/w4mclassfilter_galaxy_wrapper/master/tools/w4mclassfilter/test-data/input_variableMetadata.tsv          |
+------------------------------------------------------------------------------------------------------------------------------------------------------+

-------------------------------
Example without Range-Filtering
-------------------------------

This example retains only samples whose '``gender``' attribute is '``M``'.

**Input parameters**

+---------------------------------------------+-------------------------------+
| Input Parameter                             | Value                         |
+=============================================+===============================+
| Column that names the sample class          | gender                        |
+---------------------------------------------+-------------------------------+
| Sample-class names                          | M                             |
+---------------------------------------------+-------------------------------+
| Exclude/include named classes               | filter-in                     |
+---------------------------------------------+-------------------------------+
| Use 'wild-cards' or 'regular expressions'   | wild-cards                    |
+---------------------------------------------+-------------------------------+
| Variable range-filters                      | (Leave this field empty.)     |
+---------------------------------------------+-------------------------------+
| Data transformation                         | none                          |
+---------------------------------------------+-------------------------------+
| Missing-value imputation                    | center                        |
+---------------------------------------------+-------------------------------+
| Sample-sort column                          | sampleMetadata                |
+---------------------------------------------+-------------------------------+
| Feature-sort column                         | variableMetadata              |
+---------------------------------------------+-------------------------------+
| Compute centers for classes                 | none                          |
+---------------------------------------------+-------------------------------+

**Expected outputs**

+-------------------+-------------------------------------------------------------------------------------------------------------------------------------------------+

+-------------------+-------------------------------------------------------------------------------------------------------------------------------------------------+
| Variable metadata | https://raw.githubusercontent.com/HegemanLab/w4mclassfilter_galaxy_wrapper/master/tools/w4mclassfilter/test-data/expected_variableMetadata.tsv  |
+-------------------+-------------------------------------------------------------------------------------------------------------------------------------------------+

----------------------------
Example with Range-Filtering
----------------------------

This example retains only features whose ``mz`` is greater than 200, whose ``rt`` is less than 800, and whose maximum intensity across all samples is 2,000,000.
This example retains all samples (except those having zero variance for all feature), although it would be possible to filter on samples as well.

**Input parameters**

+---------------------------------------------+-----------------------------------+
| Input Parameter                             | Value                             |
+=============================================+===================================+
| Column that names the sample class          | sampleMetadata                    |
+---------------------------------------------+-----------------------------------+
| Sample-class names                          | HU_13[48]                         |
+---------------------------------------------+-----------------------------------+
| Exclude/include named classes               | filter-out                        |
+---------------------------------------------+-----------------------------------+
| Use 'wild-cards' or 'regular expressions'   | regular-expressions               |
+---------------------------------------------+-----------------------------------+
| Variable range-filters                      | FEATMAX:20.93157:,mz:200:,rt::800 |
+---------------------------------------------+-----------------------------------+
| Data transformation                         | log2                              |
+---------------------------------------------+-----------------------------------+
| Missing-value imputation                    | zero                              |
+---------------------------------------------+-----------------------------------+
| Sample-sort column                          | sampleMetadata                    |
+---------------------------------------------+-----------------------------------+
| Feature-sort column                         | variableMetadata                  |
+---------------------------------------------+-----------------------------------+
| Compute centers for classes                 | none                              |
+---------------------------------------------+-----------------------------------+

**Expected outputs**

+-------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+

+-------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
| Sample metadata   | https://raw.githubusercontent.com/HegemanLab/w4mclassfilter_galaxy_wrapper/master/tools/w4mclassfilter/test-data/rangefilter_sampleMetadata.tsv   |
+-------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
| Variable metadata | https://raw.githubusercontent.com/HegemanLab/w4mclassfilter_galaxy_wrapper/master/tools/w4mclassfilter/test-data/rangefilter_variableMetadata.tsv |
+-------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+

--------------------------------
Example with Treatment-Centering
--------------------------------

This example retains only the samples that are medoids for their gender.

**Input parameters**

+---------------------------------------------+-----------------------------------+
| Input Parameter                             | Value                             |
+=============================================+===================================+
| Column that names the sample class          | gender                            |
+---------------------------------------------+-----------------------------------+
| Sample-class names                          | (Leave this field empty.)         |
+---------------------------------------------+-----------------------------------+
| Exclude/include named classes               | filter-out                        |
+---------------------------------------------+-----------------------------------+
| Use 'wild-cards' or 'regular expressions'   | wild-cards                        |
+---------------------------------------------+-----------------------------------+
| Variable range-filters                      | (Leave this field empty.)         |
+---------------------------------------------+-----------------------------------+
| Data transformation                         | none                              |
+---------------------------------------------+-----------------------------------+
| Missing-value imputation                    | zero                              |
+---------------------------------------------+-----------------------------------+
| Sample-sort column                          | gender                            |
+---------------------------------------------+-----------------------------------+
| Feature-sort column                         | rt                                |
+---------------------------------------------+-----------------------------------+
| Compute centers for classes                 | medoid                            |
+---------------------------------------------+-----------------------------------+

**Expected outputs**

+-------------------+----------------------------------------------------------------------------------------------------------+
| Expected Output   | Download from URL                                                                                        |
+===================+==========================================================================================================+
| Data matrix       | https://raw.githubusercontent.com/HegemanLab/w4mclassfilter/master/tests/testthat/exp_cent_medoid_dm.tsv |
+-------------------+----------------------------------------------------------------------------------------------------------+
| Sample metadata   | https://raw.githubusercontent.com/HegemanLab/w4mclassfilter/master/tests/testthat/exp_cent_medoid_sm.tsv |
+-------------------+----------------------------------------------------------------------------------------------------------+
| Variable metadata | https://raw.githubusercontent.com/HegemanLab/w4mclassfilter/master/tests/testthat/exp_cent_medoid_vm.tsv |
+-------------------+----------------------------------------------------------------------------------------------------------+
    ]]></help>
    <citations>
        <!-- Giacomoni_2014 W4M 2.5 -->
        <citation type="doi">10.1093/bioinformatics/btu813</citation>
        <!-- Guitton_2017 W4M 3.0 -->
        <citation type="doi">10.1016/j.biocel.2017.07.002</citation>
        <!-- Kuhl_2012 CAMERA -->
        <citation type="doi">10.1021/ac202450g</citation>
        <!-- Smith_2006 XCMS -->
        <citation type="doi">10.1021/ac051437y</citation>