VennMaster Software Documentation

A tool for drawing area proportional Euler diagrams.

Bioinformatics publication (2005)
BMC Bioinformatics publication (2008)

0. Introduction

VennMaster is a tool for drawing area proportional Venn/Euler-diagrams by importing gene lists from GoMiner.

1. Installation

The software requires the Java runtime environment 1.5.0 (JRE 5.0) which can be downloaded from java.sun.com.
  1. Install JRE 5.0 (1.5.0) if it is not available on your system.
  2. Download the current VennMaster version and unpack the file into a directory.
  3. Start VennMaster by Hint: It is not recommended to call VennMaster by a direct click on the venn.jar file since the standard memory assignment is too low for the most Euler arrangements.
VennMaster is packed into a single zip archive which must be unzipped (e.g. using WinZip) into the desired directory (e.g. "C:\Program Files\" or your home directory). Call venn.sh in the VennMaster directory from the command line (Linux or Mac OS X) or double click venn.bat under Microsoft Windows in the file explorer.
When using many categories VennMaster may report an out of memory error. In these cases reduce the number of categories by specifying other import filter settings or open venn.sh (Linux or Mac OS X) or venn.bat (Windows) with a text editor (e.g. vi or notepad) and change the memory size by editing the two -X options of the java call. The -X options specify the memory size (in MB) assigned to the software. These can be adapted depending on the available memory and the problem size (number of categories/elements). The standard settings are usually too small for the most problems (2MB for Sun Java 1.5 on linux and 1MB on win).

Download

VennMaster-0.37.5.zip (Version 0.37.5)

Version history

VennMaster-0.37.4.zip (Version 0.37.4)
VennMaster-0.37.3.zip (Version 0.37.3)
VennMaster-src-0.37.3-20080219.zip (Source code version 0.37.3)
VennMaster-0.37.2.zip (Version 0.37.2)
VennMaster-src-0.37.2-20080110.zip (Source code version 0.37.2)
VennMaster-0.37.0.zip (Version 0.37.0)
VennMaster-src-0.37.0-20071119.zip (Sour ce code version 0.37.0)
VennMaster-0.36.0.zip (Version 0.36.0)
VennMaster-src-0.36.0-20070907.zip (Source code version 0.36.0)
VennMaster-0.35.0.zip (Version 0.35.0)
VennMaster-src-0.35.0-20070806.zip (Source code version 0.35.0)

License

VennMaster and the VennMaster source code are licensed under a
Creative Commons License
This work is licensed under a Creative Commons Attribution-Noncommercial 3.0 License.

2. Running VennMaster

The following steps lead to an Euler diagram:
  1. Import a data set
  2. Filter the data (only for data formats B and C)
  3. Explore the Euler diagram

1. File Formats

VennMaster can import three different file formats.

A. List File Format

This is a very simple tab delimited file format with an element/group pair in each line which can easily be generated by e.g. Microsoft Excel or OpenOffice.

Toy example:
cat mammal
dog mammal
rose plant
rose spiny
dog animal
lobster animal
lobster spiny
:
:
This example can be downloaded: example1.list.

B. GoMiner Export File Format

VennMaster can import the pair of GoMiner summary export and gene-category export files. A brief summary of using GoMiner to generate these files is given in the Appendix below. An example file pair can be downloaded: go1.se go1.gce.

C. High-Throughput GoMiner Export File Format

VennMaster can import the single .gce-file which can be exported by the new high-throughput GoMiner.

2. Importing the Input Files

A. List File

Choose the menu point Open List in the File menu and navigate to a file in the format described in section 1a.

B. GoMiner Export File

  1. Choose Open GoMiner file from the VennMaster File menu.
  2. In the first appearing file open dialog select the summary export (.se) file and press OK.
  3. In the subsequent file open dialog select the gene-category export (.gce) file.
  4. Continue with filtering.

C. High-Throughput GoMiner Export File

The export file format of the high-throughput GoMiner is now a single .gce file with a new column containing the false discovery rate (FDR).

3. Filtering

The number of categories can be reduced with the interactive filtering panel.
VennMaster filtering panel
The five parameters have to be adjusted until the number of filtered categories (field #filtered categories) is satisfying. The number of filtered categories and elements are immediately adjusted when changing the filter values. Click on the Update button to start the simulation with the current filter settings. The Reset button sets the filter settings back to the currently shown diagram. Normally the filter dialog should react immediately when changing the filter parameters. If not press on the Filter button.

4. Interactive Exploration

VennMaster allows the interactive exploration of the sets. When moving the mouse slowly over the polygon arrangement, the region under the mouse will be highlighted and the corresponding sets are shown in a small tool tip window. When a region is selected with the left mouse button the details of the selection are listed in the "Categories" tab of the information pane on the bottom. Right click on categories offers a menu for setting category labels and colors.

The upper panel shows the categories (for GoMiner files additional information is shown such as the TermID, nChanged, nTotal, pValue, and FDR). A double-click on a GO TermID opens a web browser with a direct link to www.geneontology.org. The lower pane shows a global information of the currently selected (intersection) set such as the number of involved groups and the number of elements in the intersection. Then all elements in the (intersection) set are listed in the lines below. With a double-click on a gene name a web browser is opened with a link to www.genecards.org. If a single polygon is selected it can be moved by drag and drop. When pressing the control button while selecting polygons, multiple regions can be selected and their corresponding elements are shown in the "Selection" region.

Set intersections for which no corresponding geometric intersection exists are listed in the "Inconsistencies" field of the information panel. Each entry consists of a list of categories { C1, C2 ..., Cn } : u with an integer u > 0 describing the number of elements in the shown intersection set.

Key Commands

VennMaster enables to copy and paste the contents of the category table and the gene list with the following key commands:
  1. Select one or more cells of the category table or gene list with the mouse.
  2. Press ctrl+A to select the whole table.
  3. Press ctrl+C to copy the data into the clipboard.
  4. Go to the target application (e.g. Excel or a word processing program) and paste the data.
 

Appendix

1. Generating GoMiner summary export (.se) and gene-category export files (.gce)

After processing the data with GoMiner (http://discover.nci.nih.gov/gominer) the summary export (.se) and category-genes export files (.gce) have to be exported via the middle panel of the GoMiner graphical user interface (GUI). The desired root category node needs to be selected by a single left click, and the context menu activated by a single right click. The two menu items should be selected this way to save the .se and .gce files to disk.

2. The Parameter Dialog

Optimization and visualization parameters can be configured via the parameter dialog (menu Options/Options).

A. Visualization/Global Options


size factor
(default 1.0)
Can be adapted to grow/shrink the polygons to fit better in the bounding box which may occur if the intersections between sets is very small (so the diagram is too wide for the bounding box - reduce e.g. to 0.7 in those cases).
number of edges
(default 16)
How many edges should the polygons have (>=3)
Seed
(default 173)
The random seed value ensures reproducible results (for one software version). Other solutions are found if this value is changed. For negative values the current system time is used as random seed.
Update interval
(default 10)
The number of optimization steps after which the currently best solution is shown while the optimization is running.
Max categories
(default 10)
Exceeding the maximum number of categories shows a warning message. Raise this value to suppress warnings. Higher number of categories may need more computational power.
Log2 #elements Activate this checkbox to transform the number of elements to logarithmic scale. For consistency we set log(0)→log(1)→log(2)→1.
Color mode on Toggle color mode on/off.

B. Error Function

Error Function Options
error function type
(default 1)
0=old error function, 1=new error function
max intersections
(default 6)
The maximum number of sets which will observed when evaluating the error function
alpha
(default 10.0)
Error function weight for unwanted intersection
beta
(default 20.0)
Error function weight for missing intersections
gamma
(default 5.0)
 
delta
(default 400.0)
Pressure term for more compact solutions
min scale
(default 1.0)
Allow changes of the polygon radii (experimental).
max scale
(default 1.0)
Allow changes of the polygon radii (experimental).

C. Optimization Options

Different optimizers can be chosen in the Optimizer panel (The Evolutionary new is experimental).
i) Evolutionary Optimization
Evolutionary Optimization Options
The mutation parameters (like min mutation and max mutation) behave relative to the bounding box where the individuals "live". So a mutation rate of 0.2 can move an polygon 1/5-th of the total bounding box.

tau
(default 1.0)
Mutation basis parameter (mutation of the mutation parameter)
min mutation
(default 0.01)
Lower bound for the mutation rate
max mutation
(default 0.2)
Upper bound for the mutation rate
generation size
(default 30)
How many individuals are in the generation (25-100 individuals are reasonable).
clone fraction
(default 0.2)
The best individual has N=clone fraction * generation size outcomes. The individual with rank r has at most min(1,N/r) outcomes.
max opt steps
(default 200)
Maximum number of optimization steps. Increase this value for better solutions.
max const steps
(default 25)
Stopping condition for the evolutionary algorithm. If there is no cost improvement in the best individual within max const steps epochs the optimization will be stopped. Increase this value for better solutions.
ii) Particle Swarm Optimization
Particle Swarm Optimization Options

numParticles
(default 30)
How many particles are in the swarm (25-100 individuals are reasonable). Each particle represents a solution to the problem.
cGlobal
(default 0.5)
The velocity of each individual is influenced by the global optimum (that is: the best individual to its best iteration up to now).
cLocal
(default 0.5)
The velocity of each individual is influenced by the local optimum (that is: the optimum of the respective individual up to now).
maxIterations
(default 200)
Maximum number of optimization steps. Increase this value for better solutions.
maxConstIterations
(default 25)
Stopping condition for the evolutionary algorithm. If there is no cost improvement in the globally best particle within maxConstIterations epochs the optimization will be stopped. Increase this value for better solutions.
reflect
(default true)
If reflect is checked the particles are reflected at the bounding box (the domain of the optimization problem) resulting in an inverted velocity vector in the corresponding coordinates.

3. Command line options

The functionality of VennMaster can be automated from the command line to enable batch processing of multiple files. Type the following call in your VennMaster installation directory:
java -Xms256m -Xmx256m -jar venn.jar arguments ...
The two -X options are necessary to adapt the memory assignment to VennMaster. For larger problems it may be necessary to increase those values (e.g. to 512).
-help,-?
displays help information
--version, -v
displays the version number of VennMaster
--cfg file.xml
configuration file
--ocfg file.xml
configuration file output
--list file.list
list file input
--gce input.gce
GoMiner gene-category export file
--se input.se
GoMiner summary export file
--htgce ht-input.gce
High-Throughput GoMiner gce file
--filter file.xml
filter file (for GoMiner)
--ofilter file.xml
filter file output
--svg file.svg
SVG file output
--sim file.txt
simulation errors output
--prof file.txt
error profile output for the last simulation

The original version of this page is available at http://www.informatik.uni-ulm.de/ni/staff/HKestler/vennm/doc.html.


Contact/Imprint
André Müller, Hans A. Kestler
last modified: 2010-05-12