Help Page


Welcome to clicO FS (Circular Interactive Layout Converter Free Services) ! This is a free service in the form of web interface for Circos tool, a powerful visualizer that generate circular layout. If you have any doubt or problem, kindly look in this page for answers.



Table of Contents





1. Introduction


1.1 What is Circos?

Circos is a powerful data visualization tool in the form of circular layout by Krzywinski, M. et. al. It is an ideal tool for visualization of genomic data, although other data can also be used.

Circos has been continuously proven to be useful in scientific field, and had been cited by more than 100 scientific articles.

Besides being able to visualize data, Circos also perform it in an attractive way. Take a look at the collection of images generated by Circos. Impressive?

Collection images


1.2 How Circos Works?

The execution of Circos program and its output is based on a single configuration file. Basically, the configuration file specifies and configures the following :

  1. Karyotype file - The location of at least 1 karyotype file must be specified in configuration file. It acts as The 'backbone' of Circos image, usually defines the chromosomes and its length / location, in the form of ideogram in output. Optionally, location of bands could also be defined.
    These examples show the human and rat karyotype files (taken from Circos tutorial).

  2. Data Track file - The specification of data track file is optional in configuration file. It 'gives meaning' to the backbone ideogram. Usually, data track file contains the data on association / characteristics of different data points. Can be in various format, such as links, tiles, histogram, scatterplot, highlight, connector, and text. (Examples)

  3. Various other configurations - Define how karyotype and data track would be presented in the Circos output, to the way intended by user. There are many types of parameters that can be configured, such as ideogram settings, ticks settings, label settings etc., thereby allowing user to generate the output in almost any way possibly.

To gain insight on the structure of configuration file, take a look at this example. As stated in Circos website, it is the minimum practical configuration required to generate an output with only ideograms. Most of the parameters are enclosed in opening and closing tags (eg: <ideogram> and </ideogram>), and <<include * >> is used to include other file.


After the configuration file is ready and valid, Circos is run on command-line by as easy as a single command as shown in red box below.


Circos command


1.3 What is clicO FS?

Despite its powerfulness and attractiveness, Circos curently lacks of an well-established user interface. Therefore, it would be difficult for new user / researcher to start using it, especially for researchers that are not familiar with command-line. This website is built just for that reason.

When using this Web UI, all operations / configurations are performed in the back-end. User doesn't have to deal with any command-line or configuration files. It is made to be as simple as possible, yet powerful enough to generate most type of images.



1.4 How clicO FS Works?

Bootstrap Rails

Basically, clicO FS is built using Twitter Bootstrap v3 as the front-end framework, and Ruby on Rails 4.0.0 as the back-end framework, along with various other web technologies.

Since clicO FS is completely web-based, user could utilize and perform any operations by just visiting this website.



2. Tutorials (Blank Template)


2.1 Getting Started

Generally, clicO is designed to be as user-friendly as possible, and user should be able to get familiar with it within a fairly short time. This section would explain about how to use and utilize clicO, along with few examples data set. After going through this tutorial, you should be able to get an overview about how clicO works, and you can proceed by creating new project with your own data.


* If you just want to quickly go through this Tutorial, follow the Instructions in grey boxes.


Let's get started !


Firstly :

Download both ZIP files of DEMO Karyotypes and DEMO Data Tracks

and unzip it into any directory you like. This sample data contains the karyotypes and data tracks files that are needed for this tutorial.


Then, open the web application by :

Enter http://clicofs.codoncloud.com to your preferred browser

You should be able to see the Home page.

Home unsigned

Welcome to clicO !

To quickly navigate to various components of ClicO FS,

Click on "Get Started!" button from the navigation bar

where you would arrive to a page with selections.

Get started

(Optional) If you choose to register, your created project and plotting would be saved and you could continue to work on it the next time you log in. clicO distinguishes all the data and information for each user, so that your data could be kept private, and user could manage multiple projects at the same time. Your email address would be used as your ID the next time you sign in, and the user confirmation link would be sent there. Therefore, make sure you provide a valid email address.



2.2 Karyotype (Human and Mouse)

For this project, you will be creating comparative genomics of Chromosome 1 and 2 of Mouse and Human, along with simulated data.

Firstly, from "Get Started" page, selects the "Blank Template" mode

Select "Blank Template" mode from the dropdown and click 'Go'

Provide a meaningful name to the project

Provide a name for your project "Comparative Genomics", enter the Captcha, and click 'Start'

Alternatively, if you have logged in, click on "Create Project" to create new project. You can continue on your work the next time you log in.

Now you should be in 'Select Karyotype' page. Karyotype forms the backbone of the plotted circular graph, therefore you must upload and select at least one karyotype before you proceed. As with most other pages, you could press on the '?' sign beside the header to show detailed instructions. Since you have not upload any karyotype to be selected yet, upload now :

Click 'upload new' button

You'll now in 'New Karyotypes' page. You could click the 'format description' button to view the format of karyotype file required. Basically, only CSV or TXT file with 7 columns (same as Circos) are accepted, and incorrect format will be rejected.

To configure and upload Human Karyotype file :

1. Click 'Upload New' button
2. Enter 'Human' for the Description field
3. Click 'Choose file' and select 'all_karyo_demo/karyotype.human.txt' from the extracted folders you have downloaded.
4. Specified color for the karyotype "#2945e3"
5. Click 'Upload' button

After uploading, you'll see a table with uploaded karyotype's information in 'Select Karyotype' page. You can now upload any new karyotype.

Similarly, upload another required file, the Mouse Karyotype :

1. Click 'Upload New' button
2. Enter 'Mouse' for the Description field
3. Click 'Choose file' and select 'all_karyo_demo/karyotype.mouse.txt' from the extracted folders you have downloaded.
4. Specified color for the karyotype "#a62a55"
5. Click 'Upload' button

You can check or uncheck the checkboxes to select the karyotypes to be included in output. The selections would be saved in database, and therefore would be selected by default the next time you open this project.

To proceed, :

Select both human and mouse karyotypes and click 'next' button

You'll be in the first Settings page, 'Karyotype Settings'. Starting from this stage, you can actually press the flow menu at the top to freely navigate to any steps.

On the left section, the selected karyotypes would be shown in tabs, with their descriptions as title. After you have finished configuring, you could click 'Save' button to update the settings in database and file level, or click 'Preview' button to preview the output (without saving). If you've logged in, the saved settings would be kept the next time you open this project.

The preview frame is positioned at the right-hand section. You could choose to preview the output based on your configuration at any time, and this frame would present in most of the following pages. The currently seleted karyotypes and data tracks (if any) would be shown as well.

Feel free to configure around the various Settings. Make any changes and preview the output in page. After you're done, click 'next' button to next page. You could continue to configure and preview any other settings about karyotype.


If you would like to get similar output as of this tutorial, please follow example parameters/settings as written below for each input fields on the Settings pages.

Chromosomes Settings
1. Deselect (untick) all chromosomes EXCEPT hs1 and hs2 (from Human), and mm1 and mm2 (from Mouse) to show only these 4 chromosomes.
2. Select (tick) to reverse mm1 and mm2
Chromosomes Ordering
1. Drag and drop to arrange the chromosomes in the order of: hs1 hs2 mm2 mm1

2.3 Data Tracks

After you're done configuring various settings about karyotype, it's time to add in the sample data tracks :

Click 'Data Tracks' in the flow menu to reach 'Select Data Tracks' page.

Nine (9) data tracks will be uploaded, including links, tiles, histogram, line, heatmap, scatterpot, highlight, connector, and text.

Firstly, upload the data tracks of type "links" :

1. Click 'Upload New' button
2. In 'File Type', select 'Links'
3. Input 'Links' as description
4. Click "Choose file" and select 'all_tracks_demo/links.txt' from the extracted folders you have downloaded.
5. Click "Upload" button to upload

Similarly for 8 other data tracks :

Repeat steps above to upload the other 8 data tracks. Make sure the "File Type" is correct or else it would cause errors.

After that, you’ll have to select the data tracks hat you intend to show in output :

Select all 9 data tracks that you have uploaded, then Click 'Next' button

You'll now in settings page for data tracks. You could configure the settings for each data track's such as line thickness, color etc. Feel free to configure and preview the various Settings.


If you would like to get similar output as of this tutorial, please follow all parameters/settings as written below for each data tracks on the Settings page.

Links
1. 'Radius' to 0.50`r
2. 'Color' to #a8a8a8
3. 'Ribbon' to Yes
Histogram
1. 'Inner Radius' to 0.80r
2. 'Fill color' to #62c25b
3. 'Custom Rules' to
color = white
stroke_color = white
thickness = 5

<rules>
<rule>
use = yes
condition = var(value) > 0.5
show = yes
fill_color = vdgreen
</rule>
</rules>

<backgrounds>
<background>
color = vlgreen_a4
</background>
</backgrounds>

<axes>
<axis>
spacing = 0.2r
color = white
thickness = 3
</axis>
</axes>
Line
1. 'Inner radius' to 0.73r
2. 'Outer radius' to 0.78r
3. 'Thickness' to 2
4. 'Color' to #079fad
5. 'Background color' to #c9f5f4
Heatmap
1. 'Inner radius' to 0.67r
2. 'Outer radius' to 0.70r
Scatterplot
1. 'Inner radius' to 0.60r
2. 'Outer radius' to 0.65r
3. 'Glyph color' to #b8a227
4. 'Background color' to #f2e4bf
5. 'Custom Rules' to
<axes>
<axis>
spacing = 0.2r
color = vlgrey
thickness = 2
</axis>
</axes>
Tiles
1. 'Inner radius' to 0.93r
2. 'Outer radius' to 0.98r
3. 'Layer of tiles' to 1
4. 'Thickness' to 30
5. 'Color' to orange
6. 'Background color' to Light Orange
Text
1. 'Inner radius' to 0.55r
2. 'Outer radius' to 0.60r
3. 'Text size' to 12
Connector
1. 'Inner Radius' to 0.50r
2. 'Outer radius' to 0.55r

After you're done configuring all the settings to your desired output :

Click 'Output' on the flow menu to generate the final output. Or you can freely go back to any stages to change the configurations through the flow menu.

If you have followed through this tutorial, you should now be able to view the output similar to this :

Tutorial output1


3. Tutorials (GenBank Format File)


ClicO FS also provides service in which you could generate Circos visualization from GenBank format file as easy as just a click.

Firstly :

Download the DEMO Genbank file

and unzip it into any directory you like. The file contains sample Genbank format file of Brucella melitensis 16M.

All settings are preconfigured to display the visualization as accurate as possible and save you from the hassles of configurations. As a trade-off, should you need more customizations, you might have to start with "Blank Template" mode.

6 data tracks would be generated automatically in the output. From outer to inner rings :

To go to the page for this mode :

Select "Plot from GenBank file" from "Get Started" page

After that, all you need to do is upload and plot. The sample data provided contains data of chromosome I of Brucella melitensis, retrieved from Genbank. Click on the "GenBank Format" link to get the detailed description of the format.

Upload the sample Genbank Format file from genbank_demo/brucella_melitensis_16M.gb and plot

You should be able to view the output similar to this :

Tutorial output3


Thanks !