ClusterViz

Documentation

Installation

Installation follows the standard Python package management principles: After extracting the files from the package, enter the newly created directory and just run

 python setup.py install
            

to build and install the package. Note that you might have to perform this with a user with sufficient rights. This could mean that you have to be root if installing under UNIX.

This will install ClusterViz as a package under your Python site-packages directory. It will also install the front-end script clusterviz into a location such that you should be able to execute it.

Dependencies

ClusterViz does depend on two other Python modules to function. These are the following:

• Numeric for array operations. Development of this module has actually already ceased and we will replace it by its successor in the near future. Information is available here and it can be downloaded from here.
• PyOpenGL. This is the interface to do OpenGL programming from Python. Without this obviously no visualization is possible. Get it from here.
• RPy. This is optional. ClusterViz can make use of an existing installation of the statistics software R to make plots. Then you also will need RPy.

Running the program

The program is called

 clusterviz
            

Just run this Python script with the data file to work on as argument:

 clusterviz FILE
            

To get information about how to use it you can issue:

 clusterviz -h
            

To use another algorithm than the default and fast hard k-means algorithm use one of these commands (which are documented in the above help output).
Soft k-means with beta = 30:

 clusterviz -s 30 FILE
            

Mixture models:

 clusterviz -m FILE
            

Data file format

The data are presented to ClusterViz in a flat-file format. Per line one data sample is expected whose components are white-space separated. Earlier versions of ClusterViz supported only three-dimensional data. This restriction has now been lifted. X-dimensional data can be projected down to three dimensions by just using the first three dimensions and disregarding the rest for displaying. Other possibilities are to determine via a command line option which dimensions to use in this way or to give a linear transformation matrix that is applied for the display (see the --help option for the syntax). Note that the clustering process itself works on the non-transformed data and only the display is result of the projection.
Example data sets to try ClusterViz out can be downloaded from the project's Sourceforge file area.

GUI controls

There are a number of commands available in the GUI. To see them just hit 'h' while the GUI is running.

Keyboard commands

Mouse control