Circos Plot Generator

Generate configuration files for Circos circular visualization plots, enabling genomics data visualization including genomic variations, chromosome ideograms, cell-cell communication networks, and custom track annotations. Simplifies the complex Circos configuration process for researchers without Perl expertise.

Key Capabilities:

- Genomic Variation Visualization: Create plots for SNPs, CNVs, structural variants (translocations, inversions)
Cell-Cell Communication Networks: Visualize intercellular interactions and signaling pathways
Chromosome Ideograms: Display chromosome structure with bands and annotations
Multiple Track Types: Support histograms, scatter plots, links, heatmaps, and text tracks
Publication-Ready Output: Generate configurations for high-quality PNG/SVG figures

When to Use

✅ Use this skill when:

- Visualizing genomic variations across chromosomes (SNPs, CNVs, SVs) for publication
Creating circular genome maps showing multiple data types simultaneously
Plotting cell-cell communication networks from single-cell RNA-seq data
Displaying synteny or chromosomal rearrangements between genomes
Creating circos plots for grant proposals, presentations, or papers
Generating custom track visualizations for genomic features
Comparing structural variants across multiple samples or conditions

❌ Do NOT use when:

- Needing interactive genome browsers (e.g., IGV, UCSC) → Use genome browser tools
Creating linear genome plots → Use cnv-caller-plotter or INLINECODE1
Analyzing time-series or trajectory data → Use trajectory analysis tools
Working with protein structures → Use PyMOL or ChimeraX
Requiring real-time data visualization → Use web-based dashboards
Making simple bar charts or line plots → Use matplotlib, ggplot2, or Excel

Related Skills:

- 上游 (Upstream): cnv-caller-plotter, crispr-screen-analyzer, INLINECODE4
下游 (Downstream): dpi-upscaler-checker, journal-cover-prompter, INLINECODE7

Integration with Other Skills

Upstream Skills:

- cnv-caller-plotter: Generate CNV calls for visualization in Circos
INLINECODE9: Prepare hit data for genomic context visualization
INLINECODE10: Map features to genomic coordinates for track display

Downstream Skills:

- dpi-upscaler-checker: Verify output resolution meets publication requirements
INLINECODE12: Generate AI prompts for journal covers using Circos plots
INLINECODE13: Create figure legends for complex Circos visualizations

Complete Workflow:

WGS Data → cnv-caller-plotter → circos-plot-generator → dpi-upscaler-checker → Publication Figure

Core Capabilities

1. Genomic Variation Track Generation

Create tracks for visualizing genomic variations including SNPs, CNVs, and structural variants.

CODEBLOCK1

Input Data Format:

Column	Description	Example
INLINECODE14	Chromosome name	chr1, chrX
INLINECODE15

Variation Types Supported:

Type	Visualization	Color Coding
SNP	Histogram points	Blue/Red (gain/loss)
CNV

Best Practices:

- ✅ Normalize values to -1 to +1 range for consistent scaling
✅ Use appropriate bin sizes (1-10 Mb) for genome-wide views
✅ Color code by type for easy interpretation
✅ Include ideogram for chromosome context

Common Issues and Solutions:

Issue: Too many data points causing clutter

- Symptom: Plot looks crowded with overlapping elements
Solution: Increase bin size; filter for significant variants only; use transparency

Issue: Chromosome naming mismatch

- Symptom: Data not appearing on correct chromosomes
Solution: Use consistent naming (chr1, chr2, ... chrX, chrY); check for "1" vs "chr1"

2. Cell-Cell Communication Visualization

Create circular plots showing interactions between cell types in tissues or tumors.

CODEBLOCK2

Input Format for Cell Communication:

Column	Description	Example
INLINECODE21	Source cell type	T_Cell
INLINECODE22

Visualization Features:

Feature	Description	Use Case
Ribbon links	Connection width ∝ interaction strength	Show communication intensity
Cell segments

Best Practices:

- ✅ Normalize weights to 0-1 scale for consistent ribbon sizing
✅ Group related cell types together in input file
✅ Use distinct colors for each cell type (max 8-10 for clarity)
✅ Filter weak interactions (weight < 0.2) to reduce clutter

Common Issues and Solutions:

Issue: Too many cell types causing confusion

- Symptom: Plot crowded with >10 cell types
Solution: Group rare cell types into "Other"; create separate plots for major groups

Issue: Bidirectional interactions not clear

- Symptom: Can't distinguish A→B from B→A
Solution: Use arrow indicators; color-code by direction; split into two plots

3. Chromosome Ideogram Configuration

Generate chromosome ideograms showing banding patterns and genomic coordinates.

CODEBLOCK3

Chromosome Specifications:

Chromosome	Size (bp)	Display Color
chr1	248,956,422	Red
chr2

242,193,529 | Orange |
| chr3 | 198,295,559 | Yellow |
| ... | ... | ... |
| chrX | 156,040,895 | Purple |
| chrY | 57,227,415 | Grey |

Ideogram Features:

Feature	Description	Configuration
Spacing	Gap between chromosomes	0.005r (0.5% of radius)
Thickness

Best Practices:

- ✅ Include all autosomes for genome-wide views
✅ Show X and Y for sex chromosome analysis
✅ Use consistent scaling across samples
✅ Add cytoband information for clinical relevance

Common Issues and Solutions:

Issue: Small chromosomes (chr21, chrY) hard to see

- Symptom: Very small segments for small chromosomes
Solution: Use non-linear scaling; create zoomed inset plots

Issue: Mitochondrial DNA not included

- Symptom: chrM variants not shown
Solution: Add chrM to CHROMOSOME_SIZES dict; or exclude mitochondrial from plot

4. Multiple Track Layering

Overlay multiple data tracks in concentric circles for complex visualizations.

CODEBLOCK4

Track Positioning:

Track	Radius Range	Typical Use
Outer 1	0.95r - 0.80r	Primary data (CNVs)
Outer 2

Track Types:

Type	Data Format	Best For
Histogram	chr start end value	Continuous values (CNVs, expression)
Scatter

Best Practices:

- ✅ Limit to 3-4 tracks for readability
✅ Use complementary colors for different data types
✅ Add track labels in figure legend
✅ Consider track order - most important data outermost

Common Issues and Solutions:

Issue: Tracks overlapping

- Symptom: Data from different tracks hard to distinguish
Solution: Adjust radius ranges; use different track types; add transparency

Issue: Scale differences between tracks

- Symptom: One track dominates visualization
Solution: Normalize each track to 0-1 range; use separate color scales

5. Color Scheme Customization

Select from predefined color schemes or define custom colors for publication consistency.

CODEBLOCK5

Color Schemes:

Scheme	Style	Best For
default	Basic colors	Quick visualization, drafts
nature

Custom Colors:
CODEBLOCK6

Best Practices:

- ✅ Use colorblind-friendly palettes for accessibility
✅ Match journal requirements for submissions
✅ Maintain consistency across all figures in paper
✅ Test printed output - colors may differ from screen

Common Issues and Solutions:

Issue: Colors not distinct enough

- Symptom: Hard to distinguish adjacent tracks
Solution: Increase color contrast; use complementary colors

Issue: Colors don't match brand/institution

- Symptom: Need specific institutional colors
Solution: Define custom color scheme with hex codes

6. Configuration Export and Rendering

Generate complete Circos configuration and optionally render the plot.

CODEBLOCK7

Output Files:

File	Description	Format
INLINECODE25	Main configuration	Text
INLINECODE26

Chromosome definitions | Text |
| data/*.txt | Track data files | TSV |
| circos.png | Raster image (if rendered) | PNG |
| circos.svg | Vector image (if rendered) | SVG |

Rendering Requirements:

Component	Installation	Command
Circos	INLINECODE30	INLINECODE31
Perl

Best Practices:

- ✅ Generate SVG for publication - scalable, editable
✅ Use PNG for drafts - faster rendering
✅ Check file sizes - high-res images can be large
✅ Archive configurations - for reproducibility

Common Issues and Solutions:

Issue: Circos installation fails

- Symptom: "circos: command not found"
Solution: Use conda installation; check Perl and GD dependencies

Issue: Rendering produces warnings

- Symptom: Many "skip" or "warning" messages
Solution: Usually harmless; check output image quality; adjust data ranges

Complete Workflow Example

From variant calls to publication figure:

CODEBLOCK8

Python API Usage:

CODEBLOCK9

Expected Output Files:

CODEBLOCK10

Common Patterns

Pattern 1: Cancer Genomic Landscape

Scenario: Visualize genomic alterations in a tumor sample for publication.

CODEBLOCK11

Workflow:

1. Collect CNV data from WGS or SNP array
Get SNV calls from exome/WGS
Identify structural variants (SVs)
Generate Circos configuration
Render and export high-resolution PNG/SVG
Create figure legend and methods description

Output Example:
CODEBLOCK12

Pattern 2: Tumor Microenvironment

Scenario: Visualize cell-cell communication in tumor microenvironment.

CODEBLOCK13

Workflow:

1. Run CellChat or similar on scRNA-seq data
Export communication probabilities
Filter for significant interactions
Generate Circos configuration
Adjust colors for each cell type
Add annotations for key pathways

Output Example:
CODEBLOCK14

Pattern 3: Comparative Genomics

Scenario: Compare synteny between two species or strains.

CODEBLOCK15

Workflow:

1. Identify syntenic blocks between genomes
Map coordinates to common reference
Create link track for conserved regions
Generate dual-genome Circos plot
Color-code by chromosome of origin
Highlight breakpoints and rearrangements

Output Example:
CODEBLOCK16

Pattern 4: Time-Series Evolution

Scenario: Track clonal evolution through treatment timepoints.

CODEBLOCK17

Workflow:

1. Collect CNV data from multiple timepoints
Track clone frequencies
Create separate track for each timepoint
Add links showing clone relationships
Generate evolution Circos plot
Annotate treatment events

Output Example:

Clonal Evolution Plot:
  Timepoints: 3
  Clones tracked: 5
  
Evolutionary trajectory:
  - Baseline: 3 subclones
  - Post-treatment: 1 dominant clone
  - Relapse: New clone emergence
  
Therapeutic implications:
  - Pre-existing resistance clone expanded
  - New mutation acquired at relapse

Quality Checklist

Data Preparation:

- [ ] CRITICAL: Verify chromosome naming consistency (chr1 vs 1)
[ ] Check coordinate system (0-based vs 1-based)
[ ] Validate all positions within chromosome bounds
[ ] Normalize values to appropriate ranges
[ ] Filter out low-quality or ambiguous data
[ ] Ensure no duplicate entries
[ ] Check for missing values and handle appropriately
[ ] Verify file formats (CSV with proper headers)

Configuration:

- [ ] CRITICAL: Set appropriate image size for publication (min 1200x1200)
[ ] Choose color scheme matching journal requirements
[ ] Set track radii to avoid overlap
[ ] Configure chromosome spacing for readability
[ ] Add descriptive title
[ ] Set up proper scaling for each track
[ ] Choose appropriate color for each data type
[ ] Test with subset of data first

Rendering:

- [ ] CRITICAL: Generate SVG for publication-quality output
[ ] Check PNG output for visual quality
[ ] Verify all tracks visible and correctly positioned
[ ] Test color visibility (colorblind-friendly check)
[ ] Confirm labels readable at target size
[ ] Check for rendering warnings or errors
[ ] Verify file sizes reasonable
[ ] Archive configuration files

Publication:

- [ ] CRITICAL: Include scale bars and legends
[ ] Add chromosome labels clearly
[ ] Include figure caption with data description
[ ] Note software version in methods
[ ] Provide data availability statement
[ ] Check journal figure requirements (size, format)
[ ] Create supplementary data files if needed
[ ] Test figure at print resolution

Common Pitfalls

Data Issues:

- ❌ Inconsistent chromosome names → Data missing from plot

- ✅ Use consistent "chr" prefix (chr1, chr2, not 1, 2)

- ❌ Coordinates out of bounds → Rendering errors

- ✅ Verify all coordinates ≤ chromosome size

- ❌ Too many data points → Cluttered, slow rendering

- ✅ Filter for significance; increase bin size

- ❌ Missing values not handled → Gaps or errors

- ✅ Impute or filter missing values before plotting

Configuration Issues:

- ❌ Tracks overlap → Data unreadable

- ✅ Adjust radius ranges; use transparency

- ❌ Colors too similar → Can't distinguish tracks

- ✅ Use distinct, contrasting colors

- ❌ Font too small → Labels unreadable

- ✅ Increase font sizes for publication

- ❌ Image too small → Poor resolution

- ✅ Use minimum 1200x1200 for publications

Interpretation Issues:

- ❌ No scale reference → Values unclear

- ✅ Add color scale and value ranges

- ❌ Missing legend → Data types unexplained

- ✅ Include comprehensive figure legend

- ❌ No chromosome labels → Location unclear

- ✅ Label all chromosomes clearly

- ❌ Too much information → Figure overwhelming

- ✅ Limit to 3-4 key data types per plot

Troubleshooting

Problem: Configuration generates but Circos won't render

- Symptoms: "Can't open file" or "Invalid configuration" errors
Causes:

- Missing data files
- Incorrect file paths
- Syntax errors in configuration
- Missing Circos installation

- Solutions:

- Verify all data files exist in data/ directory
- Check file paths are absolute or correct relative paths
- Validate configuration syntax
- Install Circos: INLINECODE32

Problem: Plot is blank or missing data

- Symptoms: Chromosomes shown but no data tracks
Causes:

- Data format incorrect
- Chromosome name mismatch
- Values out of visible range

- Solutions:

- Check data format matches expected (TSV, correct columns)
- Verify chromosome names (chr1 vs 1)
- Check min/max values in data files

Problem: Colors not as expected

- Symptoms: Wrong colors or all same color
Causes:

- Color scheme name misspelled
- Custom colors not defined
- Color values out of range

- Solutions:

- Check color_scheme name matches available schemes
- Define custom colors if needed
- Verify color values are valid hex codes

Problem: Links/connections not showing

- Symptoms: Histograms visible but no SV links
Causes:

- Link data format incorrect
- Target coordinates missing
- Link radius outside visible area

- Solutions:

- Check link file format: chr1 start1 end1 chr2 start2 end2
- Verify target coordinates provided for translocations
- Adjust link radius parameter

Problem: Text labels overlapping

- Symptoms: Gene names or labels unreadable
Causes:

- Too many labels in small space
- Font size too large
- Insufficient label radius

- Solutions:

- Filter labels to show only most important
- Reduce font size
- Increase label radius (move further from center)
- Use label collision detection if available

Problem: Rendering is very slow

- Symptoms: Takes minutes or hours to generate plot
Causes:

- Too many data points
- High resolution settings
- Complex link calculations

- Solutions:

- Reduce data points (filter or bin)
- Lower image resolution for drafts
- Simplify link visualization
- Use PNG instead of SVG for faster rendering

References

Available in references/ directory:

- (No reference files currently available for this skill)

External Resources:

- Circos Official Documentation: http://circos.ca/documentation
Circos Tutorials: http://circos.ca/documentation/tutorials
Bioconda Circos: https://bioconda.github.io/recipes/circos/README.html
Nature Genetics Circos Examples: https://www.nature.com/ng/

Scripts

Located in scripts/ directory:

- main.py - Circos configuration generator with support for variations and cell communication

Color Scheme Reference

Default: red, blue, green, orange, purple, cyan

Nature: #E64B35, #4DBBD5, #00A087, #3C5488, #F39B7F, #8491B4

Lancet: #00468B, #ED0000, #42B540, #0099B4, #925E9F, #FDAF91

Cell: #1B9E77, #D95F02, #7570B3, #E7298A, #66A61E, #E6AB02

Parameters

Parameter	Type	Default	Required	Description
INLINECODE36	string	-	Yes	Input data file (TSV/CSV format)
INLINECODE37, INLINECODE38

Usage

Basic Usage

CODEBLOCK19

Input Data Format

Variation data (TSV format):
CODEBLOCK20

Cell communication data (TSV format):
CODEBLOCK21

Risk Assessment

Risk Indicator	Assessment	Level
Code Execution	Python script executed locally	Low
Network Access

Security Checklist

- [x] No hardcoded credentials or API keys
[x] No unauthorized file system access
[x] Input validation for file paths
[x] Output directory restricted
[x] Error messages sanitized
[x] Script execution in sandboxed environment
[x] No network connections

Prerequisites

CODEBLOCK22

Evaluation Criteria

Success Metrics

- [x] Successfully generates Circos configuration
[x] Creates valid SVG output files
[x] Supports multiple color schemes
[x] Handles both variation and cell communication data

Test Cases

1. Variation Plot: Genomic data → Circular genome visualization
Cell Communication: Interaction matrix → Cell-type network diagram
Custom Colors: Data + color scheme → Styled visualization

Lifecycle Status

- Current Stage: Active
Next Review Date: 2026-03-09
Known Issues: None
Planned Improvements:

- Add more plot types (methylation, expression) - Support for interactive HTML output - Integration with common genomic formats (VCF, BED)

Last Updated: 2026-02-09 Skill ID: 186 Version: 2.0 (K-Dense Standard)

Circos 图生成器

为Circos圆形可视化图生成配置文件，实现基因组学数据可视化，包括基因组变异、染色体核型图、细胞间通信网络和自定义轨道注释。简化复杂的Circos配置过程，使不具备Perl专业知识的研究人员也能使用。

关键能力：

- 基因组变异可视化：创建SNP、CNV、结构变异（易位、倒位）的图形
细胞间通信网络：可视化细胞间相互作用和信号通路
染色体核型图：显示带有条带和注释的染色体结构
多种轨道类型：支持直方图、散点图、连接线、热图和文本轨道
可发表输出：生成高质量PNG/SVG图形的配置

何时使用

✅ 使用此技能的场景：

- 可视化跨染色体的基因组变异（SNP、CNV、SV）用于发表
创建同时显示多种数据类型的环形基因组图谱
绘制来自单细胞RNA-seq数据的细胞间通信网络
显示基因组间的共线性或染色体重排
为基金申请、演示或论文创建Circos图
为基因组特征生成自定义轨道可视化
比较多个样本或条件下的结构变异

❌ 不要使用的场景：

- 需要交互式基因组浏览器（如IGV、UCSC）→ 使用基因组浏览器工具
创建线性基因组图 → 使用cnv-caller-plotter或gene-structure-mapper
分析时间序列或轨迹数据 → 使用轨迹分析工具
处理蛋白质结构 → 使用PyMOL或ChimeraX
需要实时数据可视化 → 使用基于Web的仪表板
制作简单的柱状图或折线图 → 使用matplotlib、ggplot2或Excel

相关技能：

- 上游：cnv-caller-plotter、crispr-screen-analyzer、bio-ontology-mapper
下游：dpi-upscaler-checker、journal-cover-prompter、figure-legend-gen

与其他技能的集成

上游技能：

- cnv-caller-plotter：生成用于Circos可视化的CNV调用
crispr-screen-analyzer：准备用于基因组背景可视化的命中数据
bio-ontology-mapper：将特征映射到基因组坐标用于轨道显示

下游技能：

- dpi-upscaler-checker：验证输出分辨率是否满足发表要求
journal-cover-prompter：使用Circos图为期刊封面生成AI提示
figure-legend-gen：为复杂的Circos可视化创建图例

完整工作流程：

WGS数据 → cnv-caller-plotter → circos-plot-generator → dpi-upscaler-checker → 发表图

核心能力

1. 基因组变异轨道生成

创建用于可视化基因组变异的轨道，包括SNP、CNV和结构变异。

python
from scripts.main import CircosConfig

基因组变异图的配置

config = { type: variation, title: 样本基因组变异, data: variations.csv, width: 1200, height: 1200, color_scheme: nature, output: ./circos_output }

生成配置

generator = CircosConfig(config) config_path = generator.generate()

print(f配置已生成：{config_path})
print(f包含的轨道：)
print( - SNP/CNV的直方图轨道)
print( - 结构变异的连接线轨道)
print( - 染色体核型图)

输入数据格式：

列名	描述	示例
chrom	染色体名称	chr1, chrX
start

支持的变异类型：

类型	可视化方式	颜色编码
SNP	直方图点	蓝色/红色（获得/丢失）
CNV

直方图条 | 绿色/橙色（扩增/缺失） |
| 易位 | 染色体间连接线 | 紫色带 |
| 倒位 | 染色体内连接线 | 黄色 |
| 缺失 | 直方图条 | 红色 |
| 重复 | 直方图条 | 蓝色 |

最佳实践：

- ✅ 将值归一化到-1到+1范围以实现一致的比例
✅ 使用适当的区间大小（1-10 Mb）用于全基因组视图
✅ 按类型进行颜色编码以便于解释
✅ 包含核型图以提供染色体背景

常见问题及解决方案：

问题：数据点过多导致杂乱

- 症状：图形看起来拥挤，元素重叠
解决方案：增加区间大小；仅筛选显著变异；使用透明度

问题：染色体命名不匹配

- 症状：数据未出现在正确的染色体上
解决方案：使用一致的命名（chr1, chr2, ... chrX, chrY）；检查1与chr1

2. 细胞间通信可视化

创建显示组织或肿瘤中细胞类型间相互作用的圆形图。

python
from scripts.main import CircosConfig

细胞间通信的配置

config = { type: cell-comm, title: 肿瘤微环境相互作用, data: cell_communication.csv, width: 1000, height: 1000, color_scheme: cell, output: ./cellcommplots }

generator = CircosConfig(config)
config_path = generator.generate()

print(细胞间通信图已配置：)
print( - 细胞类型排列在圆上)
print( - 连接带显示相互作用)
print( - 每种细胞类型的标签)

细胞通信的输入格式：

列名	描述	示例
source	源细胞类型	T_Cell
target

可视化特征：

特征	描述	用例
带状连接线	连接宽度 ∝ 相互作用强度	显示通信强度
细胞片段

最佳实践：

- ✅ 将权重归一化到0-1范围以实现一致的带状大小
✅ 在输入文件中将相关细胞类型分组在一起
✅ 为每种细胞类型使用独特的颜色（最多8-10种以保持清晰）
✅ 过滤弱相互作用（权重 < 0.2）以减少杂乱

常见问题及解决方案：

问题：细胞类型过多导致混乱

- 症状：图形拥挤，超过10种细胞类型
解决方案：将稀有细胞类型分组为其他；为主要组创建单独的图

问题：双向相互作用不清晰

- 症状：无法区分A→B和B→A
解决方案：使用箭头指示符；按方向进行颜色编码；分成两个图

3. 染色体核型图配置

生成显示带型模式和基因组坐标的染色体核型图。

python
from scripts.main import CircosConfig, CHROMOSOME_SIZES

查看可用的染色体

print(可用染色体（GRCh38/hg38）：) for chrom, size in CHROMOSOME_SIZES.items(): sizemb = size / 1000_000 print(f {chrom}: {size_mb:.1f} Mb)

自定义染色体选择

config = { type: variation, title: Chr1-5变异, chromosomes: [chr1, chr2, chr3, chr4, chr5], # 子集 width: 1000, height: 1000, output: ./chr1-5_plots

circos-plot-generatorCircos图生成器