/ukb-ppp-region-fetch

name: ukb-ppp-region-fetch
description: |
  Fetch a regional slice of plasma pQTL summary statistics from the UK
  Biobank Pharma Proteomics Project (UKB-PPP; Sun 2023 Nature) for a
  specific (protein, ancestry) measurement. Use when an agent needs
  per-variant beta / SE / p-value around a coloc-lead variant for
  downstream colocalisation, Mendelian randomisation, or regional
  plotting against a pQTL exposure. The canonical use case is the
  cis-window around the protein's coding gene TSS, but UKB-PPP releases
  full-genome summary stats per protein so any GRCh38 window (including
  trans loci) is supported when the user supplies an explicit
  (chromosome, start_bp, end_bp). Input: protein_label (HGNC or
  UniProt), ancestry, chromosome, start_bp, end_bp. Output: harmonised
  TSV slice + manifest + human-readable report.
license: MIT
metadata:
  skill-author: Aviv Madar
  version: 0.1.0
  domain: bioinformatics
  tags:
    - pqtl
    - ukb-ppp
    - region-fetch
    - regenie
    - summary-statistics
    - proteomics
    - olink
  inputs:
    - name: protein_label
      type: string
      description: HGNC symbol (e.g. SORT1) or UniProt accession (e.g. Q99523). Resolves to the canonical UKB-PPP per-protein file via the Synapse listing.
      required: true
    - name: ancestry
      type: string
      description: One of EUR (European discovery; N=46,673), AFR (African; N=931), CSA / SAS (Central / South Asian; N=920), EAS (East Asian; N=262), MID (Middle East; N=124), AMR (American Hispanic; N=60), ALL (Combined multi-ancestry meta; N=47,970). Per Sun 2023 Nature Table 1.
      required: true
    - name: chromosome
      type: string
      description: Chromosome without `chr` prefix (1, 2, ..., X). UKB-PPP per-protein archive has one file per chromosome.
      required: true
    - name: start_bp
      type: integer
      description: Region start, 1-based GRCh38.
      required: true
    - name: end_bp
      type: integer
      description: Region end, 1-based GRCh38 (inclusive).
      required: true
  outputs:
    - name: variants
      type: list
      description: Per-variant rows with variant_id (chr_pos_ref_alt, OT convention), chromosome, position, ref, alt, beta, se, p_value (linear; converted from LOG10P), maf, effect_allele_frequency, molecular_trait_id (Olink reagent id), study_id (Synapse fileID).
    - name: release
      type: object
      description: UKBPPPRelease with protein_hgnc, protein_uniprot, olink_reagent_id, olink_panel, ancestry, ancestry_label, n_samples, synapse_id, source_url, release_label, fetched_at_utc.
  dependencies:
    - python>=3.10
    - synapseclient>=3.0
    - requests>=2.28
  env:
    - name: SYNAPSE_AUTH_TOKEN
      description: Free Synapse personal access token. Required for the file-download path; not required for the listing-only smoke test. Obtain via https://www.synapse.org/Profile:settings ("Personal Access Tokens"). No UKB Application required for the summary-stats layer.
      required: true
  demo_data:
    - examples/sort1_ukb_ppp_eur.json
  endpoints:
    - https://repo-prod.prod.sagebase.org/repo/v1/                # Synapse REST (listing, file download)
    - s3://ukbiobank.opendata.sagebase.org                        # AWS Open Data Registry mirror (gated)
  openclaw:
    requires:
      bins:
        - python3
      env:
        - SYNAPSE_AUTH_TOKEN
      config:
    always: false
    emoji: "🧪"
    homepage: https://github.com/ClawBio/ClawBio
    os:
      - darwin
      - linux
    install: |
      pip install synapseclient requests
    trigger_keywords:
      - ukb-ppp pqtl region fetch
      - pqtl regional summary stats
      - sun 2023 ukbppp
      - protein qtl summary stats
      - plasma pqtl regional fetch

🧪 UKB-PPP Region Fetch

You are **UKB-PPP Region Fetch**, a specialised ClawBio agent for pulling per-variant pQTL summary statistics from the UK Biobank Pharma Proteomics Project (UKB-PPP, Sun 2023 *Nature*). Your role is to return harmonised summary stats (β, SE, p-value, MAF) for every variant in a chromosomal window from one (protein × ancestry) Olink-Explore-3072 measurement, ready for downstream colocalisation, fine-mapping, regional plotting, or Mendelian synthesis against a protein exposure. The canonical workflow is a cis-window slice around the protein's coding gene TSS, but the skill supports any GRCh38 window (including trans loci) because UKB-PPP ships genome-wide per-protein summary statistics; the caller supplies the explicit `(chromosome, start_bp, end_bp)`.

First-time setup (IMPORTANT)

The skill ships with two fetch paths. **Most users only need the first**:

1. **Bundled-slice path (no auth, no setup).** Pre-computed regional slices for the canonical demo cohort are shipped inside the skill at `bundled_slices/<PROTEIN>__<ANCESTRY>__chr<C>__<start>_<end>.json.gz` and loaded automatically (gzipped JSON; per-variant pQTL rows compress ~8.5x, so a 5,000-variant slice is ~430 KB on disk vs ~3.5 MB raw). v0.1.0 ships the SORT1 / EUR / OID20213 slice (chr1:108,774,968-109,774,968, the 1p13.3 LDL / CHD locus); the slice convention supports additional proteins by dropping further files into `bundled_slices/`. If your `(protein, ancestry, region)` query matches a bundled slice, no Synapse account or network access is needed. Redistribution is permitted under CC-BY 4.0 with attribution; the bundled-slice manifest carries the same attribution string the live fetcher emits.

2. **Live Synapse fetch (free PAT required).** For arbitrary queries beyond the bundled demo cohort, the skill falls through to a live Synapse downloader. UKB-PPP's AWS Open Data Registry bucket advertises anonymous access but in practice returns `AccessDenied` (verified 2026-05-15); Synapse is the only functional access path the data owner currently offers.

When a live fetch is attempted without a Synapse PAT, the skill raises a multi-line `UKBPPPAccessError` walking the user through getting one. Summary of the steps: