A quick video overview:

Here is a video Circa tutorial that walks through the types of files you can plot in Circa, as well as how to export a file from Excel.

Genome file

The first step in Circa is to load a “genome file” with the chromosome names and sizes:

This information enables Circa to draw the chromosomes with the right names and relative sizes.
Human GRCh37 (hg19) and GRCh38 are included with a simple button push.
For other genomes, you can generate that genome file in any way you want, but the method below covers a common case.

From FASTA to a “genome file”

If you have a FASTA file, you can use samtools faidx to get the .fai index file, which has the same info as the genome file needed.
# starting with your_genome.fasta, index it to get the lengths
samtools faidx your_genome.fasta

# then add a header:
cat <(echo -e "chromosome\tsize\tnot_needed1\tnot_needed2\tnot_needed3") your_genome.fasta.fai > genome_file_for_Circa.tsv

Here’s a toy example (with very short sequences):

# contents of your_genome.fasta

# contents of genome_file_for_Circa.tsv
chromosome size not_needed1 not_needed2 not_needed3
A 10 3 10 11
B 10 17 10 11
C 20 31 20 21

(These should be tabs, though this site renders them as spaces above).

Note the first column has chromosome names and the second column contains the sizes 10, 10, and 20. Then loading that into Circa produces the following base plot:

Notice here that the chromosome segments (10, 10, and 20) yield a sum of 40, so the first two chromosomes each take up 10/40 = 1/4 of the circle, and chromosome C takes up 20/40 = 1/2.

This is the coordinate system that we then start plotting data onto.

Main data files

Now that you have the “genome file”, the coordinate system is all set up and ready for you to start plotting your data. Just remember that the chromosome names must match and the data points will only be plotted if they fit inside the chromosome sizes you indicated in the genome file. A warning will be shown in Circa if any data points are skipped due to this kind of name or size mismatch.

Here is an example:


This one file can be used to draw various kinds of layer types:

rectangle settings

area settingstext settings

Notice that all layer types have at least a chromosome and one position, while each has some additional information to convey.

The layer types above can also be colored by a column. Here we color the innermost text layer by the “type” column.

coloring by a column

To draw connections or ribbons, since these connect two positions in the genome, the file will need to have two sets of chromosome and position:


The data file above produces the following ribbons:

Settings for ribbons in CircaRibbons in Circa

The difference between ribbons and connections is that ribbons use both the start and stop positions to connect two sequences, while connections use only one position to connect two points in the genome.

The same file above also produces the following connections:

connections settingsconnections plot

More notes on file formats

Rows and columns

Each file must be neatly formatted into rows and columns, where columns are separated by tabs, spaces, or commas. The delimiter is detected automatically.


Each file must have a header in the first row, which gives the name for each column.


The files must be smaller than 10MB. Anything bigger than that would create a really crowded plot anyway, so it is best to filter your data or consolidate it if the file is too big. This will also better show the information you are trying to convey

Text files

Circa cannot read binary files or any or formats that are not human-readable in a text editor like nano, vim, or TextEdit. Excel files can be exported to CSV by going to File -> Save As… and changing the File Format in the dropdown to CSV.

What next?

Check out the other tutorials for Circa on the Circa tutorials page.

When you have made sure Circa is right for you, you can get it here:
Ready to make beautiful circos plots from your own data? Click here to buy Circa