Use the latest version of Circos and read Circos best practices—these list recent important changes and identify sources of common problems.

If you are having trouble, post your issue to the Circos Google Group and include all files and detailed error logs. Please do not email me directly unless it is urgent—you are much more likely to receive a timely reply from the group.

Don't know what question to ask? Read Points of View: Visualizing Biological Data by Bang Wong, myself and invited authors from the Points of View series.

11 — Image Maps

1. Image Maps - Introduction and Clickable Ideograms

HTML image maps allow you to associate areas of the image with web links. Any element in the image (ideogram, tick, band, highlight, ribobn, etc) can have an associated URL. When you publish both the image and the image map on a web page, the client's browser uses the image map to create clickable regions within the image.

Many of the example images in this tutorial set have image maps. You can mouse-over these images to see the effect of the map. The links associated with each element are bogus, though, so don't be surprised if they lead nowhere.

using image maps

Using client-side image maps is simple, and you can get more information about image maps elsewhere.

Briefly, let's say you have already created your image, circos.png, and an image map, circos.html (I will shortly how the image map is actually created in Circos). To use the image map, you need to place the contents of the circos.html file within the web page, and then use the USEMAP attribute in the IMG tag to associate the image with the map.

<!-- first the contents of the ciros.html file -->
<map name='circosmap'>
<area shape='poly' coords='769,362,778,361,777,348,767,349' ...
<area shape='poly' coords='730,230,738,225,731,213,723,217' ...
<!-- now the image element -->
<img src="circos.png" usemap="#circosmap">

As you can see, the image map file is composed of a <map> tag, which has an associated name parameter and, inside this block, multiple <area> tags. Each area tag defines a clickable area in the image as a rectangle, circle or polygon.

You can include the HTML map into the page using an server-side include directive (if supported by your web server installation). For dynamic pages, the script that generates the page would be responsible for injecting the image map contents into HTML stream.

preparing to use maps

Parameters that toggle and define image map properties are found in the <image> block of the configuration file. If you set

image_map_use      = yes
image_map_name     = circosmap

you will get an image map written to the same directory as the image file. The image map file will have the same filename as the image file, but with an .html extension.

Don't confuse the map name and filename. The image_map_name defines the name of the map as it appears in the NAME tag in the MAP element (this is the same name that is referenced by USEMAP). The filename is the name of the file to which the map is written. Thus, the name and filename of the map can be different.

Once you've toggled the use of image maps using image_map_use, you still need to define URLs to populate the map. In this tutorial, I will describe how to associate URLs with ideograms.

setting image map parameters on the command line

You can override any parameter in the configuration file using the -param command-line flag. If the parameter is inside a block, specify the block hierarchy and parameter with / as delimiter.

# set value of karyotype parameter in root of configuration
circos -param karyotype=myfile.txt

# set image_map_use parameter in <image> block
circos -param image/image_map_use=yes

# set several parameters in <image> block
circos -param image/image_map_use=yes -param image/image_map_file=myfile.html

making ideograms clickable

Image maps are implemented consistently (at least I've tried to do this) for all image elements (ideograms, ticks, highlights, ribbons, etc). The approach to defining and making dynamic URLs of ideograms will generally apply to all other elements. I will describe how other elements are made clickable in other tutorials in this section.

To associate a URL with an ideogram, use ideogram_url in the <ideogram> block.

ideogram_url =

That's it. Now, every ideogram in the image (as well as ideogram labels) will link to This is demonstrated in the first image of this tutorial.

Note that the https:// prefix in front of the url makes the url absolute. If the https:// were left out, you would get a relative URL.

This is a boring example, because it is unlikely that you would want to link to the same URL from every ideogram. Let's now look at how to make the URL dynamic.

dynamic URLs

The ideogram_url string can contain fields which refer to properties of the ideogram. For example,

ideogram_url =[chr]

will result in each ideogram having a unique link because when the URL is generated for each ideogram, the string [chr] will be replaced by the value of the chr parameter for the ideogram. In general, any string in the url in square brackets will be replaced by the value of the parameter.

URL parameters

For ideograms, you have access to the following parameters.

  • chr - name of the ideogram (e.g. hs1)
  • tag - tag of the ideogram (e.g. a, if you've defined a crop like hs1[a]:0-50)
  • label - label of the ideogram (e.g. 1)
  • idx - index of the ideogram (internal value)
  • display_idx - display index of the ideogram (internal value)
  • start - base position of the start of the ideogram (same as start of chromosome, unless the ideogram is a crop)
  • end - base position of the end of the ideogram (same as end of chromosome, unless the ideogram is a crop)
  • chrlength - length of the corresponding chromosome
  • scale - global scale of the ideogram

Each of these can be used any number of times in the URL as [parameter_name]. For example, if you have a script at /cgi-bin/script which understands the CGI parameter named chromosome, you might use

ideogram_url = /cgi-bin/script?chromosome=[chr]

Each image element (ideogram, tick, highlight, ribbon, etc) will have its own set of parameters, though many will have a shared set (e.g. start, end).

In the third example image of this tutorial, I've created an image map which uses all of the parameters. This is overkill, but you get the idea.

ideogram_url = script?type=ideogram&start=[start]&end=[end]

Notice that this URL is relative (it doesn't start with a /). Also notice that I've added a type=ideogram parameter pair to the URL - you can mix static and dynamic parameters to suit your application.

defining URLs specific to individual ideograms

In the examples above, the ideogram_url string was defined in the configuration file. This definition was applied to each ideogram. Individual URLs could have dynamic elements, with the use of parameters described above, but the URL template was the same for each ideogram.

To define URLs specific to individual ideograms you have two options: including a url parameter in the karyotype file or rules. I will cover rules shortly, but for now let's look how the karyotype file can be used to support URL definitions.

Recall that the karyotype file contains the definitions of each chromosome and any cytogenetic bands.

chr - hs1 1 0 247249719 chr1
chr - hs2 2 0 242951149 chr2
chr - hs3 3 0 199501827 chr3

You can attach a custom URL definition to any chromosome by adding a url parameter

chr - hs1 1 0 247249719 chr1 url=special_script?chr=[chr]
chr - hs2 2 0 242951149 chr2 url=another_special_script?chr=[chr]
chr - hs3 3 0 199501827 chr3

In this case, ideograms for chr1 and chr2 will have URLs distinct from all other ideograms. If you have defined ideogram_url in the configuration file, other chromosomes will have URLs based on this parameter. If ideogram_url is not defined, then only chr1 and chr2 will have URLs.

incorporating custom tags via id parameter

The id parameter, supported by any element, is a useful way to tag your element with any string. This gives you a way to reference an element with an identifier that fits your application (e.g. primary key of a database).

To do so, add the id parameter to the karyotype file

chr - hs1 1 0 247249719 chr1 id=string001,url=special_script?id=[id]&chr=[chr]
chr - hs2 2 0 242951149 chr2 id=string002,url=another_special_script?id=[id]&chr=[chr]
chr - hs3 3 0 199501827 chr3 id=string003

and, for example, define the ideogram_url as

ideogram_url = script?id=[id]

The result will be the same as in the example above, except now the URL incorporates the id parameter value, which we manually defined for each chromosome.

using rules to adjust URLs

It should not surpise you that you can use rules to adjust URL parameters. Just like adjusting color, stroke, position, or value of a data point, you can adjust the URL based on a rule.

URLs of any image elements that support rule blocks (plots, links, highlights) can be manipulated in rules. Ideograms and ticks do not support rules at this time. I will show an example of rules in a subsequent tutorial.

strict image maps — handling missing parameters

If a url definition uses a parameter which is not defined, then one of three things happen.

If image_map_missing_parameter=exit, then Circos exists with an error message. This behaviour is useful if you suspect that there's an error in the URL definition, or if you don't know whether a parameter is defined. This setting is draconic but safe.

If image_map_missing_parameter=removeparam, the [parameter_name] field will be removed. Any parameters that remain will be used. For example, if

url = script?x=[x]&y=[y]

and parameter y is not defined for an element, the effect will be the same as if we defined this url for that element.

url = script?x=[x]&y=

Finally, if image_map_missing_parameter=removeurl, then the URL is not used. In other words, the element will not have an entry in the image map.

scaling and shifting image maps

The parameters


are used to transform the values of image map coordinates using a translation and scaling.

The *shift values will be added to the x (and/or y) coordinate of the map element boundary. These offsets are useful if the Circos image will be composited with another image, or cropped, or manipulated in any manner that shifts its original (0,0) (upper left) corner. You can define one or both values, and they can be negative.

The *factor parameter values multiply the x (and/or y) coordinates for each map element boundary. These parameters are useful if you are going to resize the image later. For example, if you create a 3000 x 3000 pixel image radius=1500px, but publish a 800 x 800 pixel image, set both factors to 800/3000 = 2.666667. Unless you are stretching the image (don't do it!) both factors should have the same value.

debugging image maps

For debugging purposes, you can overlay the image map elements on top of the PNG image (not SVG). Each element in the overlay can have a fill color and stroke color. Note that if you add any x/y shift or multiplicative factors (above) then the overlay will reflect those factors.

image_map_overlay              = yes
image_map_overlay_fill_color   = lred_a4
image_map_overlay_stroke_color = red
image_map_overlay_stroke_thickness = 8