<?xml version="1.0"?>
<tool name="honto" id="honto" version="0.1.0">
    <description>A novel method for assessing and measuring homophily in networks</description>
    
    <!-- Tool developers -->
    <creator>
        <person givenName="Paolo" familyName="Franciosa" 
                url="http://www.statistica.uniroma1.it/users/pfrancio/" 
                email="paolo.franciosa@uniroma1.it" />

        <person givenName="Nicola" familyName="Apollonio" 
                url="https://www.iac.rm.cnr.it/~apollonio/" 
                email="nicola.apollonio@cnr.it" />

        <person givenName="Daniele" familyName="Santoni" 
                url="http://www.iasi.cnr.it/~dsantoni/" 
                email="daniele.santoni@iasi.cnr.it" />

        <person givenName="Fabio" familyName="Cumbo" 
                url="https://fabio-cumbo.github.io/" 
                email="fabio.cumbo@gmail.com" />
    </creator>

    <!-- Define dependencies -->
    <requirements>
        <requirement type="package" version="0.1.0">honto</requirement>
    </requirements>

    <command detect_errors="exit_code">
<![CDATA[
    ln -s ${edges} edges.txt;
    ln -s ${nodes} nodes.txt;

    honto 

    --input_edges edges.txt
    --input_nodes nodes.txt
    --weight_threshold ${weight_threshold}
    
    #if $isolated == "yes":
        --isolated
    #end if

    #if $log_transform.enable_lt == "yes":
        --log_transform
        #if $log_transform.scale_log.scale_type == "factor":
            --scale_factor $log_transform.scale_log.scale_value
        #elif $log_transform.scale_log.scale_type == "from_one":
            --scale_from_one
        #end if
    #end if

    --cmap $heatmap.cmap
    --vmin $heatmap.vmin
    --vmax $heatmap.vmax
    --center $heatmap.center
    #if $heatmap.cbar == "yes":
        --cbar
    #end if
    
    --nproc "\${GALAXY_SLOTS:-4}"
    --overwrite
    --verbose
]]>
    </command>

    <inputs>
        <!-- Select edges -->
        <param name="edges" type="data" format="tsv" 
               label="Select a network" 
               help="Input network with the list of edges, one per line." />
        
        <!-- Select colors -->
        <param name="nodes" type="data" format="tsv" 
               label="Select a nodes definition file" 
               help="This file contains a mapping between node names and colors." />
        
        <!-- Weight threshold -->
        <param name="weight_threshold" type="integer" value="700" min="0" 
               label="Weight threshold" 
               help="Threshold for considering edges based in their weight." />
        
        <!-- Isolated -->
        <param name="isolated" type="boolean" checked="false" truevalue="yes" falsevalue="no" 
               label="Insert isolated nodes" />
        
        <!-- Log-transformation options -->
        <conditional name="log_transform">
            <!-- Enable log-transformation -->
            <param name="enable_lt" type="boolean" checked="false" truevalue="yes" falsevalue="no" 
                   label="Log-transform z-scores" />

            <when value="yes">
                <!-- Scale options -->
                <conditional name="scale_log">
                    <!-- Select a scale option -->
                    <param name="scale_type" type="select" label="Choose one of the available scale options">
                        <option value="default" selected="true">Scale automatically</option>
                        <option value="factor">Factor</option>
                        <option value="from_one">Truncate from one</option>
                    </param>

                    <!-- In case of "factor" -->
                    <when value="factor">
                        <param name="scale_value" type="float" value="0.0"
                               label="Scale factor" 
                               help="Rescale z-scores with this constant before log-transforming values." />
                    </when>
                </conditional>
            </when>
        </conditional>
        
        <!-- Heatmap customization options -->
        <section name="heatmap" expanded="true" 
                 title="Heatmap customization"
                 help="Access advanced options to customize the produced heatmap by specifying the colormap, scale, and color bar">
            <!-- Colormap -->
            <param name="cmap" type="text" value="PiYG" 
                   label="Heatmap colormap" />
            
            <!-- Vmin -->
            <param name="vmin" type="float" value="2.2967"
                   label="Select a vmin value" 
                   help="Min value to anchor the colormap" />
            
            <!-- Vmax -->
            <param name="vmax" type="float" value="4.3957"
                   label="Select a vmax value" 
                   help="Max value to anchor the colormap" />
            
            <!-- Center -->
            <param name="center" type="float" value="2.9957"
                   label="Select a center" 
                   help="The value at which to center the colormap when plotting divergent data" />
            
            <!-- Cbar -->
            <param name="cbar" type="boolean" checked="false" truevalue="yes" falsevalue="no" 
                   label="Add a color bar" />
        </section>
    </inputs>

    <outputs>
        <!-- Output z-scores edges -->
        <data format="tsv" name="zscores_edges" 
              label="${tool.name} on ${on_string}: Edges z-scores" 
              from_work_dir="edges_zscores_edges.txt" />
        
        <!-- Output z-scores singletons -->
        <data format="tsv" name="zscores_singletons" 
              label="${tool.name} on ${on_string}: Singletons z-scores" 
              from_work_dir="edges_zscores_singletons.txt" />
        
        <!-- Output heatmap -->
        <data format="pdf" name="out_heatmap" 
              label="${tool.name} on ${on_string}: Heatmap" 
              from_work_dir="edges.pdf" />
    </outputs>

    <help><![CDATA[
**Homophily Network Tool**

`honto` is a tool designed for assessing and measuring homophily in networks whose nodes have categorical attributes, 
namely when the nodes of networks come partitioned into classes.

Homophily evaluation is performed through the comparison between the relative edge density of the subgraphs, 
induced by each class, and the corresponding expected relative edge density under a null model.

The novelty of our approach consists in prescribing an endogenous null model, namely, the sample space of the null model 
is built on the input network itself. This allows us to give exact explicit expressions for the z-scores of the 
relative edge density of each class as well as other related statistics

-----

**Input**

The first input is file representing an undirected network composed by a list of edges like the example below.
No header lines are allowed.

+--------+--------+
| TP0001 | TP1015 |
+--------+--------+
| TP0001 | TP0949 |
+--------+--------+
| TP0001 | TP0692 |
+--------+--------+
| ...    | ...    |
+--------+--------+
| TP0976 | TP0977 |
+--------+--------+
| TP1032 | TP1033 |
+--------+--------+


Please note that the above mentioned file could also have an additional column with numeric weight values.
You may want to avoid considering some nodes by applying a threshold on this column.

The second input is the nodes definition file. It contains a row for each node in the network with two columns
with a mapping between the node name and a color or group id, like in the example below.
No header lines are allowed in this case either.

+--------+-----+
| TP0001 | L   |
+--------+-----+
| TP1015 | K   |
+--------+-----+
| TP0949 | U   |
+--------+-----+
| TP0692 | L   |
+--------+-----+
| ...    | ... |
+--------+-----+
| TP1032 | X   |
+--------+-----+
| TP1033 | X   |
+--------+-----+

-----

**Output**

The tool produces three output files. Two of them contains the z-scores for both edges and singletons.
The third output is a PDF with the final heatmap.

-----

.. class:: infomark

**Notes**

Please visit the official GitHub repository_ for other information about `honto`.

.. _repository: https://github.com/fabio-cumbo/honto
    ]]></help>

</tool>