{"id":33051322,"url":"https://github.com/moshi4/pyCirclize","last_synced_at":"2025-11-18T21:00:58.268Z","repository":{"id":64906509,"uuid":"579313517","full_name":"moshi4/pyCirclize","owner":"moshi4","description":"Circular visualization in Python (Circos Plot, Chord Diagram, Radar Chart)","archived":false,"fork":false,"pushed_at":"2025-10-03T18:12:45.000Z","size":61283,"stargazers_count":968,"open_issues_count":4,"forks_count":53,"subscribers_count":10,"default_branch":"main","last_synced_at":"2025-10-03T19:33:58.780Z","etag":null,"topics":["bioinformatics","chord-diagram","circos","comparative-genomics","data-visualization","dataviz","genomics","genomics-visualization","matplotlib","microbial-genomics","phylogenetic-trees","python","radar-chart","visualization"],"latest_commit_sha":null,"homepage":"https://moshi4.github.io/pyCirclize/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/moshi4.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2022-12-17T09:21:45.000Z","updated_at":"2025-10-03T17:50:27.000Z","dependencies_parsed_at":"2023-02-19T17:46:12.568Z","dependency_job_id":"5e0d6196-5943-4f07-abbe-e3d8672b4697","html_url":"https://github.com/moshi4/pyCirclize","commit_stats":{"total_commits":180,"total_committers":2,"mean_commits":90.0,"dds":"0.022222222222222254","last_synced_commit":"d9e47564b8f0917b66d217c005957cf585a3b0cc"},"previous_names":[],"tags_count":26,"template":false,"template_full_name":null,"purl":"pkg:github/moshi4/pyCirclize","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/moshi4%2FpyCirclize","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/moshi4%2FpyCirclize/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/moshi4%2FpyCirclize/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/moshi4%2FpyCirclize/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/moshi4","download_url":"https://codeload.github.com/moshi4/pyCirclize/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/moshi4%2FpyCirclize/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":285138471,"owners_count":27121052,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-11-18T02:00:05.759Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bioinformatics","chord-diagram","circos","comparative-genomics","data-visualization","dataviz","genomics","genomics-visualization","matplotlib","microbial-genomics","phylogenetic-trees","python","radar-chart","visualization"],"created_at":"2025-11-14T03:00:27.110Z","updated_at":"2025-11-18T21:00:58.260Z","avatar_url":"https://github.com/moshi4.png","language":"Python","readme":"# pyCirclize: Circular visualization in Python\n\n![Python3](https://img.shields.io/badge/Language-Python3-steelblue)\n![OS](https://img.shields.io/badge/OS-_Windows_|_Mac_|_Linux-steelblue)\n![License](https://img.shields.io/badge/License-MIT-steelblue)\n[![Latest PyPI version](https://img.shields.io/pypi/v/pycirclize.svg)](https://pypi.python.org/pypi/pycirclize)\n[![conda-forge](https://img.shields.io/conda/vn/conda-forge/pycirclize.svg?color=green)](https://anaconda.org/conda-forge/pycirclize)\n[![CI](https://github.com/moshi4/pyCirclize/actions/workflows/ci.yml/badge.svg)](https://github.com/moshi4/pyCirclize/actions/workflows/ci.yml)\n\n## Table of contents\n\n- [Overview](#overview)\n- [Installation](#installation)\n- [API Usage](#api-usage)\n- [Code Example](#code-example)\n- [Tooltip Option](#tooltip-option)\n- [Star History](#star-history)\n\n## Overview\n\npyCirclize is a circular visualization python package implemented based on matplotlib.\nThis package is developed for the purpose of easily and beautifully plotting circular figure such as Circos Plot and Chord Diagram in Python.\nIn addition, useful genome and phylogenetic tree visualization methods for the bioinformatics field are also implemented.\npyCirclize was inspired by [circlize](https://github.com/jokergoo/circlize) and [pyCircos](https://github.com/ponnhide/pyCircos).\nMore detailed documentation is available [here](https://moshi4.github.io/pyCirclize/).\n\n![pyCirclize_gallery.png](https://raw.githubusercontent.com/moshi4/pyCirclize/main/docs/images/pyCirclize_gallery.png)  \n**Fig.1 pyCirclize example plot gallery**\n\n## Installation\n\n`Python 3.10 or later` is required for installation.\n\n**Install PyPI package:**\n\n    pip install pycirclize\n\n**Install conda-forge package:**\n\n    conda install -c conda-forge pycirclize\n\n## API Usage\n\nAPI usage is described in each of the following sections in the [document](https://moshi4.github.io/pyCirclize/).\n\n- [Getting Started](https://moshi4.github.io/pyCirclize/getting_started/)\n- [Plot API Example](https://moshi4.github.io/pyCirclize/plot_api_example/)\n- [Chord Diagram](https://moshi4.github.io/pyCirclize/chord_diagram/)\n- [Radar Chart](https://moshi4.github.io/pyCirclize/radar_chart/)\n- [Circos Plot (Genomics)](https://moshi4.github.io/pyCirclize/circos_plot/)\n- [Comparative Genomics](https://moshi4.github.io/pyCirclize/comparative_genomics/)\n- [Phylogenetic Tree](https://moshi4.github.io/pyCirclize/phylogenetic_tree/)\n- [Plot Tips](https://moshi4.github.io/pyCirclize/plot_tips/)\n\n## Code Example\n\n### 1. Circos Plot\n\n```python\nfrom pycirclize import Circos\nimport numpy as np\nnp.random.seed(0)\n\n# Initialize Circos sectors\nsectors = {\"A\": 10, \"B\": 15, \"C\": 12, \"D\": 20, \"E\": 15}\ncircos = Circos(sectors, space=5)\n\nfor sector in circos.sectors:\n    # Plot sector name\n    sector.text(f\"Sector: {sector.name}\", r=110, size=15)\n    # Create x positions \u0026 random y values\n    x = np.arange(sector.start, sector.end) + 0.5\n    y = np.random.randint(0, 100, len(x))\n    # Plot lines\n    track1 = sector.add_track((80, 100), r_pad_ratio=0.1)\n    track1.xticks_by_interval(interval=1)\n    track1.axis()\n    track1.line(x, y)\n    # Plot points \n    track2 = sector.add_track((55, 75), r_pad_ratio=0.1)\n    track2.axis()\n    track2.scatter(x, y)\n    # Plot bars\n    track3 = sector.add_track((30, 50), r_pad_ratio=0.1)\n    track3.axis()\n    track3.bar(x, y)\n\n# Plot links \ncircos.link((\"A\", 0, 3), (\"B\", 15, 12))\ncircos.link((\"B\", 0, 3), (\"C\", 7, 11), color=\"skyblue\")\ncircos.link((\"C\", 2, 5), (\"E\", 15, 12), color=\"chocolate\", direction=1)\ncircos.link((\"D\", 3, 5), (\"D\", 18, 15), color=\"lime\", ec=\"black\", lw=0.5, hatch=\"//\", direction=2)\ncircos.link((\"D\", 8, 10), (\"E\", 2, 8), color=\"violet\", ec=\"red\", lw=1.0, ls=\"dashed\")\n\ncircos.savefig(\"example01.png\")\n```\n\n![example01.png](https://raw.githubusercontent.com/moshi4/pyCirclize/main/docs/images/example01.png)  \n\n### 2. Circos Plot (Genomics)\n\n```python\nfrom pycirclize import Circos\nfrom pycirclize.utils import fetch_genbank_by_accid\nfrom pycirclize.parser import Genbank\n\n# Download `NC_002483` E.coli plasmid genbank\ngbk_fetch_data = fetch_genbank_by_accid(\"NC_002483\")\ngbk = Genbank(gbk_fetch_data)\n\n# Initialize Circos instance with genome size\nsectors = gbk.get_seqid2size()\nspace = 0 if len(sectors) == 1 else 2\ncircos = Circos(sectors, space=space)\ncircos.text(f\"Escherichia coli K-12 plasmid F\\n\\n{gbk.name}\", size=14)\n\nseqid2features = gbk.get_seqid2features(feature_type=\"CDS\")\nfor sector in circos.sectors:\n    # Setup track for features plot\n    f_cds_track = sector.add_track((95, 100))\n    f_cds_track.axis(fc=\"lightgrey\", ec=\"none\", alpha=0.5)\n    r_cds_track = sector.add_track((90, 95))\n    r_cds_track.axis(fc=\"lightgrey\", ec=\"none\", alpha=0.5)\n    # Plot forward/reverse strand CDS\n    features = seqid2features[sector.name]\n    for feature in features:\n        if feature.location.strand == 1:\n            f_cds_track.genomic_features(feature, plotstyle=\"arrow\", fc=\"salmon\", lw=0.5)\n        else:\n            r_cds_track.genomic_features(feature, plotstyle=\"arrow\", fc=\"skyblue\", lw=0.5)\n\n    # Plot 'gene' qualifier label if exists\n    labels, label_pos_list = [], []\n    for feature in features:\n        start = int(feature.location.start)\n        end = int(feature.location.end)\n        label_pos = (start + end) / 2\n        gene_name = feature.qualifiers.get(\"gene\", [None])[0]\n        if gene_name is not None:\n            labels.append(gene_name)\n            label_pos_list.append(label_pos)\n            f_cds_track.annotate(label_pos, gene_name, label_size=6)\n\n    # Plot xticks (interval = 10 Kb)\n    r_cds_track.xticks_by_interval(\n        10000, outer=False, label_formatter=lambda v: f\"{v/1000:.1f} Kb\"\n    )\n\ncircos.savefig(\"example02.png\")\n```\n\n![example02.png](https://raw.githubusercontent.com/moshi4/pyCirclize/main/docs/images/example02.png)  \n\n### 3. Chord Diagram\n\n```python\nfrom pycirclize import Circos\nimport pandas as pd\n\n# Create matrix dataframe (3 x 6)\nrow_names = [\"F1\", \"F2\", \"F3\"]\ncol_names = [\"T1\", \"T2\", \"T3\", \"T4\", \"T5\", \"T6\"]\nmatrix_data = [\n    [10, 16, 7, 7, 10, 8],\n    [4, 9, 10, 12, 12, 7],\n    [17, 13, 7, 4, 20, 4],\n]\nmatrix_df = pd.DataFrame(matrix_data, index=row_names, columns=col_names)\n\n# Initialize Circos instance for chord diagram plot\ncircos = Circos.chord_diagram(\n    matrix_df,\n    space=5,\n    cmap=\"tab10\",\n    label_kws=dict(size=12),\n    link_kws=dict(ec=\"black\", lw=0.5, direction=1),\n)\n\ncircos.savefig(\"example03.png\")\n```\n\n![example03.png](https://raw.githubusercontent.com/moshi4/pyCirclize/main/docs/images/example03.png)  \n\n### 4. Phylogenetic Tree\n\n```python\nfrom pycirclize import Circos\nfrom pycirclize.utils import load_example_tree_file, ColorCycler\nfrom matplotlib.lines import Line2D\n\n# Initialize Circos from phylogenetic tree\ntree_file = load_example_tree_file(\"large_example.nwk\")\ncircos, tv = Circos.initialize_from_tree(\n    tree_file,\n    r_lim=(30, 100),\n    leaf_label_size=5,\n    line_kws=dict(color=\"lightgrey\", lw=1.0),\n)\n\n# Define group-species dict for tree annotation\n# In this example, set minimum species list to specify group's MRCA node\ngroup_name2species_list = dict(\n    Monotremata=[\"Tachyglossus_aculeatus\", \"Ornithorhynchus_anatinus\"],\n    Marsupialia=[\"Monodelphis_domestica\", \"Vombatus_ursinus\"],\n    Xenarthra=[\"Choloepus_didactylus\", \"Dasypus_novemcinctus\"],\n    Afrotheria=[\"Trichechus_manatus\", \"Chrysochloris_asiatica\"],\n    Euarchontes=[\"Galeopterus_variegatus\", \"Theropithecus_gelada\"],\n    Glires=[\"Oryctolagus_cuniculus\", \"Microtus_oregoni\"],\n    Laurasiatheria=[\"Talpa_occidentalis\", \"Mirounga_leonina\"],\n)\n\n# Set tree line color \u0026 label color\nColorCycler.set_cmap(\"tab10\")\ngroup_name2color = {name: ColorCycler() for name in group_name2species_list.keys()}\nfor group_name, species_list in group_name2species_list.items():\n    color = group_name2color[group_name]\n    tv.set_node_line_props(species_list, color=color, apply_label_color=True)\n\n# Plot figure \u0026 set legend on center\nfig = circos.plotfig()\n_ = circos.ax.legend(\n    handles=[Line2D([], [], label=n, color=c) for n, c in group_name2color.items()],\n    labelcolor=group_name2color.values(),\n    fontsize=6,\n    loc=\"center\",\n    bbox_to_anchor=(0.5, 0.5),\n)\nfig.savefig(\"example04.png\")\n```\n\n![example04.png](https://raw.githubusercontent.com/moshi4/pyCirclize/main/docs/images/example04.png)  \n\n### 5. Radar Chart\n\n```python\nfrom pycirclize import Circos\nimport pandas as pd\n\n# Create RPG jobs parameter dataframe (3 jobs, 7 parameters)\ndf = pd.DataFrame(\n    data=[\n        [80, 80, 80, 80, 80, 80, 80],\n        [90, 20, 95, 95, 30, 30, 80],\n        [60, 90, 20, 20, 100, 90, 50],\n    ],\n    index=[\"Hero\", \"Warrior\", \"Wizard\"],\n    columns=[\"HP\", \"MP\", \"ATK\", \"DEF\", \"SP.ATK\", \"SP.DEF\", \"SPD\"],\n)\n\n# Initialize Circos instance for radar chart plot\ncircos = Circos.radar_chart(\n    df,\n    vmax=100,\n    marker_size=6,\n    grid_interval_ratio=0.2,\n)\n\n# Plot figure \u0026 set legend on upper right\nfig = circos.plotfig()\n_ = circos.ax.legend(loc=\"upper right\", fontsize=10)\nfig.savefig(\"example05.png\")\n```\n\n![example05.png](https://raw.githubusercontent.com/moshi4/pyCirclize/main/docs/images/example05.png)  \n\n## Tooltip Option\n\npyCirclize supports tooltip display in jupyter using [ipympl](https://github.com/matplotlib/ipympl).\nTo enable tooltip, install pycirclize with ipympl and call `circos.plotfig(tooltip=True)` method.\nTooltip option is tested on jupyter notebooks in VScode and JupyterLab.\n\n```shell\npip install pycirclize[tooltip]\n# or\nconda install -c conda-forge pycirclize ipympl\n```\n\n\u003e [!WARNING]\n\u003e Interactive tooltip plots require live python kernel.\n\u003e Be aware that tooltips are not permanently enabled in the notebook after plotting.\n\n![pyCirclize_tooltip.gif](https://raw.githubusercontent.com/moshi4/pyCirclize/main/docs/images/pyCirclize_tooltip.gif)  \n\n## Star History\n\n[![Star History Chart](https://api.star-history.com/svg?repos=moshi4/pyCirclize\u0026type=Date)](https://star-history.com/#moshi4/pyCirclize\u0026Date)\n","funding_links":[],"categories":["Circular"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmoshi4%2FpyCirclize","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmoshi4%2FpyCirclize","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmoshi4%2FpyCirclize/lists"}