pyCirclize: Circular visualization in Python

Table of contents

• Overview
• Installation
• API Usage
• Code Example
• Tooltip Option
• Star History

Overview

pyCirclize is a circular visualization python package implemented based on matplotlib. This package is developed for the purpose of easily and beautifully plotting circular figure such as Circos Plot and Chord Diagram in Python. In addition, useful genome and phylogenetic tree visualization methods for the bioinformatics field are also implemented. pyCirclize was inspired by circlize and pyCircos. More detailed documentation is available here.

Fig.1 pyCirclize example plot gallery

Installation

Python 3.10 or later is required for installation.

Install PyPI package:

pip install pycirclize

Install conda-forge package:

conda install -c conda-forge pycirclize

API Usage

API usage is described in each of the following sections in the document.

• Getting Started
• Plot API Example
• Chord Diagram
• Radar Chart
• Circos Plot (Genomics)
• Comparative Genomics
• Phylogenetic Tree
• Plot Tips

Code Example

1. Circos Plot

```python from pycirclize import Circos import numpy as np np.random.seed(0)

Initialize Circos sectors

sectors = {"A": 10, "B": 15, "C": 12, "D": 20, "E": 15} circos = Circos(sectors, space=5)

for sector in circos.sectors: # Plot sector name sector.text(f"Sector: {sector.name}", r=110, size=15) # Create x positions & random y values x = np.arange(sector.start, sector.end) + 0.5 y = np.random.randint(0, 100, len(x)) # Plot lines track1 = sector.addtrack((80, 100), rpadratio=0.1) track1.xticksbyinterval(interval=1) track1.axis() track1.line(x, y) # Plot points track2 = sector.addtrack((55, 75), rpadratio=0.1) track2.axis() track2.scatter(x, y) # Plot bars track3 = sector.addtrack((30, 50), rpad_ratio=0.1) track3.axis() track3.bar(x, y)

Plot links

circos.link(("A", 0, 3), ("B", 15, 12)) circos.link(("B", 0, 3), ("C", 7, 11), color="skyblue") circos.link(("C", 2, 5), ("E", 15, 12), color="chocolate", direction=1) circos.link(("D", 3, 5), ("D", 18, 15), color="lime", ec="black", lw=0.5, hatch="//", direction=2) circos.link(("D", 8, 10), ("E", 2, 8), color="violet", ec="red", lw=1.0, ls="dashed")

circos.savefig("example01.png") ```

2. Circos Plot (Genomics)

```python from pycirclize import Circos from pycirclize.utils import fetchgenbankby_accid from pycirclize.parser import Genbank

Download NC_002483 E.coli plasmid genbank

gbkfetchdata = fetchgenbankbyaccid("NC002483") gbk = Genbank(gbkfetchdata)

Initialize Circos instance with genome size

sectors = gbk.get_seqid2size() space = 0 if len(sectors) == 1 else 2 circos = Circos(sectors, space=space) circos.text(f"Escherichia coli K-12 plasmid F\n\n{gbk.name}", size=14)

seqid2features = gbk.getseqid2features(featuretype="CDS") for sector in circos.sectors: # Setup track for features plot fcdstrack = sector.addtrack((95, 100)) fcdstrack.axis(fc="lightgrey", ec="none", alpha=0.5) rcdstrack = sector.addtrack((90, 95)) rcdstrack.axis(fc="lightgrey", ec="none", alpha=0.5) # Plot forward/reverse strand CDS features = seqid2features[sector.name] for feature in features: if feature.location.strand == 1: fcdstrack.genomicfeatures(feature, plotstyle="arrow", fc="salmon", lw=0.5) else: rcdstrack.genomicfeatures(feature, plotstyle="arrow", fc="skyblue", lw=0.5)

# Plot 'gene' qualifier label if exists
labels, label_pos_list = [], []
for feature in features:
    start = int(feature.location.start)
    end = int(feature.location.end)
    label_pos = (start + end) / 2
    gene_name = feature.qualifiers.get("gene", [None])[0]
    if gene_name is not None:
        labels.append(gene_name)
        label_pos_list.append(label_pos)
        f_cds_track.annotate(label_pos, gene_name, label_size=6)

# Plot xticks (interval = 10 Kb)
r_cds_track.xticks_by_interval(
    10000, outer=False, label_formatter=lambda v: f"{v/1000:.1f} Kb"
)

circos.savefig("example02.png") ```

3. Chord Diagram

```python from pycirclize import Circos import pandas as pd

Create matrix dataframe (3 x 6)

rownames = ["F1", "F2", "F3"] colnames = ["T1", "T2", "T3", "T4", "T5", "T6"] matrixdata = [ [10, 16, 7, 7, 10, 8], [4, 9, 10, 12, 12, 7], [17, 13, 7, 4, 20, 4], ] matrixdf = pd.DataFrame(matrixdata, index=rownames, columns=col_names)

Initialize Circos instance for chord diagram plot

circos = Circos.chorddiagram( matrixdf, space=5, cmap="tab10", labelkws=dict(size=12), linkkws=dict(ec="black", lw=0.5, direction=1), )

circos.savefig("example03.png") ```

4. Phylogenetic Tree

```python from pycirclize import Circos from pycirclize.utils import loadexampletree_file, ColorCycler from matplotlib.lines import Line2D

Initialize Circos from phylogenetic tree

treefile = loadexampletreefile("largeexample.nwk") circos, tv = Circos.initializefromtree( treefile, rlim=(30, 100), leaflabelsize=5, linekws=dict(color="lightgrey", lw=1.0), )

Define group-species dict for tree annotation

In this example, set minimum species list to specify group's MRCA node

groupname2specieslist = dict( Monotremata=["Tachyglossusaculeatus", "Ornithorhynchusanatinus"], Marsupialia=["Monodelphisdomestica", "Vombatusursinus"], Xenarthra=["Choloepusdidactylus", "Dasypusnovemcinctus"], Afrotheria=["Trichechusmanatus", "Chrysochlorisasiatica"], Euarchontes=["Galeopterusvariegatus", "Theropithecusgelada"], Glires=["Oryctolaguscuniculus", "Microtusoregoni"], Laurasiatheria=["Talpaoccidentalis", "Miroungaleonina"], )

Set tree line color & label color

ColorCycler.setcmap("tab10") groupname2color = {name: ColorCycler() for name in groupname2specieslist.keys()} for groupname, specieslist in groupname2specieslist.items(): color = groupname2color[groupname] tv.setnodelineprops(specieslist, color=color, applylabelcolor=True)

Plot figure & set legend on center

fig = circos.plotfig() _ = circos.ax.legend( handles=[Line2D([], [], label=n, color=c) for n, c in groupname2color.items()], labelcolor=groupname2color.values(), fontsize=6, loc="center", bboxtoanchor=(0.5, 0.5), ) fig.savefig("example04.png") ```

5. Radar Chart

```python from pycirclize import Circos import pandas as pd

Create RPG jobs parameter dataframe (3 jobs, 7 parameters)

df = pd.DataFrame( data=[ [80, 80, 80, 80, 80, 80, 80], [90, 20, 95, 95, 30, 30, 80], [60, 90, 20, 20, 100, 90, 50], ], index=["Hero", "Warrior", "Wizard"], columns=["HP", "MP", "ATK", "DEF", "SP.ATK", "SP.DEF", "SPD"], )

Initialize Circos instance for radar chart plot

circos = Circos.radarchart( df, vmax=100, markersize=6, gridintervalratio=0.2, )

Plot figure & set legend on upper right

fig = circos.plotfig() _ = circos.ax.legend(loc="upper right", fontsize=10) fig.savefig("example05.png") ```

Tooltip Option

pyCirclize supports tooltip display in jupyter using ipympl. To enable tooltip, install pycirclize with ipympl and call circos.plotfig(tooltip=True) method. Tooltip option is tested on jupyter notebooks in VScode and JupyterLab.

```shell pip install pycirclize[tooltip]

or

conda install -c conda-forge pycirclize ipympl ```

[!WARNING] Interactive tooltip plots require live python kernel. Be aware that tooltips are not always enabled in the notebook after plotting.

Star History