Circos Plot Generator

**Output Files:**

| File | Description | Format |
|------|-------------|--------|
| `circos.conf` | Main configuration | Text |
| `data/karyotype.txt` | 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** | `conda install -c bioconda circos` | `circos -conf circos.conf` |
| **Perl** | Usually pre-installed | Required by Circos |
| **GD library** | System package | Image generation |

**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

---

## Implementation Details

See `## Workflow` above for related details.

- Execution model: validate the request, choose the packaged workflow, and produce a bounded deliverable.
- Input controls: confirm the source files, scope limits, output format, and acceptance criteria before running any script.
- Primary implementation surface: `scripts/main.py`.
- Reference guidance: `references/` contains supporting rules, prompts, or checklists.
- Parameters to clarify first: input path, output path, scope filters, thresholds, and any domain-specific constraints.
- Output discipline: keep results reproducible, identify assumptions explicitly, and avoid undocumented side effects.

## Quick Check

Use this command to verify that the packaged script entry point can be parsed before deeper execution.

```bash
python -m py_compile scripts/main.py

python -m py_compile scripts/main.py
python scripts/main.py --help

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

from scripts.main import CircosConfig

# Configuration for genomic variation plot
config = {
    "type": "variation",
    "title": "Sample Genomic Variations",
    "data": "variations.csv",
    "width": 1200,
    "height": 1200,
    "color_scheme": "nature",
    "output": "./circos_output"
}

# Generate configuration
generator = CircosConfig(config)
config_path = generator.generate()

print(f"Configuration generated: {config_path}")
print(f"Tracks included:")
print("  - Histogram track for SNPs/CNVs")
print("  - Link track for structural variants")
print("  - Chromosome ideogram")

from scripts.main import CircosConfig

# Configuration for cell-cell communication
config = {
    "type": "cell-comm",
    "title": "Tumor Microenvironment Interactions",
    "data": "cell_communication.csv",
    "width": 1000,
    "height": 1000,
    "color_scheme": "cell",
    "output": "./cell_comm_plots"
}

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

print("Cell-cell communication plot configured:")
print("  - Cell types arranged in circle")
print("  - Connection ribbons showing interactions")
print("  - Labels for each cell type")

from scripts.main import CircosConfig, CHROMOSOME_SIZES

# View available chromosomes
print("Available chromosomes (GRCh38/hg38):")
for chrom, size in CHROMOSOME_SIZES.items():
    size_mb = size / 1_000_000
    print(f"  {chrom}: {size_mb:.1f} Mb")

# Custom chromosome selection
config = {
    "type": "variation",
    "title": "Chr1-5 Variations",
    "chromosomes": ["chr1", "chr2", "chr3", "chr4", "chr5"],  # Subset
    "width": 1000,
    "height": 1000,
    "output": "./chr1-5_plots"
}

# Note: Chromosome selection handled in data preprocessing

from scripts.main import CircosConfig

# Multi-track configuration
config = {
    "type": "custom",
    "title": "Multi-Track Genome View",
    "width": 1200,
    "height": 1200,
    "tracks": [
        {
            "type": "histogram",
            "file": "data/cnv_track.txt",
            "color": "color0"  # Red
        },
        {
            "type": "histogram", 
            "file": "data/snp_track.txt",
            "color": "color1"  # Blue
        },
        {
            "type": "link",
            "file": "data/sv_links.txt",
            "color": "color2"  # Green
        }
    ],
    "output": "./multi_track"
}

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

from scripts.main import CircosConfig, COLOR_SCHEMES

# View available color schemes
print("Available color schemes:")
for name, colors in COLOR_SCHEMES.items():
    print(f"\n{name.upper()}:")
    print(f"  Colors: {', '.join(colors[:4])}...")

# Example outputs for each scheme
scheme_examples = {
    "default": ["red", "blue", "green", "orange"],
    "nature": ["#E64B35", "#4DBBD5", "#00A087", "#3C5488"],
    "lancet": ["#00468B", "#ED0000", "#42B540", "#0099B4"],
    "cell": ["#1B9E77", "#D95F02", "#7570B3", "#E7298A"]
}

# Usage
config = {
    "type": "variation",
    "color_scheme": "nature",  # Publication-quality colors
    # ... other config
}

# Define custom scheme
my_colors = ["#FF6B6B", "#4ECDC4", "#45B7D1", "#96CEB4", "#FFEAA7"]
COLOR_SCHEMES["custom"] = my_colors

config["color_scheme"] = "custom"

import subprocess
from pathlib import Path
from scripts.main import CircosConfig

def generate_and_render(config: dict, render: bool = False) -> dict:
    """
    Generate Circos config and optionally render plot.
    
    Returns:
        dict with paths and status
    """
    # Generate configuration
    generator = CircosConfig(config)
    config_path = generator.generate()
    
    result = {
        "config_path": config_path,
        "data_dir": str(generator.data_dir),
        "rendered": False,
        "output_image": None
    }
    
    # Attempt to render
    if render:
        output_dir = Path(config["output"])
        try:
            proc_result = subprocess.run(
                ["circos", "-conf", config_path],
                capture_output=True,
                text=True,
                cwd=output_dir
            )
            
            if proc_result.returncode == 0:
                result["rendered"] = True
                result["output_image"] = str(output_dir / "circos.png")
                print("✅ Plot rendered successfully!")
            else:
                print(f"❌ Rendering failed: {proc_result.stderr}")
        except FileNotFoundError:
            print("⚠️  Circos not installed. Configuration ready for manual rendering.")
            print(f"   Run: cd {output_dir} && circos -conf circos.conf")
    
    return result

## Complete Workflow Example

**From variant calls to publication figure:**

```text

# Step 1: Create sample data for testing
python scripts/main.py --create-sample variation --output ./data

# Step 2: Generate configuration
python scripts/main.py \
  --data ./data/sample_variations.csv \
  --type variation \
  --title "Tumor Genomic Landscape" \
  --color-scheme nature \
  --width 1200 \
  --height 1200 \
  --output ./plots

# Step 3: Render plot (requires Circos)
python scripts/main.py \
  --data ./data/sample_variations.csv \
  --type variation \
  --output ./plots \
  --render

from scripts.main import CircosConfig
import pandas as pd

def create_genomic_landscape_plot(
    variation_data: pd.DataFrame,
    output_dir: str = "./circos_output",
    title: str = "Genomic Variations"
) -> str:
    """
    Create comprehensive genomic landscape Circos plot.
    
    Args:
        variation_data: DataFrame with columns [chrom, start, end, type, value]
        output_dir: Output directory for files
        title: Plot title
        
    Returns:
        Path to generated configuration file
    """
    # Save data to CSV
    data_path = f"{output_dir}/input_data.csv"
    variation_data.to_csv(data_path, index=False)
    
    # Generate configuration
    config = {
        "type": "variation",
        "title": title,
        "data": data_path,
        "width": 1200,
        "height": 1200,
        "color_scheme": "nature",
        "output": output_dir
    }
    
    generator = CircosConfig(config)
    config_path = generator.generate()
    
    # Print summary
    print(f"✅ Circos configuration generated")
    print(f"   Config: {config_path}")
    print(f"   Data directory: {generator.data_dir}")
    print(f"\nTo render:")
    print(f"   circos -conf {config_path}")
    
    return config_path

# Example with sample data
sample_data = pd.DataFrame({
    'chrom': ['chr1', 'chr1', 'chr2', 'chr5', 'chrX'],
    'start': [1000000, 5000000, 1000000, 5000000, 5000000],
    'end': [2000000, 6000000, 1500000, 7000000, 8000000],
    'type': ['SNP', 'CNV', 'SNP', 'TRANSLOCATION', 'DELETION'],
    'value': [0.5, -0.8, 0.3, None, -1.0],
    'target_chrom': [None, None, None, 'chr2', None],
    'target_start': [None, None, None, 8000000, None],
    'target_end': [None, None, None, 10000000, None]
})

config_file = create_genomic_landscape_plot(
    sample_data,
    output_dir="./my_plot",
    title="Sample Genomic Landscape"
)

circos_output/
├── circos.conf              # Main configuration
├── data/
│   ├── karyotype.txt        # Chromosome definitions
│   ├── variations.txt       # Histogram data
│   └── links.txt            # Structural variant links
└── (after rendering)
    ├── circos.png           # Raster output
    └── circos.svg           # Vector output

{
  "plot_type": "variation",
  "title": "Tumor Genomic Landscape",
  "data_layers": [
    "CNV (outer track)",
    "SNV density (middle track)",
    "Structural variants (links)"
  ],
  "color_scheme": "nature",
  "resolution": "1200x1200",
  "publication": "Nature Medicine"
}

Cancer Genomic Landscape Plot:
  - CNV track: 47 copy number alterations
  - SNV track: 2,847 mutations (density)
  - SV links: 12 translocations, 8 inversions
  
Key findings visible:
  - Chr8 MYC amplification
  - Chr17 TP53 deletion
  - Chr7-14 translocation
  
Publication ready: 1200x1200 PNG + SVG

{
  "plot_type": "cell-comm",
  "title": "TME Communication Network",
  "cell_types": [
    "T_Cell", "B_Cell", "Macrophage",
    "NK_Cell", "Tumor_Cell", "Fibroblast"
  ],
  "data_source": "CellChat analysis",
  "filter": "weight > 0.3",
  "color_scheme": "cell"
}

TME Communication Network:
  Cell types: 6
  Interactions: 24 (filtered from 156)
  
Major communication axes:
  - T_Cell → Macrophage (strongest)
  - Dendritic → T_Cell
  - Tumor → Macrophage
  
Insights:
  - Immunosuppressive signaling dominant
  - Limited NK cell activation

{
  "plot_type": "custom",
  "title": "Human-Mouse Synteny",
  "tracks": [
    {
      "type": "link",
      "data": "synteny_blocks.txt",
      "description": "Conserved regions"
    }
  ],
  "genomes": ["hg38", "mm10"],
  "color_by": "chromosome"
}

Synteny Comparison:
  Human chromosomes: 22 + X + Y
  Mouse chromosomes: 19 + X + Y
  Syntenic blocks: 342
  
Key observations:
  - Chr12 conservation strong
  - Multiple breakpoints on Chr1
  - X chromosome largely conserved

{
  "plot_type": "custom",
  "title": "Clonal Evolution Over Time",
  "timepoints": ["Baseline", "Post-Treatment", "Relapse"],
  "tracks": [
    "Baseline CNV",
    "Post-Treatment CNV",
    "Relapse CNV",
    "Clonal links"
  ],
  "color_scheme": "lancet"
}

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