Build circular genome visualizations using circlize (R), pyCirclize (Python), or Circos (Perl CLI) with ideogram tracks, multi-data tracks (scatter, histogram, heatmap), chord/link arcs for interactions, and explicit circos.clear() between plots. Covers when circular is appropriate vs when Cartesian wins (Cleveland-McGill 1984), karyograms, and chromosome adjacency in chord diagrams. Use when adjacency on the circle conveys meaning — chromosome-level overview, structural variants, Hi-C interactions, cross-genome comparisons.
Standardmäßig ist der Prompt ausgewählt, der zuerst die Quelle prüft. Sie können zu einem direkten Befehl wechseln oder eine lokale Kopie herunterladen.
Quelldateien prüfen
Lesen Sie SKILL.md und alle von SkillsMP angezeigten Begleitdateien, bevor Sie sich für eine Installation entscheiden.
Mit Codex oder Claude installieren Kopieren Sie diesen Prompt, fügen Sie ihn in Codex, Claude oder einen anderen Assistant ein und lassen Sie die Skill-Seite prüfen und installieren.
Ein direkter Befehl überspringt den Prüf-Prompt. Prüfen Sie die Quelle, bevor Sie ihn ausführen.
Build circular genome visualizations using circlize (R), pyCirclize (Python), or Circos (Perl CLI) with ideogram tracks, multi-data tracks (scatter, histogram, heatmap), chord/link arcs for interactions, and explicit circos.clear() between plots. Covers when circular is appropriate vs when Cartesian wins (Cleveland-McGill 1984), karyograms, and chromosome adjacency in chord diagrams. Use when adjacency on the circle conveys meaning — chromosome-level overview, structural variants, Hi-C interactions, cross-genome comparisons.
Before using code patterns, verify installed versions match. If versions differ:
R: packageVersion('<pkg>') then ?function_name
Python: pip show <package> then help(module.function)
If code throws ImportError, AttributeError, or TypeError, introspect the installed package and adapt the example to match the actual API rather than retrying.
Circular Genome Plots (Circos)
"Make a circos plot" -> Render genome chromosomes around a circle with stacked tracks (histogram, scatter, heatmap) and arcs/chords showing interactions. Krzywinski 2009 Genome Res 19:1639 introduced the genre for genome-scale comparative views. The single decision that matters:
does the circular layout convey meaning that Cartesian cannot?
CLI: Circos (Perl); config-driven; most flexible but steepest learning
The Single Most Important Modern Insight -- Circular Plots Often Hide What Cartesian Reveals
Cleveland-McGill 1984 J Am Stat Assoc 79:531 effectiveness rankings establish that position-on-common-scale (Cartesian) is the most accurate visual channel; circular position requires mental "unwrapping" and impairs precise value comparison. Heer-Bostock 2010 CHI replicated the ranking in modern crowd studies. Use circular only when adjacency on the circle conveys meaning that linear cannot.
Use circular ONLY when:
Chromosome adjacency matters (whole-genome SVs, Hi-C contacts where genome circularity is the geometry)
Pairwise interactions between many entities (chord diagrams; chromosome translocations)
Aesthetic / overview infographic for cover figure
Do NOT use circular for:
Comparing values across categories (Cartesian bar/dot wins)
Time series (linear axis wins)
Anything where precise value reading matters
The circos plot is a beautiful but dangerous default. The most-cited published critique is the genre being applied where it adds no information.
circlize (R) — Modern Default
Goal: Render a multi-track circos plot with ideograms, gene-density histogram, variant-density heatmap, and inter-chromosomal SV links.
Approach: Initialize with chromosome ideograms via circos.initializeWithIdeogram; add tracks with circos.genomicTrack + appropriate panel function; add links with circos.link; always call circos.clear() after the plot completes.
library(circlize)# 1. Initialize with hg38 ideograms
pdf('circos.pdf', width =8, height =8)
circos.par(start.degree =90,# 12 o'clock start
gap.degree =c(rep(1,23),5))# bigger gap before chr1 for visual break# hg38 specifically benefits from explicit chromosome.index to skip unmapped contigs
circos.initializeWithIdeogram(species ='hg38',
chromosome.index = paste0('chr',c(1:22,'X','Y')),
plotType =c('axis','labels','ideogram'))# 2. Gene-density histogram (outermost data track)
circos.genomicDensity(gene_bed, col ='#0072B2', track.height =0.08)# 3. Variant-density heatmap
circos.genomicHeatmap(variant_bed,
col = colorRamp2(c(0,100),c('white','#D55E00')),
heatmap_height =0.08, side ='inside')# 4. CNV scatter
circos.genomicTrack(cnv_bed, ylim =c(-2,2),
panel.fun =function(region, value, ...){
circos.genomicPoints(region, value,
col = ifelse(value >0.3,'#D55E00',
ifelse(value <-0.3,'#0072B2','grey60')),
pch =16, cex =0.4)},
track.height =0.1)# 5. Inter-chromosomal SV linksfor(i inseq_len(nrow(sv_df))){
circos.link(sv_df$chr1[i],c(sv_df$start1[i], sv_df$end1[i]),
sv_df$chr2[i],c(sv_df$start2[i], sv_df$end2[i]),
col ='#888888', lwd =0.4)}# 6. CRITICAL -- clear global state
circos.clear()
dev.off()
The circos.clear() Trap
circos.par() settings (start.degree, gap.degree, canvas.xlim, canvas.ylim, clock.wise, circle.margin) are GLOBAL state. After a plot completes, those settings persist into the next plot.
Forgetting circos.clear() produces:
Next circos.par() calls silently fail to take effect (warning, easily missed in loops)
Re-initialization may error or render at wrong angles
Loop-rendered figures inherit state from the previous iteration
Always call circos.clear() after every plot. Make it the last line of the plotting block alongside dev.off().
pyCirclize (Python)
from pycirclize import Circos
import matplotlib.pyplot as plt
sectors = {'chr1': 248956422, 'chr2': 242193529, ...}
circos = Circos(sectors, space=2) # space = degree gap between sectorsfor sector in circos.sectors:
sector.text(sector.name, r=110, size=8)
# outer ideogram
sector.axis(r_lim=(95, 100), fc='lightgrey')
# data track
track = sector.add_track((75, 90))
track.bar(positions, heights, width=bin_size, color='#0072B2')
# Inter-sector links (chord diagram)
circos.link(('chr1', 1e8, 1.1e8), ('chr5', 2e8, 2.1e8),
color='#888888', alpha=0.5)
fig = circos.plotfig()
fig.savefig('circos_py.pdf', bbox_inches='tight')
pyCirclize is a younger package than circlize but actively developed (Shimoyama 2024+). API more Pythonic than circlize-via-rpy2.
Circos (Krzywinski 2009) is the original; supports unlimited tracks and arbitrary geometries via configuration. For publication-grade complex figures the Perl tool remains the most powerful. For Python/R workflows, circlize/pyCirclize are more accessible.
Decision Tree by Use Case
Use case
Recommended
Why
Whole-genome CNV summary
circlize/pyCirclize
Standard genre
SV link diagram
Chord arcs in circos
Inter-chromosomal adjacency
Hi-C contact summary at chromosome level
circos heatmap track
Adjacency matters
Per-sample mutation overview
Circular karyogram
Aesthetic; comparable to OncoPrint
Cohort-wide gene expression comparison
NOT circular
Use heatmap (Cartesian wins)
Time-series of any kind
NOT circular
Use line plot
Pathway diagram
NOT circular
Use Cytoscape
Ideogram + Karyogram Without Circos
For per-chromosome data display where circularity is not required, karyoploteR (Gel 2017 Bioinformatics 33:3088) renders linear ideograms with stacked data tracks — often the better choice for CNV per-chromosome views.
library(karyoploteR)
kp <- plotKaryotype(genome ='hg38', chromosomes =c('chr1','chr7','chr17'))
kpAddBaseNumbers(kp)
kpLines(kp, data = cnv_gr, y = cnv_gr$log2)
kpAddCytobandLabels(kp)
See copy-number/cnv-visualization for karyoploteR in depth.
Per-Method Failure Modes
circos.clear() forgotten in a loop
Trigger: Plotting multiple circos figures in a for loop without circos.clear() between.
Mechanism: circos.par settings (gap.degree, start.degree, clock.wise) persist across plots.
Symptom: Plots 2..N inherit state from plot 1; gap sizes, rotation differ unexpectedly.
Fix: End every plot block with circos.clear(). Make it a hygiene rule.
Using circular when Cartesian would be better
Trigger: "Circos plot of gene expression across 20 conditions."
Mechanism: Circular impairs value comparison (Cleveland-McGill 1984; Heer-Bostock 2010).
Symptom: Reviewer or coauthor says "I can't tell which condition is highest."
Fix: Use clustered heatmap. Reserve circos for genome-adjacency or chord-diagram use cases.
Too many links produce a black blob
Trigger: Plotting 10000+ chord links between chromosomes.
Mechanism: Overlap saturates the center; no individual link visible.
Symptom: Center of circos is uniformly dark.
Fix: Filter to top-confidence links; OR color-bin by interaction strength with alpha; OR aggregate to chromosome-level summary then link.
Sector ordering arbitrary
Trigger: Default sector order is input order.
Mechanism: circlize / pyCirclize do not auto-order chromosomes 1..22, X, Y.
Symptom: Chromosomes appear in genome-build-file order.
Trigger:species = 'hg19' when data is hg38-coordinate.
Mechanism: circlize fetches cytoband data per species; mismatch renders correct ideogram but wrong banding for the data.
Symptom: Cytoband boundaries don't match published references.
Fix: Match species to data coordinate system. For non-standard genomes, supply custom cytoband file. For species = 'hg38' specifically, always pass chromosome.index = paste0('chr', c(1:22, 'X', 'Y')) to skip unmapped contigs (jokergoo/circlize issue #46).
Ideogram covers data track
Trigger: Default ideogram track height too large; data track squeezed.
Mechanism: circos.initializeWithIdeogram uses ~5% of radius; left-over for data.
Symptom: Data values invisible because track is too narrow.
Fix: Reduce cytoband.height in initialization; OR use plotType = c('axis', 'labels') to omit ideogram entirely.
Chromosome label collisions for small chromosomes
Trigger: Default label position; small chromosomes (chr21, chr22, chrY) have overlapping labels.
Mechanism: Labels drawn at sector midpoints regardless of sector width.
Symptom: Labels overlap.
Fix:circos.par(gap.degree = c(rep(1, 22), 10, 10, 10)) for larger gaps before small chromosomes; OR reduce label font size.
Reconciliation
Pattern
Cause
Action
circlize and pyCirclize differ in default rotation
Different start-angle convention
Set start.degree=90 (R) / equivalent (Python) explicitly
Cytoband colors don't match UCSC
Different species cytoband source
Verify species; for custom genomes supply band file
Inter-sector links arc the "long way around"
Default arc direction
Some chord packages support direction = 'short'
Quantitative Thresholds
Threshold
Value
Source
Max sectors readable
~30
Visualization practical
Max links before blob
~5000
Practical; depends on alpha
Cytoband.height default
0.05 of radius
circlize default
When circular adds value
Adjacency-meaningful only
Cleveland-McGill 1984
Common Errors
Error / symptom
Cause
Solution
Subsequent plots use wrong rotation
circos.clear() forgotten
Always end with circos.clear()
Chromosomes out of order
Default = input order
Explicit chromosome.index
Cytoband mismatch
Wrong species
Match species to data coords
Center of circos black
Too many links
Filter or aggregate
Reviewer asks "why circular?"
Cartesian would have been clearer
Migrate to heatmap unless adjacency matters
Small-chromosome label overlap
Default label position
Larger gap.degree before small sectors
References
Cleveland WS, McGill R. 1984. Graphical perception: theory, experimentation, and application to the development of graphical methods. J Am Stat Assoc 79(387):531-554.
Gel B, Serra E. 2017. karyoploteR: an R/Bioconductor package to plot customizable genomes. Bioinformatics 33(19):3088-3090.
Gu Z, Gu L, Eils R, Schlesner M, Brors B. 2014. circlize implements and enhances circular visualization in R. Bioinformatics 30(19):2811-2812.
Heer J, Bostock M. 2010. Crowdsourcing graphical perception: using Mechanical Turk to assess visualization design. Proc CHI 203-212.
Krzywinski M, Schein J, Birol I, et al. 2009. Circos: an information aesthetic for comparative genomics. Genome Res 19(9):1639-1645.
