annotate gather.xml @ 0:6acd7c0ad672 draft default tip

"planemo upload for repository https://github.com/shenwei356/csvtk commit 3a97e1b79bf0c6cdd37d5c8fb497b85531a563ab"

<tool id="csvtk_gather" name="csvtk-gather" version="@VERSION@+@GALAXY_VERSION@">
    <description> column(s) into key-value pairs</description>
    <macros>
        <import>macros.xml</import>
    </macros>
    <expand macro="requirements" />
    <expand macro="version_cmd" />
    <command detect_errors="exit_code"><![CDATA[

###################
## Start Command ##
###################
csvtk gather --num-cpus "\${GALAXY_SLOTS:-1}"

    ## Add additional flags as specified ##
    #######################################
    $global_param.illegal_rows
    $global_param.empty_rows
    $global_param.header
    $global_param.lazy_quotes

    ## Set Tabular input/output flag if first input is tabular ##
    #############################################################
    #if $in_1.is_of_type("tabular"):
        -t -T
    #end if

    ## Set input files ##
    #####################
    $in_1

    ## Specify fields to use ##
    ###########################
    -F -f '$column_text.in_text'

    ## Specific inputs ##
    #####################
    -k '$key_string'
    -v '$value_string'
    
    ## Keep only Key/value columns ##
    #################################
    #if $only_input_columns == 'Yes'
        | csvtk cut -F -f '$key_string','$value_string'

        #if $in_1.is_of_type("tabular"):
            -t -T
        #end if
    #end if

    ## To output ##
    ###############
    > gathered

    ]]></command>
    <inputs>
        <expand macro="singular_input"/>
        <expand macro="fields_input"/>
        <param name="key_string" type="text"
            optional="false"
            argument="-k"
            label="Name of Key Column"
            help="Set name of key column that gathered field will output to">
            <expand macro="text_sanitizer" />
        </param>
        <param name="value_string" type="text"
            optional="false"
            argument="-v"
            label="Name of Value Column">
            <expand macro="text_sanitizer" />
        </param>
        <param name="only_input_columns" type="boolean"
            truevalue="Yes"
            falsevalue="No"
            label="Keep only Key and Value column(s) generated"
            help="Removes all columns but the input labeled key and value columns"
        />
        <expand macro="global_parameters" />
    </inputs>
    <outputs>
        <data format_source="in_1" from_work_dir="gathered" name="gathered" label="${in_1.name} gathered on column(s) ${column_text.in_text}" />
    </outputs>
    <tests>
        <test>
            <param name="in_1" value="csv.csv" />
            <param name="key_string" value="1" />
            <param name="value_string" value="2" />
            <conditional name="column_text">
                <param name="select" value="string" />
                <param name="in_text" value="1" />
            </conditional>
            <output name="gathered" file="gathered.csv" ftype="csv" />
        </test>
    </tests>
    <help><![CDATA[
    
Csvtk - Gather Help
-------------------

Info
####

Csvtk gather gathers columns into key-value pairs

.. class:: warningmark

    Single quotes are not allowed in text inputs!

@HELP_INPUT_DATA@


Usage
#####

**Ex. Gather with column 1:**

Suppose we had the following table:

+---------+------------+-----------+
| Name    | Blood Type | Frequency |
+=========+============+===========+
| Bob     | A          | 4         |
+---------+------------+-----------+
| Jacob   | B          | 5         |
+---------+------------+-----------+
| Matthew | O          | 12        |
+---------+------------+-----------+
| Daniel  | AB         | 1         |
+---------+------------+-----------+

If we did a gather on column 1 creating a key column called "Key" and a value column called "Output"
we would get the following result.

+------------+-----------+------+---------+
| Blood Type | Frequency | Key  | Output  |
+============+===========+======+=========+
| A          | 4         | Name | Bob     |
+------------+-----------+------+---------+
| B          | 4         | Name | Jacob   |
+------------+-----------+------+---------+
| O          | 12        | Name | Matthew |
+------------+-----------+------+---------+
| AB         | 1         | Name | Daniel  |
+------------+-----------+------+---------+

----

**Ex. Gather with 2 columns:**

Same starting table

+---------+------------+-----------+
| Name    | Blood Type | Frequency |
+=========+============+===========+
| Bob     | A          | 4         |
+---------+------------+-----------+
| Jacob   | B          | 5         |
+---------+------------+-----------+
| Matthew | O          | 12        |
+---------+------------+-----------+
| Daniel  | AB         | 1         |
+---------+------------+-----------+

Now, if we specify the input columns as "1,2" to get columns 1 and 2 targeted as the key columns (called key),
we get the following output:

+-----------+------------+---------+
| Frequency | Key        | Output  |
+===========+============+=========+
| 4         | Name       | Bob     |
+-----------+------------+---------+
| 4         | Blood Type | A       |
+-----------+------------+---------+
| 4         | Name       | Jacob   |
+-----------+------------+---------+
| 4         | Blood Type | B       |
+-----------+------------+---------+
| 12        | Name       | Matthew |
+-----------+------------+---------+
| 12        | Blood Type | O       |
+-----------+------------+---------+
| 1         | Name       | Daniel  |
+-----------+------------+---------+
| 1         | Blood Type | AB      |
+-----------+------------+---------+

----

@HELP_COLUMNS@


@HELP_END_STATEMENT@


    ]]></help>
    <expand macro="citations" />
</tool>