view hexagram-6ae12361157c/hexagram/hexagram.xml~ @ 0:1407e3634bcf draft default tip

Uploaded r11 from test tool shed.

<?xml version="1.0"?>
<tool id="hexagram" name="Hexagram Visualization" version="0.1">
    <description>Interactive hex grid clustering visualization</description>
    <requirements>
        <!--
            Go get the drl-graph-layout package as defined in
            tool_dependencies.xml
        -->
        <requirement type="package" version="1.1">drl-graph-layout</requirement>
        <!--
            And go get some Python modules that aren't standard.
        -->
        <requirement type="python-module">numpy</requirement>
        <requirement type="python-module">scipy</requirement>
    </requirements> 
    <!-- 
        This is the command to run as a Cheetah template.
        We do fancy iteration over multiple score matrices (see
        ../plotting/xy_plot.xml).
    -->
    <command interpreter="python">hexagram.py 
		#for $i, $s in enumerate( $similarity )
			"${s.similarity_matrix.file_name}"
		#end for
		 #for $i, $s in enumerate ($similarity)
            --names "${s.similarity_matrix.name}"
        #end for
        #for $i, $s in enumerate( $scores )
            --scores "${s.score_matrix.file_name}"
        #end for
        #if $query:
            --query "$query"
        #end if
        #if $colormaps
            --colormaps "$colormaps"
        #end if
        --html "$output"
        --directory "$output.files_path"
        --truncation_edges $edges
        #if $singletons
            --include-singletons
        #end if
        #if $nostats
            --no-stats
        #end if
    </command>
    <inputs>
		<repeat name="similarity" title="Similarity Matrices">
        	<param name="similarity_matrix" type="data" format="tabular" 
            	label="Similarity matrix of signatures to visualize"/>
		</repeat>
        <repeat name="scores" title="Scores">
            <param name="score_matrix" type="data" format="tabular" 
                label="Score matrix for signatures to visualize"/>
        </repeat>       
        <param name="colormaps" type="data" format="text" optional="true" 
            label="Colormap configuration file"/>
        <param name="edges" type="integer" value="10" 
            label="Number of edges to use per node"/>
        <param name="query" type="text" 
            label="Name of query signature"
            help="A signature name, or empty for no query"/>
        <param name="singletons" type="boolean" 
            label="Keep unconnected singleton signatures"/>
        <param name="nostats" type="boolean" 
            label="Skip calculation of heatmap clumpiness statistics"/>
    </inputs>
    <outputs>
        <data name="output" label="Hexagram Visualization($edges edges)" 
            format="html" hidden="false"/>
    </outputs>
    <stdio>
        <!-- 
            The tool catches all errors and returns 1, or 0 if no errors 
            happened. 
        -->
        <exit_code range="1" level="fatal" 
            description="Error in visualization generator (see below)" />
        <exit_code range="2:" level="fatal" description="Unhandleable error" />
    </stdio>
    <help>

Hexagram Visualization
======================

This tool produces a "hexagram visualization": an interactive Google Maps-based two-dimensional layout of the similarity matrix data, on a hexagonal grid, with the score matrix data represented as different available colorings of the hexagons. This visualization is an HTML web page with associated support files, and appears as the tool's output in your Galaxy history; to open it, click on the eyeball icon.

If, instead of a rich interactive Web application, you get a boring white page with some text on it, you probably have tool output sanitization on. Turn sanitization off in your universe_wsgi.ini, or download the visualization, unzip it, and open the HTML file it contains. If you want to use a downloaded visualization, you will need to open it in a browser other than Chrome (which, for security reasons, does not let local Web pages access local files programmatically).

Input Format
------------

The tool takes three types of input files:

Similarity Matrix
+++++++++++++++++

The only required input file is a *similarity matrix*, which contains similarity information over a set of "samples" or "signatures". This file is a sparse matrix represented as three tab-delimited columns; the first two columns of each row contain the names of two signatures, and the last column contains a nonzero, non-negative floating-point "similarity" between them. No headers are used. Self-edges are permitted, and self-edges with a similarity of 1 will be added to every node if "Keep unconnected singleton signatures" is checked. The input similarity matrix need not describe a similarity graph that is connected, and similarity need not be transitive in any way.

Score Matrices
++++++++++++++

You almost certainly want to run the tool with one or more *score matrices*, which specify some attribute data to overlay on the signature hexes once they are arranged. Any number of score matrices can be specified. Each score matrix is a TSV file; the first column contains sample names, and any other columns contain the values of attributes for those samples. Score matrices have a header line, which specifies some (unused) name for the column of sample names, and the name of the attribute described by each column of attribute data.

Attribute data may be continuous (floating-point numbers), categorical (non-negative integers), or binary (0 or 1). The visualizer assumes that each column is the most restrictive type that will fit the data given; a column with all 0.0s and 1.0s will be assumed to be binary, even if the user intended it to represent a continuous value. Categories in categorical columns are assumed to be numbered from 0, even if no 0s appear in the column.

Colormap Configuration File
+++++++++++++++++++++++++++

If you have categorical data to display, you probably want to write a *colormap configuration file* for it. Categorical data is displayed in the visualizer with one color per category; if you want to specify particular colors for each category, or names for each category (instead of the default labels of 0 through n), you need a colormap configuration file. Each line in this file should begin with the name of a categorical attribute, followed by, for each category used in that attribute, the category number, the desired name for the category, and a CSS color (like "white" or "#FFFFFF" or "rgb(255,255,255)) to use to represent that category. Fields on each line are separated by tab characters.

    </help>
</tool>