annotate sampler.xml @ 1:81b079d1642c draft

planemo upload for repository ['https://github.com/brsynth/icfree-ml', 'https://github.com/pablocarb/doebase'] commit 1e01b679611d980f87089184e7d8a538b96d68c7

<tool id="doe_synbio_sampler" name="iCFree sampler" version="@TOOL_VERSION@+galaxy@VERSION_SUFFIX@" license="@LICENCE@">
    <description>Generate data points using latin hypercube sampling (LHS)</description>
    <macros>
        <import>macros.xml</import>
        <token name="@TOOL_VERSION@">2.1.1</token>
    </macros>
    <requirements>
        <requirement type="package" version="@TOOL_VERSION@">icfree</requirement>
    </requirements>
    <expand macro="stdio"/>
    <command detect_errors="exit_code"><![CDATA[
        python -m icfree.sampler
            '$cfps_file'
            --nb-sampling-steps '$adv.nb_sampling_steps'
            --nb-samples '$nb_samples'
            #if str($adv.sampling_ratio) != ""
                #set ratios = ' '.join(['"' + $x + '"' for $x in $adv.sampling_ratio.split()])
                --sampling-ratios $ratios
            #end if
            #if str($adv.seed_cond.seed_param) == 'not_random'
                --seed '$adv.seed_cond.seed'
            #end if
            --output-format 'tsv'
            --output-folder . &&
            mv sampling.tsv '$output_sampling'
    ]]></command>
    <inputs>
        <param name="cfps_file" type="data" format="tabular" label="CFPS parameters and features" />
        <param name="nb_samples" type="integer" value="99" min="1" max="198" label="Number of samples to generate" />
        <section name="adv" title="Advanced Options" expanded="false">
            <param name="nb_sampling_steps" type="integer" value="5" min="1" max="10" label="Number of values for all factors when performing the sampling" />
            <param name="sampling_ratio" type="text" value="" label="Ratios associated for all factors" help="Only float, space separated, are allowed">
                <validator type="regex" message="Float separated by a space between in the range: 0.0 - 1.0">^(?:(0.\d+|1\.0)(\s0?\.\d+|1\.0)*)*$</validator>
            </param>
            <conditional name="seed_cond">
                <param name="seed_param" type="select" label="Seed" help="Choose a seed or let it as random">
                    <option value="random" selected="true">random</option>
                    <option value="not_random">fixed</option>
                </param>
                <when value="random"/>
                <when value="not_random">
                    <param name="seed" type="text" value="0" label="Seed value" help="Only integer allowed">
                        <validator type="empty_field" message="Not empty, select random"/>
                        <validator type="regex" message="Only integer allowed">^(?:\d+)$</validator>
                    </param>
                </when>
            </conditional>
        </section>
    </inputs>
    <outputs>
        <data name="output_sampling" format="tabular" label="${tool.name}" />
    </outputs>
    <tests>
        <!-- test 1: check if identical outputs are produced with default parameters  -->
        <test>
            <param name="cfps_file" value="converter_proCFPS_parameters.tsv" />
            <param name="seed_param" value="not_random" />
            <param name="seed" value="0" />
            <output name="output_sampling" file="sampler_sampling.test-1.tsv" ftype="tabular" compare="diff" />
        </test>
        <!-- test 2: advanced arguments -->
        <test>
            <param name="cfps_file" value="converter_proCFPS_parameters.tsv" />
            <param name="nb_sampling_steps" value="3" />
            <param name="nb_samples" value="100" />
            <param name="sampling_ratio" value="0.4 0.2 0.3" />
            <param name="seed_param" value="not_random" />
            <param name="seed" value="0" />
            <param name="nb_samples" value="100" />
            <output name="output_sampling" file="sampler_sampling.test-2.tsv" ftype="tabular" compare="diff" />
        </test>
    </tests>
    <help><![CDATA[
Sampler
=======

This module generates a list of values for all parameters given in the input file.
The values are generated using a Latin Hypercube Sampling (LHS) method (lhs function from the pyDOE package).
The number of values generated is given by the user and the values are saved in csv or tsv file.

It is important to note that the user can pass some values that he whishes to combine. In this case, we are dealing with discrete space, and because LHS is working on continuous space the result sampling can contain duplicates.
To avoid this, we have set some filters to select the appropriate sampling method:

* If the result sampling contain duplicates, then we replace them by random samples.
* Proceed with full random sampling.
* Generate all the combinations.

Input
-----
* **CFPS Parameters File**: The first column is the parameter (or factor) names. The second column is the maxValue of the parameter that will be used in the sampling. The third column is the concnetration of the stock. The fourth column is the deadVolume of the parameter. This is used to calculate the volume of the parameter that will not be pipetted by the robot (because of viscosity). The fifth column is the specific ratios we want to have for this parameter. If nothing defined, then take ratios given in program options. If one single number is given, then take this number as a const value.

Advanced options:
-----------------
* **Number of sampling steps**: Number of values for all factors when performing the sampling (default: 5)
* **Sampling ratios**: Ratios for all factors when performing the sampling
* **Number of samples**: Number of samples to generate for all factors when performing the sampling (default: 99)

Output
------
* a TSV file with the sampling values for each parameter
    ]]></help>
    <expand macro="creator"/>
    <citations>
        <citation type="bibtex">
            @unpublished{icfree
                author = {Joan Hérisson, Yorgo El Moubayed},
                title = {{icfree}},
                url = {https://github.com/brsynth/icfree-ml/},
            }
        </citation>
    </citations>
</tool>