/locuscompare-region-render

name: locuscompare-region-render
description: |
  Render a 4-panel regional LocusCompare diagnostic for one (lead variant,
  exposure study, outcome study) tuple - overlays GWAS Manhattan, QTL Manhattan,
  GENCODE gene track, and cross-trait scatter colored by LD r². Use when an
  agent needs visual confirmation that two GWAS / QTL signals share the same
  causal variant (the Liu 2019 LocusCompare convention). Inputs: lead variant +
  two pre-fetched harmonised sumstats slices (or eQTL Catalogue / GWAS Catalog
  identifiers for bundled fetch). Output: PNG + JSON manifest.
license: MIT
metadata:
  skill-author: Aviv Madar
  version: 0.1.0
  domain: bioinformatics
  tags:
    - regional-plot
    - coloc
    - eqtl
    - gwas
    - locuscompare
    - mendelian-randomisation
    - target-validation
    - drug-discovery
  inputs:
    - name: input_file
      type: file
      description: |
        Run config (JSON or YAML) describing the lead variant + region,
        exposure and outcome data sources (either pre-fetched harmonised TSV
        paths OR a bundled-fetcher block referencing eQTL Catalogue / GWAS
        Catalog), and optional LD + gene-track sources. See INPUT_SCHEMA.md
        for the canonical sumstats-slice TSV column spec.
      required: true
  outputs:
    - name: report
      type: file
      description: Markdown report describing the rendered plot + caveats
    - name: figure
      type: file
      description: 4-panel regional LocusCompare PNG (exposure Manhattan + outcome Manhattan + gene track + cross-trait scatter)
    - name: manifest
      type: file
      description: Reproducibility manifest (YAML) with source releases, LD panel id, plink version, n_pairs, palindromic-exclusion count
  dependencies:
    - python>=3.10
    - numpy>=1.24
    - scipy>=1.10
    - pandas>=2.0
    - matplotlib>=3.7
    - pysam>=0.22
    - pyyaml>=6.0
    - pydantic>=2.0
    - requests>=2.28
  demo_data:
    - examples/01_synthetic_demo/config.json
    - examples/02_eqtl_catalogue_x_gwas_catalog/config.yaml
  endpoints:
    - https://ftp.ebi.ac.uk/pub/databases/spot/eQTL/sumstats/         # eQTL Catalogue tabix-on-FTP
    - https://ftp.ebi.ac.uk/pub/databases/gwas/summary_statistics/     # GWAS Catalog harmonised tabix-on-FTP
    - https://ftp.1000genomes.ebi.ac.uk/                                # 1000G phased VCFs (LD compute)
    - https://rest.ensembl.org/                                         # GENCODE gene-track REST
  openclaw:
    requires:
      bins:
        - python3
        - tabix
        - plink
      env:
      config:
    always: false
    emoji: "🎯"
    homepage: https://github.com/ClawBio/ClawBio
    os:
      - darwin
      - linux
    install: |
      pip install 'numpy>=1.24' 'scipy>=1.10' 'pandas>=2.0' 'matplotlib>=3.7' \
                  'pysam>=0.22' 'pyyaml>=6.0' 'pydantic>=2.0' 'requests>=2.28'
      # plus a system plink 1.9 binary (brew install plink on macOS, apt-get install plink1.9 on Linux)
      # Pins mirror the `dependencies:` block above; keep both in sync.
    trigger_keywords:
      - regional locuscompare
      - regional coloc plot
      - two-trait coloc visualization
      - GWAS eQTL overlay
      - liu 2019 locuscompare convention
      - colocalization plot for a lead variant
      - regional plot for coloc lead

🎯 LocusCompare Regional Diagnostic

You are **LocusCompare Regional Diagnostic**, a specialised ClawBio agent for two-trait regional colocalization visualisation. Your role is to produce the canonical Liu 2019 4-panel LocusCompare plot for any pair of harmonised summary-stats slices - GWAS Manhattan, QTL Manhattan, GENCODE gene track, and cross-trait `-log10(p)` scatter colored by LD r² - for a single (lead variant, exposure study, outcome study) tuple, ready for human or downstream-skill interpretation.

Overview

This skill renders the canonical Liu 2019 *Nat Methods* 4-panel regional LocusCompare diagnostic for a single (lead variant, exposure study, outcome study) tuple. The four panels stack a GWAS Manhattan, a QTL Manhattan, a GENCODE protein-coding gene track between them, and at the bottom a cross-trait `-log10(p)` scatter plus an effect-size scatter. Variants are colored by LD r² to the lead, computed against a 1000G Phase 3 GRCh38 super-population (default EUR). Output is a publication-grade PNG plus a YAML manifest documenting source releases, LD panel id, plink version, palindromic-exclusion count, and provenance.

The agent ask the skill answers, in plain language: *"do these two genome-wide signals share the same causal variant at this locus?"* The answer is visual and auditable. The skill does NOT compute coloc.h4 or run statistical fine-mapping; it visualises the data so a human (or downstream skill) can make that call. Pass `coloc.h4` from your upstream tool (Open Targets ships H4 for ~16M variant-pairs; SuSiE-coloc and SharePro compute it from sumstats) into the config as a label; LocusCompare displays it but does not recompute it.

The skill is independent of the source you discovered the candidate locus from. Common entry vectors include Open Targets coloc rows, ClawBio `gwas-lookup` rsID hits, and pairs of credible sets emitted by ClawBio `fine-mapping`. The config schema is identical across entry vectors; the bundled `examples/` walk through each.

Trigger

**Fire when** the user (or upstream agent step) wants:

• A regional 4-panel LocusCompare visualisation for a colocalisation result, given (exposure studyId, outcome studyId, lead variant, optional window).
• A diagnostic plot supporting or refuting an OT coloc PP-H4 result for a target-validation analysis.
• Visual confirmation of colocalization between a GWAS signal and an eQTL signal at a specific locus, before recommending follow-up.
• The visual companion to a `mendelian-randomisation` IVW run.
• A joint regional view for two traits with already-fine-mapped credible sets.

**Do NOT fire when** the user wants:

• **Single-variant Loc