      _  _      _
     (_)| |___ (_)__   __ ___
     | ||  _  \| |\ \ / // _ \
     | || / \ || | \ V /|  __/   
   __| ||_| |_||_|  \_/  \___/
   \___/

jhive - Java GUI for hive plots

Version 0.2.7 (January 21st, 2014)
Written by Ka Ming Nip <kmnip@bcgsc.ca>
Copyright 2012-2014 Canada's Michael Smith Genome Sciences Centre

################################################################################

Web documentation and tutorials (INCOMPLETE; work in progress)

  http://www.bcgsc.ca/wiki/display/jhive/home

To learn about hive plots, see

  http://www.hiveplot.com

If you use hive plots, please cite us

  M. Krzywinski, et al., Hive plots-rational approach to visualizing networks, Brief Bioinform, Dec 9 2011.

################################################################################

Table of Contents

1. UPDATES

2. RUNNING jhive

3. INPUT FILE FORMAT

4. DRAWING A HIVE PLOT

5. SETTINGS

6. OTHER FEATURES

7. EXTERNAL PACKAGES AND FILES USED

################################################################################

1. UPDATES

Version 0.2.7
* NEW: Display the current min/max values for each axis when either:
       (i) "auto" checkbox is checked, or
       (ii) "auto" checkbox is unchecked, but the textfield is empty.
* NEW: Option to cancel the current running task (ie. loading file, applying settings).
       The "Apply" button would become the "Cancel" button and vice versa.
* NEW: New network parameter for axis/position assignment, "reachability".
       The reachability of a node defines how many other nodes can reach this node.       
       For example:
        a -> b
        b -> x
       
        node | reachability | explaination
       ------+--------------+-----------------------------------
         a   |  0           | No possible paths to node 'a'.
         b   |  1           | One path from node 'a'.
         x   |  2           | Two paths from nodes 'a' and 'b'.
* NEW: Added 'otherpos' attribute for 'diff=onaxis' nodes in diff plots.
       It tells you whether the other node is 'higher' or 'lower' on the same axis of
       the other hive plot.
* FIX: Reduced runtime for the overall process for calculating "clustering coefficient".
* FIX: Reduced runtime for the graph-building process when a graph file is loaded.
* FIX: Reduced runtime for name-based node search (ie. via format rules).

Previous updates for Version 0.2.x

Version 0.2.6
* NEW: Added 'otheraxis' attribute for 'diff=offaxis' nodes in diff plots.
       It tells you which axis the other node is located on the other hive plot.

Version 0.2.5
* NEW: Dump the visible items of a hive plot into a DOT file. 
* FIX: Some controls are not set properly when settings were loaded from file.

Version 0.2.4
* FIX: Some mappings were done incorrectly in differential hive plots.
* FIX: Some disabled controls cannot be re-enabled again.

Version 0.2.3
* NEW: Re-organized controls for "Axis", "Position", "Edge", "Node" columns from
       the settings panel into tabs.
* NEW: Setting to fine how similar nodes are clustered to generate a differential
       hive plot, ie.
       1 : 1, same name
       1 : 1
       1 : n
       n : n
       n : m
       
       If the mapping is not "1 : 1, same name", similar nodes not having the
       same name would still be clustered according to the mapping selected.
       
       Clustered nodes have 2 new attributes 'nodes_a' and 'nodes_b' that store
       the names of component nodes from the original hive plots.
* NEW: Support double-quoted node id and attributes in DOT.
* NEW: Support a wider range of characters for node id and attributes in DOT, ie.
       any non-space character that is not [#;="[]{}]
* NEW: Support statements for default node/edge attributes in DOT.
* NEW: 3 new node parameters for axis/position assignments:
       betweeness, eigenvector centrality, PageRank
* FIX: Improved speed in drawing hive plots. 
* FIX: Over-counting of next-neighbors when calculating "branching".
* FIX: Calculating node properties of large networks would freeze the main window.

Version 0.2.2
* NEW: Interval-based zoom; set the absolute min/max value for individual axis
       or all axes.
* NEW: Axis-specific normalization.
* FIX: Logarithmic transform now applies to node positions in a hive plot
       (instead of the original values used to calculate node positions).
* FIX: The 'src' attribute is not set for some edges in differential hive plots.
* FIX: Drag-and-drop of files does not work in some platforms.
* FIX: Selecting a node parameter for position assignment for all 3 axes causes
       a hive plot to be drawn 4 times.

Version 0.2.1
* NEW: Option to log-transform positions of each axis.
* NEW: Merged the buttons "Append format rules" and "Replace format rules" into
       one button "Open format Rules". The user has the option to specify whether
       to append or replace in the file chooser.
* NEW: Node properties are calculated as needed instead of calculated upfront
       when the DOT file is loaded.
* FIX: Much smoother bezier curves/ribbons in hive plots.
* FIX: Concurrency issues.

Version 0.2.0
* NEW: Support DOT files of directed multigraphs.
* NEW: Support DOT files of undirected graphs or multigraphs.
* NEW: Support DOT files that only have edges, ie. nodes are not defined
       explicitly.
* NEW: Option to bin nodes evenly along the axis. This is particularly useful
       when the graph has more than thousands of nodes.
* NEW: Save settings (the state of the controls in the settings panel only) to
       an XML file. Conflicting (ie. disabled/greyed-out) settings components
       would not be saved.
* NEW: Restore settings from an XML file. Can also be done via drag-and-drop of
       a settings file into the settings panel.

################################################################################

2. RUNNING jhive

java -jar jhive.jar

Please make sure the 'lib' directory and 'jhive.jar' are under the same directory.
Java Runtime Environment 1.6 or above is required.

################################################################################

3. INPUT FILE FORMAT

The supported format of input graph files is in a subset of the DOT format.

Directed and undirected (multi)graphs are supported.

For example:

digraph GraphName {
A [attribute1=100 attribute2=1000] # node 'A'
B [attribute1=200 attribute2=2000] # node 'B'
C [attribute1=400 attribute2=4000] # node 'C'
A -> B [atttribute1=100 attribute2=1000 attribute3=positive] # edge from 'A' to 'B'
B -> C [attribute1=200 attribute2=2000 attribute3=negative] # edge from 'B' to 'C'
}

There are more examples in the 'sample_graphs' directory.

If nodes have a "name" attribute, the value would replace the node's name in
the hive plot. For example, the name of this node is "new" instead of "old":

old [name=new]

################################################################################

4. DRAWING A HIVE PLOT

a. From the "File" menu > select "Open Graph File(s)..."
b. Select input file (e.g. sample_graphs/regulondb.txt)
c. Adjust settings and add format rules, as required.
d. Click the "Apply" button to redraw the plot.
e. Repeat c,d as necessary.

################################################################################

5. SETTINGS

Settings are divided into 5 parts.

a. Axis

   Controls for axis assignment of nodes.

   (i)  Dropdown box for assigning nodes to axes by one of the following parameters:
        - type                   : type of a node, ie. source, sink, both source and sink
        - name                   : name of a node
        - flow                   : flow of a node; out-degree minus in-degree
        - degree                 : number of edges incident on a node
        - clustering coefficient : tendency of a node to cluster together
        - branching (nn/n)       : ratio of next-neighbors to neighbors
        - closeness              : average distance between a node and all others reachable
                                   from it
        - eccentricity           : maximum distance between a node and all others reachable
                                   from it
        - betweeness             : number of shortest paths on which a node lies
        - eigenvector            : popularity of a node based on random walk in the graph.
        - PageRank               : eigenvector with an attenuation factor.
        - node attributes from input graph file
                       : These are blue in the dropdown box and are given a '$' prefix
   
   (ii)  textfields for defining the rule of each axis
   (iii) check-boxes for quickly switching on/off the rules
     
   Axis rules can be one or more regular expressions.
   The regular expressions are evaluated with JavaScript.
   An empty rule corresponds to "everything else".
  
   Example 1, numerical attributes:
   a1 rule: x<30            Nodes with x < 30 are assigned to axis 1.
   a2 rule: x>=30 && x<=60  Nodes with x in range [30,60] are assigned to axis 2.
   a3 rule:                 All other nodes.
   
   Example 2, string attributes:
   a1 rule: 'x'=='blue'     Nodes where x is 'blue' are assigned to axis 1.
   a2 rule: 'x'=='yellow'   Nodes where x is 'yellow' are assigned to axis 2.
   a3 rule: 'x'=='brown'    Nodes where x is 'brown' are assigned to axis 3.
   
   Note the usage of quotations on variable x in example 2 but not in example 1.
   
b. Position

   Controls for position assignment of nodes.
   
   (i)    Dropdown boxes for assigning nodes a position on the axes by a node parameter.
          All node parameters used in axis assignment except 'type' can be used.
   (ii)   Textfields to specify the smallest value allowed for each axis. Checkboxes to determine the values automatically.
   (iii)  Textfields to specify the largest value allowed for each axis. Checkboxes to determine the values automatically.
   (iv)   Checkboxes to scale positions to fit nodes along the whole axis.
   (v)    Checkboxes to logarithmically transform node positions.
   (vi)   Checkboxes to lay out nodes in descending order (instead of ascending order) from the origin.
   (vii)  Checkbox to lay out nodes on each axis by rank order; nodes do not stack as a result.
   (viii) Checkbox to bin nodes evenly along the axis; textfield to specify the number of bins.
   
c. Edge

   Controls to set the asthetics of edges.
   
   (i)   combo-box to select the default color of edges
   (ii)  slider for minimum opacity of edges
   (iii) 'normalize' check-box
         When checked, opacity is proportional to the amount of overlap.
   (iv)  slider for thickness of edges
   (v)   dropdown box to select the style of edges:
         - curve  : Edges between two positions are drawn as a single curve.
         - fan    : Edges between two positions are fanned out.
         - ribbon : Each edge is drawn as a ribbon, whose width is based on the
                    'span' attribute of the node. 'Span' is defined as a proportion
                    of the axis length. The range of 'span' is [0,1].
   
d. Node
   
   Controls to set the asthetics of nodes.
   
   (i)   combo-box to select the default color of nodes
   (ii)  slider for minimum opacity of nodes
   (iii) 'normalize' check-box
         When checked, opacity is proportional to the amount of overlap.
   (iv)  slider for size of nodes
   (v)   'normalize' check-box
         When checked, node size is proportional to the amount of overlap.
   
e. Format Rules

   Define rules to modify the visibility and asthetics of nodes and edges on the hive plot.
   * Only one rule is allowed per line; each rule is associated with a set of
     appearance modifiers.
   * The first rule has the lowest priority while the last rule has
     the highest priority. If multiple rules act on the same properties of
     the same object, the properties defined by the expression of higher priority
     take precedence.
   * Selected edges are ordered by their depth. Edges in the same depth are
     ordered based on the priority of the corresponding expression.
   * Format Rules are evaluated unpon clicking the "Apply" button.
   * Rules files, a directory of rules files, or text selection of rules can be loaded via
     drag-and-drop onto the Formaut Rules text pane.
   * The syntax of each rule can be one of the following:
        
     (i)   GM # comments          
           - a command that affects the entire hive plot
     (ii)  [AM;...] # comments
           - sets the default appearance modifiers
           - any rules following this line will use these appearance modifiers unless overwritten otherwise
     (iii) QNS [AM;...] # comments
           - applies appearance modifier(s) to the node(s) selected with a Quick Node Selector
     (iv)  QES [AM;...] # comments
           - applies appearance modifier(s) to the edge(s) selected with a Quick Edge Selector
     (v)   CNS [AM;...] # comments
           - applies appearance modifier(s) to the node(s) selected with a Complex Node Selector
     (vi)  CES [AM;...] # comments
           - applies appearance modifier(s) to the edge(s) selected with a Complex Edge Selector

     See below for a definition of each acronym.
     See USECASES.txt for example usecases.
     Sample rules are also provided for the sample graphs.

    ===========================================================
    General Command (GM):
        clear   : hides all nodes and edges from the hive plot
    ===========================================================
    Appearance Modifier (AM):
        -------------------------------------------------------
        thickness=int       : thickness of the edge(s) selected
                              'int' must be an integer >= 0
        width=int           : equivalent of 'thickness=int'
        -------------------------------------------------------
        size=int            : radius of the node(s) selected
                              'int' must be an integer >= 0
        radius=int          : equivalent of 'size=int'
        -------------------------------------------------------
        rgb=(int,int,int)   : color of the item(s) selected, as an RGB value
                              'int' must be an integer in range [0,255]
        rgb=int             : color of the item(s) selected, as an index of the default palette
                              'int' must be an integer >= 0
        rgb=str             : color of the item(s) selected, as a name
                              'str' must be one of {
                                  optblue, optgreen, optyellow, optorange, optred, optviolet, optpurple,
                                  white,
                                  vvvvlgrey, vvvlgrey, vvlgrey, vlgrey, lgrey, grey, dgrey, vdgrey, vvdgrey, vvvdgrey, vvvvdgrey,
                                  black,
                                  vlred, lred, red, dred,
                                  vlgreen, lgreen, green, dgreen,
                                  vlblue, lblue, blue, dblue,
                                  vlpurple, lpurple, purple, dpurple,
                                  vlyellow, lyellow, yellow, dyellow,
                                  lime,
                                  vlorange, lorange, orange, dorange
                              }
        rgb=relation        : color of the item(s) selected as a darker or brighter variant of the last color used in Format Rules
                              'relation' must be one of {
                                  brighter,
                                  darker
                              }
        color=(int,int,int) : equivalent of 'rgb=(int,int,int)'
        color=int           : equivalent of 'rgb=int'
        color=str           : equivalent of 'rgb=str'
        color=relation      : equivalent of 'rgb=relation'
        -------------------------------------------------------                
        depth=int           : depth of the item(s) selected
                              All objects in the hive plot have have an initial depth value of 0.
                              All objects selected by a rule have a depth value of 1 by default.
                              'int' must be an integer in range [-2^31-1,2^31-1]
        level=int           : equivalent of 'depth=int'
        z=int               : equivalent of 'depth=int'
        layer=int           : equivalent of 'depth=int'
        -------------------------------------------------------
        opacity=int         : opacity of the item(s) selected
                              'int' must be in an integer range [0,100]
        -------------------------------------------------------                                
        show=boolean        : show or hide the item(s) selected
                              'boolean' must be one of {
                                  yes, y, true, t,
                                  no, n, false, f
                              }                    
        visible=boolean     : equivalent of 'show=boolean'
        appear=boolean      : equivalent of 'show=boolean'
        show                : show items selected
        visible             : equivalent of 'show'
        appear              : equivalent of 'show
        -------------------------------------------------------                                
        autonode=boolean    : flag to automatically show/hide node(s) when incident edge(s) are shown/hidden
                              'boolean' must be one of {
                                  yes, y, true, t,
                                  no, n, false, f
                              }
        autonode            : automatically show/hide node(s) when incident edge(s) are shown/hidden
        -------------------------------------------------------        
        label=boolean       : show or hide the label of the node(s) selected
                              'boolean' must be one of {
                                  yes, y, true, t,
                                  no, n, false, f
                              }
        label               : show the label of the node(s) selcted
        -------------------------------------------------------
    ===========================================================                       
    Quick Node Selector (QNS):
        str   : name of the node
                Space characters and the following characters are not allowed:
                '(', ')', '[', ']', '#', '=', '<', '>', '~', '!', ';'
        .*    : wild card; return all nodes
    ===========================================================
    Quick Edge Selector (QES):
        QNS1 QNS2      : the edge between nodes 'QNS1' and 'QNS2'
        QNS1 QNS2 QNS3 : the edge between nodes 'QNS1' and 'QNS2' and the edge between nodes 'QNS2' and 'QNS3'
    ===========================================================
    Complex Node Selector (CNS):
        n()     : select all nodes in the network       
        n(...)  : nodes that satisfy the conditions in '...'
        !n(...) : complement of the set of nodes returned by n(...)
                
                    '...' must be one of, or a comma-separated list of AS or ICES
                    AS selects nodes based on the nodes' attributes
                    ICES selects nodes based on the qualities of incident edges       
    ===========================================================
    Complex Edge Selector (CES):
        e()     : select all edges in the network       
        e(...)  : edges that satisfy the conditions in '...'
        !e(...) : complement of the set of edges returned by e(...)
        
                    '...' must be one of, or a comma-separated list of AS or ICNS
                    AS selects edges based on the edges' attributes
                    ICNS selects edges based on the qualities of incident nodes 
    ===========================================================
    Internal Complex Node Selector (ICNS):
        n(...)   : incident node(s) of the edge(s) of interest
        n1(...)  : source node(s) of the edge(s) of interest
        n2(...)  : sink node(s) of the edge(s) of interest
        !n(...)  : complement of set of nodes returned by n(..)
        !n1(...) : complement of set of nodes returned by n1(..)
        !n2(...) : complement of set of nodes returned by n2(..)
        
                    '...' as defined in CNS.        
    ===========================================================  
    Internal Complex Edge Selector (ICES):
        e(...)   : incident edge(s) of the node(s) of interest
        e1(...)  : incoming edge(s) to the node(s) of interest
        e2(...)  : outgoing edge(s) from the node(s) of interest
        !e(...)  : complement of set of edges returned by e(..)
        !e1(...) : complement of set of edges returned by e1(..)
        !e2(...) : complement of set of edges returned by e2(..)

                    '...' as defined in CES.
    ===========================================================
    Attribute Selector (AS):
        attr=val   : item(s) has attribute 'attr' with only one value and that value is 'val'
        attr~val   : item(s) has attribute 'attr' with one or more values and one of the values is 'val'
        attr~!val  : item(s) has attribute 'attr' with one or more values and one of the values is not 'val'
        attr>val   : item(s) has numerical attribute 'attr' greater than the value 'val'
        attr>=val  : item(s) has numerical attribute 'attr' greater than or equal to the value 'val'
        attr==val  : item(s) has numerical attribute 'attr' equal to the value 'val'
        attr<=val  : item(s) has numerical attribute 'attr' less than or equal to the value 'val'
        attr<val   : item(s) has numerical attribute 'attr' less than the value 'val'
    ===========================================================
    

################################################################################

6. OTHER FEATURES

a. Double-click on the axis name to clone the corresponding
   axis. Double-click again to colapse the cloned axis.

b. Mouse-over nodes for tooltips of node names.

c. Alternate background color between white and black. Select the
   'View' menu then check/uncheck "reverse background color". It is
   checked by default.

d. Put the settings panel in a separate window. Select the 'View' menu
   then check "show settings in separate window".
   
e. You can generate a differential hive plot based on 2 existing hive plots.
   Please see DIFF.txt for a tutorial.

################################################################################

7. EXTERNAL PACKAGES AND FILES USED

External Java Packages:
* Java Universal Network/Graph Framework
  <http://jung.sourceforge.net>
* Apache Batik SVG Toolkit
  <http://xmlgraphics.apache.org/batik/>

Icons:
* Aha-Soft icons
  <http://www.iconfinder.com/search/?q=iconset%3A16x16-free-toolbar-icons>

################################################################################
EOF
