
ONLINE VERSION

For small tables, consider using the online version of the tableviewer. 
It does not support all settings of the command-line version, but should
be sufficient to get you started.

  http://mkweb.bcgsc.ca/tableviewer

Details about how the tableviewer works can be found in these two articles.

  http://www.circos.ca/presentations/articles/vis_tables1
  http://www.circos.ca/presentations/articles/vis_tables2


COMMAND-LINE VERSION

Circos' tableviewer is a set of 3 independent scripts which 

  make-table  : create a random table (skip this step if you want to use your own data)
  parse-table : parse the table
  make-conf   : create Circos configuration and data files from parsed tables

The make-table script (first step) is useful for creating random data
for testing. If you have your own data, you can skip to the second
step (parsing a table).

* parse-table

This script reads a tabular data file, such as the kind exported by Excel, and
generates an intermediate file which contains information used to generate
configuration and data files that Circos understands.

The parsing step is independent to keep the process modular. 


* make-conf

The output of parse-table cannot be used directly by Circos. Instead, make-conf
reads the output and produces input data and configuration file in the format
that is useable by Circos.


EXAMPLES

There is a variety of sample input tables in samples/. These files are
used in the article at

  http://www.circos.ca/presentations/articles/vis_tables2

You'll notice that there are both .txt and .conf files in samples/. The
.txt files are the table data and the .conf files are used to control
how parse-table interprets and parses the input. 

Follow the examples using makeimage (this is a UNIX batch file -
Windows users will need a UNIX environment like Cygwin to run it). To
create the first two examples:

> ./makeimage 01
...
created image at img/table-01.png
created image at img/table-01.svg

> ./makeimage 02a
...
created image at img/table-02a.png
created image at img/table-02a.svg

There are many .conf files for parse-table in samples/. For a given configuration
parse-table-X.conf there is a table file table-X.txt (which may be a symlink). To 
create the image for the example,

# X = 01, 02a, 02b, 02c, ...
> ./makeimage X

If you look at the contents of the makeimage batch file, you can see what is happening:

- parse-table parses the table-X.txt file 
- parsed output is passed to make-conf
- configuration and data files are created in data/
- Circos is executed using the template configuration etc/circos.conf, which imports content from data/

A simple 3x3 table is used for example 1 (samples/table-01.txt) and a larger 5x5 table is used
for examples 2-5 (samples/table-02.txt). To illustrate how the ratio layout works (where
each ribbon represents two cells: x,y and y,x), example 6 uses samples/table-06.txt, 
which is a 5x5 table with rows/cols sharing the same names.  


RANDOM TABLES

To generate an image of a random 10 x 15 table

> bin/make-table -rows 10 -cols 15 -unique -brief

The output of make-table can be used directly by parse-table:

> bin/make-table -rows 10 -cols 15 -unique -brief | bin/parse-table | bin/make-conf -dir data
> ../../bin/circos -conf etc/circos.conf


USING YOUR OWN DATA

To generate an image of your data

cat yourdata.txt | bin/parse-table | bin/make-conf -dir data
../../bin/circos -conf etc/circos.conf

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

NOTE: The etc/circos.conf file remains the same and loads data files from data/. These data files are generated by make-conf.
