| Mission Software Resources Contact | ||||||||||||||||||
Institution address
Folkhälsan Inst of Genetics, Folkhälsan Research Center; Haartmaninkatu 8, Biomedicum 1; P.O. Box 63, FI-00014; Univ of Helsinki, Finland
|
Himmeli guideHimmeli requires two input files to work. The first, referred to as the configuration file, contains the instructions that specify where to look for the graph data and how to visualize it. Furthermore, the name of the configuration file is the only command line argument that Himmeli accepts, everything else is defined by the instructions. If you call Himmeli without any command line arguments, a concise listing of all features is printed on the screen. The second file, referred to as the edge file, contains the edges of the graph in tabulated plain text format. The first non-empty line of the file must contain the headings of the variable columns and the subsequent lines specify the graph topology. For each edge, you have to list at least the names of the end points on a single line of text in order for the edge to be registered by Himmeli. Brief instructions on how to install the program on various platforms and operating systems can be found within the installation package. Basic graphA graph is essentialy a set of relationships (edges or links or arcs, depending on context) between distinguishable entities (vertices or nodes). Consequently, the minimum dataset that can be visualized by Himmeli consists of pairs of vertices, denoted by the tail vertex (starting point) and the head vertex (end point). For now, it is assumed that the graph is undirected and no attention is paid to the order of vertices within a pair.For practical reasons, Himmeli needs to know also the file that contains the graph data as a tabulator delimited plain text table (edge file) and the name of the graph for creating the result files later. Below is a transcript of a basic setup for a small graph (on a UNIX system): [vpm himmelidemo]$ cat config.txt GraphName demoGraph EdgeFile edges.txt EdgeHeadVariable HEAD EdgeTailVariable TAIL [vpm himmelidemo]$ head -n 10 edges.txt HEAD TAIL r0 r1 r1 r2 r2 r3 r3 r4 r4 r5 r5 r6 r6 r7 r7 r8 r8 s0You can also use full paths for GraphName and
EdgeFile (e.g. '/home/johndoe/results/demoGraph' and
'/home/johndoe/himmelidemo/edges.txt'), which is useful if you want to store
the results in another directory. Note, however, that Himmeli does not create
new directories, so only existing paths can be used.
The connection between the configuration and edge files is made through the
column headings: here the column
[vpm himmelidemo]$ himmeli config.txt
3.x.x Jul 4 2008 Graph
1.0.0 Jul 4 2008 Component
2.0.0 Jul 4 2008 Artist
1.3.2 Jul 3 2008 Table
Himmeli, copyright (C) 2006 Ville-Petteri Makinen
Himmeli comes with ABSOLUTELY NO WARRANTY.
This is free software, and you are welcome to redistribute
under certain conditions; see the license file for details.
Basic configuration:
ArrowMode off
DecorationMode off
DistanceUnit 1.00
EdgeWeightFilter off
EdgeWeightMask off
EdgeWeightTransform auto
FigureLimit 10
IncrementMode off
LabelMode vertex
TimeLimit 10s
ChassisMode off
Loading tabulator delimited data:
Copied 997 bytes from 'edges.txt'.
Detecting variables:
EdgeColorVariable empty
EdgeHeadVariable 'edges.txt' 'HEAD' [ 1]
EdgeLabelVariable empty
EdgeTailVariable 'edges.txt' 'TAIL' [ 2]
EdgeWeightVariable empty
EdgeWidthVariable empty
VertexColorVariable empty
VertexLabelVariable empty
VertexNameVariable empty
VertexPatternVariable empty
VertexShapeVariable empty
VertexSizeVariable empty
VertexXVariable empty
VertexYVariable empty
Importing graph:
[1] 19 22
[2] 6 9
[3] 5 10
Computing layout:
[1] 655 iterations in 1s
[2] 556 iterations in 0s
[3] 569 iterations in 0s
Layout computed in 1s.
Saving figures:
Wrote 8.44K bytes to 'demoGraph_0001.svg'.
Wrote 3.33K bytes to 'demoGraph_0002.svg'.
Wrote 3.31K bytes to 'demoGraph_0003.svg'.
Saving graph:
Wrote 985 bytes to 'demoGraph.config.txt'.
Wrote 1.16K bytes to 'demoGraph.edges.txt'.
Wrote 2.01K bytes to 'demoGraph.vertices.txt'.
The screen output begins with version information and copyright statement for
the various software modules within Himmeli. Next, a listing of the basic
parameters is shown (there are also others, see the
index). So far none of them is configured manually, so
the default values are listed, but they will be modified in later
sections of this document.
After data imports, the detected variables are listed on the screen. There were only two data columns, hence only two are detected. The last entry in the listing indicates the number of the column: the head vertex data were correctly detected in the first column.
Himmeli makes no assumptions about the topology of the graph. Before visualization, though, the graph must be broken into connected components for technical reasons. Here we have three components and the largest comprise 19 vertices and 22 edges. Next the vertex layout is calculated for each component separately. This is the computationally most demanding phase and can take a long time for large graphs. Finally, the drawings are saved in Scalable Vector Graphics (SVG) format, and the layouts are stored in plain text tables. The text files will be covered later in the section on repeatable layouts. The drawing for the largest component is shown in Figure 1. Weighted edgesDrawing the binary links between vertices is the first step. In more realistic situations, it is often possible to quantify the strength or importance of an edge, with respect to the other edges. Previously, the weight of an edge was automatically set to a constant value due to the technical fact that Himmeli was primarily designed for weighted edge sets.
To import quantitative weight data into Himmeli, add an
[vpm himmelidemo]$ cat config.txt GraphName demoGraph EdgeFile edges.txt EdgeHeadVariable HEAD EdgeTailVariable TAIL EdgeWeightVariable WEIGHT # New! DecorationMode on # New! [vpm himmelidemo]$ head -n 10 edges.txt HEAD TAIL WEIGHT r0 r1 1.1 r1 r2 0.6 r2 r3 1.0 r3 r4 1.4 r4 r5 1.3 r5 r6 2.7 r6 r7 1.5 r7 r8 1.3 r8 s0 1.7The weights can be any positive real numbers. Note that values close to or less than zeros will cause a rejection of the edge in question, and missing values or non-numerical entries are interpreted as zeros. The weight value range can be anything; Himmeli will normalize the weights automatically. If necessary, the normalization feature can be controlled manually, see the section on pruning and hiding edges for details.
The edge weights affect the layout by pulling those vertices closer that have
a strong link between them. To make the weights more apparent, the color and
width of each line can be set to reflect the edge strength. By setting
The automatic decorations also extend to the vertices: those vertices that have many adjacent edges (high degree) are drawn with bigger symbols, and the color is determined by the sum of the weights of the adjacent edges. The results are depicted in Figure 2. Directed and labeled edgesSo far the direction of an edge had no significance on the way it was depicted. However, many real world networks contain information on directed associations. A gene transcription and expression network is one example: a transcription factor triggers gene expression, which in turn triggers new genes and so on. As mentioned earlier, the directionality is encoded in the head and tail vertex lists. A transcription factor for a gene would thus be encoded as the tail, and the target gene as the head, within a vertex pair.
The direction does not affect the vertex layout (except the distance unit)
but it changes the way edges are drawn. To show arrows instead of lines,
Color and width are effective means to convey the edge weight information,
but sometimes it is useful to have labels on the edges for extra guidance.
Labeling in Himmeli is controlled via
Suppose the graph was a results of several different methodologies. It is then useful to denote which method was used to uncover a particular connection between the vertices. Also, you can add other extra information that might be relevant when intepreting the figure. To add user-defined labels for edges, a new column must be added to the edge file: [vpm himmelidemo]$ cat config.txt GraphName demoGraph EdgeFile edges.txt EdgeHeadVariable HEAD EdgeTailVariable TAIL EdgeWeightVariable WEIGHT EdgeLabelVariable LABEL # New! ArrowMode on # New! LabelMode on # New! DecorationMode on [vpm himmelidemo]$ head -n 10 edges.txt HEAD TAIL WEIGHT LABEL r0 r1 1.1 methodA r1 r2 0.6 methodB r2 r3 1.0 r3 r4 1.4 methodC r4 r5 1.3 methodA r5 r6 2.7 r6 r7 1.5 methodA r7 r8 1.3 error? r8 s0 1.7 methodBAdding arrowheads and labels to the graph requires more space to prevent undesired overlap of element. Therefore Himmeli adjusts DistanceUnit automatically to meet the needs. Of course, you can
override this in the configuration file, if necessary. The directed drawing
is shown in Figure 3.
Manual colorsWhile it is convenient to have all the colors and other visual attributes automatically selected, in some cases you may need to set the colors based on other criteria than just edge weights. Himmeli makes this possible via two dedicated instructionsEdgeColorVariable and
EdgeWidthVariable.
The human eye has three types of color-sensitive receptors, for red, green and blue. Consequently, colors are usually represented as a combination of the three main components according to the suitably named RGB scheme. In most web pages the color codes are hexadecimal numbers (such as A0F542) that indicate the red intensity in the first two digits, green in the next two and blue in the last two digits. Himmeli follows the same convention, except that the numbers are decimal to make the codes easier to use. Some examples are illustrated in Figure 4.
Suppose the sample graph represents a metabolite network, where the vertices are metabolites and the edges describe their effects on the concentrations during a continuous process. To get the most out of the visualizations, the type of effect can be coded into the line colors so that a simultaneous increase of two metabolites is painted red, whereas a negatively correlated pair is painted blue. Some changes are needed in the configuration and edge files: [vpm himmelidemo]$ cat config.txt GraphName demoGraph EdgeFile edges.txt EdgeHeadVariable HEAD EdgeTailVariable TAIL EdgeWeightVariable WEIGHT EdgeLabelVariable LABEL EdgeColorVariable COLOR # New! ArrowMode on LabelMode on DecorationMode on [vpm himmelidemo]$ head -n 10 edges.txt HEAD TAIL WEIGHT LABEL COLOR r0 r1 1.1 methodA 991000 r1 r2 0.6 methodB 002099 r2 r3 1.0 991000 r3 r4 1.4 methodC 991000 r4 r5 1.3 methodA 002099 r5 r6 2.7 991000 r6 r7 1.5 methodA 002099 r7 r8 1.3 error? 991000 r8 s0 1.7 methodB 991000If some of the color data is missing or invalid, the corresponding edges will be painted with a default color. If you wish to hide a specific edge, set the width to non-positive via EdgeWidthVariable (see also the section
on pruning and hiding). The results for the manually
colored graph are shown in Figure 5.
Vertex shapes and fill patternsIn the previous section the edges were colored according to their function in a hypothetical metabolite network. The same customization is also possible for the vertices, although a new vertex file must be created to pass the extra information to Himmeli:[vpm himmelidemo]$ cat config.txt GraphName demoGraph EdgeFile edges.txt VertexFile vertices.txt # New! EdgeHeadVariable HEAD EdgeTailVariable TAIL EdgeWeightVariable WEIGHT EdgeLabelVariable LABEL EdgeColorVariable COLOR VertexNameVariable NAME # New! VertexColorVariable COLOR # New! VertexShapeVariable SHAPE # New! VertexPatternVariable PATTERN # New! ArrowMode on LabelMode on DecorationMode on [vpm himmelidemo]$ head -n 10 vertices.txt NAME COLOR SHAPE PATTERN r0 909090 circle r1 994030 triangle r2 307099 triangle stripe r3 994030 triangle r4 994030 triangle stripe/45 r5 307099 triangle r6 994030 triangle spot r7 307099 triangle r8 994030 triangleThose vertices that have only positive (red) arrows to other vertices are colored red (R=99, G=40, B=30), those with only negative arrows pointing to other vertices are colored blue (R=30, G=70, B=99), those with both are painted magenta (R=90, G=10, B=90), and finally the one vertex with no outward connections is painted light-grey.
Note the new instructions in the configuration file:
In addition to color, the configuration file contains instructions that
control vertex shapes ( The fill patterns behave the same way as the shapes. For example, to create diagonal stripes, you start with the default horizontal stripes and then rotate by 45 degrees to produce the code string 'stripe/45'. Additional examples of vertex colors, shapes and patterns are shown in Figures 4 and 6. Pruning and hiding edgesFor complex networks (in the topology sense) two-dimensional layout is always non-optimal and often somewhat difficult to grasp. One way to make the visualization clearer is to reduce the number of elements depicted in the figure according to pre-defined criteria. As a first step, a maximum spanning tree can provide insight into the topology, even if it discards most of the edges. Himmeli does the tree layout automatically ifChassisMode
is activated. In fact, you can set the connectivity via an additional
parameter, see the index entry on ChassisMode at the end of
the document.
Another way to reduce the number of edges is to remove those with small
(or large) weights. Himmeli has a built-in filter feature
( The results are depicted in Figure 7. The largest connected component is now smaller (18 vertices and 19 edges) since some of the vertices became unconnected due to the removal of the affected edges.
Often the preferred approach is to include all the edges when computing the
layout, but leave out some from the final figure. This can be accomplished
with Repeatable layoutsIf you have already tried Himmeli repeatedly, you may have noticed that the vertex layouts differ between each run of the program. This is due to the adaptive nature of the layout algorithm: it adjusts the internal parameters continuously according to the available calendar time (set byTimeLimit) and since the operating system allocates an
unpredictable amount of processing resources for Himmeli, the resulting
layouts are, in general, indeterministic.
To overcome this unwanted "feature", Himmeli offers additional text files that
simplify the reproduction of previously calculated layouts. The three files
(new configuration, edge and vertex files) contain all the information about
the graph, so you can store them instead of the figure files as a backup
of the layout. Specifically, the layout coordinates are stored in the columns
indicated by
The new configuration file contains the instructions from the oiginal file,
but also additional commands that override some of the original settings.
Also, the new edge and vertex files are accessed instead of the original
data files. To reconstruct the figures, simply use the command
Information elementsIf the edges and vertices are visualized according to a pre-defined scheme, it is concenient to have the symbol information available in the figure. In earlier versions of Himmeli the software put the user-supplied items automatically in the figure files. After the migration to SVG, the users themselves can do this much better with Inkscape, hence the automatic positioning is no longer supported.
The extra meta-data can be supplied to Himmeli via the
info instructions (such as EdgeColorInfo activation 991000 EdgeColorInfo inhibition 002099 VertexColorInfo activator 994030 VertexColorInfo inhibitor 307099 VertexColorInfo omnipotent 901090 VertexColorInfo impotent 909090 VertexShapeInfo pathwayA circle VertexShapeInfo pathwayB triangle VertexShapeInfo pathwayC star VertexShapeInfo pathwayD cross VertexShapeInfo pathwayE square VertexPatternInfo energy stripe VertexPatternInfo adhesion cheque VertexPatternInfo defense spot VertexPatternInfo unknown null Index
|
LinksBasic graphWeighted edges Directed and labeled edges Manual colors Vertex shapes and fill patterns Pruning and hiding edges Repeatable layouts Information elements Index
File formatsPNG (Portable Network Graphics)A bitmapped image format with lossless data compression. Use this format for web publishing or other electronic media. For high-quality printed or digital documents, the vector graphics formats SVG, PS or PDF are preferred.
SVG (Scalable Vector Graphics)
TSV, TXT (Tab delimited text) | ||||||||||||||||
| Updated 2009-10-13 by webmaster. | ||||||||||||||||||
