--- name: clawbio/ukb-ppp-region-fetch source: https://app.decimal.ai/s/clawbio-ukb-ppp-region-fetch@1/SKILL.md source_sha256: d44104382f4d --- # 🧪 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/____chr___.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: 1. Register a free account at . 2. Accept the Synapse Terms of Use (one-time click-through). 3. Open → "Personal Access Tokens". 4. Click "Create new token". Tick scopes `view` and `download`. Copy the token immediately (Synapse shows it once). 5. Export it: `export SYNAPSE_AUTH_TOKEN=` and re-run. **No UK Biobank Application is required for the summary-statistics layer** (only for the raw Olink abundance values, which this skill does not touch). ## Overview UKB-PPP (Sun et al. 2023 *Nature*) is the largest open-access plasma proteomic GWAS resource, profiling 2,923 Olink Explore 3072 proteins across 54,219 UK Biobank participants stratified into European discovery (N=46,673) plus six smaller ancestry breakouts (African, Central/South Asian, East Asian, Middle East, American Hispanic, and a Combined multi-ancestry meta-analysis). Summary statistics are released per (protein × ancestry) as REGENIE step-2 outputs and packaged as `___v1_.tar` archives on Synapse (`syn51364943`). Each tar contains one gzipped REGENIE file per autosome + X. This skill resolves a protein label (HGNC or UniProt) to the canonical Synapse fileID, downloads the protein's tar to a local cache, extracts the per-chromosome file, filters to a `(chr, start, end)` window, and emits a harmonised TSV slice plus a provenance manifest. ## Trigger **Fire when** the user (or upstream agent step) wants: - A regional slice of pQTL summary statistics (β, SE, p-value) for variants in a specified GRCh38 window for one Olink reagent in UKB-PPP. Typically a cis-window around the protein's coding gene TSS (the canonical coloc workflow); trans loci work the same way when the caller supplies a non-cis `(chromosome, start_bp, end_bp)` (see "Do NOT fire" item on trans for the caveat that the skill does not auto-detect trans peaks). - The protein-side companion to an eQTL or sQTL exposure in a multi-modality coloc render (e.g. SORT1 eQTL liver × pQTL plasma × LDL-C GWAS). - Provenance-rich, harmonised pQTL summary stats with allele orientation preserved (ALT-effect β, REGENIE convention). **Do NOT fire when** the user wants: - An **eQTL or sQTL** regional slice: use `eqtl-catalogue-region-fetch` instead (one fetcher handles all eQTL Catalogue quantification methods including ge/exon/tx/txrev/leafcutter, plus single-cell eQTL studies in v7+). - A **single-variant pQTL lookup**: UKB-PPP's full archive is large; a per-variant lookup against the Open Targets pQTL coloc table is cheaper for one-point queries. - The **deCODE pQTL** panel (Ferkingstad 2021): a different upstream cohort with separate access terms; this skill targets UKB-PPP only. Choose the upstream-source skill at the orchestrator level. - The **raw Olink abundance values** linked to phenotypes: those are gated behind a UK Biobank Application via Synapse `syn52364558` and are out of scope for the public locuscompare render path. - **trans-pQTL signals** at distant loci: UKB-PPP releases full-genome summary stats per protein, so trans signals are present in the data, but the `(chromosome, start_bp, end_bp)` window must be supplied explicitly; the skill does not auto-detect trans peaks. ## Scope **One skill, one task.** This skill fetches one `(protein × ancestry)` pair's regional summary statistics from UKB-PPP and writes them as a harmonised TSV plus a provenance manifest. It does NOT iterate proteins, ancestries, or windows; it does NOT do pQTL fine-mapping or coloc directly; it does NOT fetch eQTL / sQTL / sceQTL (use `eqtl-catalogue-region-fetch`); it does NOT fetch the deCODE pQTL panel. The caller composes those workflows on top. ## Workflow When an agent asks for a regional pQTL slice from UKB-PPP: 1. **Resolve the protein.** The skill lists the requested ancestry folder on Synapse (`syn51365303` for EUR, etc.) and parses `___v1_.tar` filenames into a (HGNC, UniProt) -> Synapse fileID index. Lookup tolerates both keys; HGNC is the default surface. The listing call is auth-free; only the subsequent download requires a Synapse PAT. 2. **Resolve the ancestry.** EUR is the default for most coloc renders given its 50x cohort size advantage; use AFR / EAS / CSA / MID / AMR for ancestry-specific renders. The 1000 Genomes super-population for the LD reference panel (1000G Phase 3) maps EUR -> EUR, AFR -> AFR, EAS -> EAS, CSA/SAS -> SAS, MID -> EUR proxy with caption caveat, AMR -> AMR. 3. **Download the tar (cached).** First fetch downloads the protein tar via `synapseclient` to the local cache (`UKB_PPP_CACHE_DIR` env or `~/.clawbio/ukb_ppp_region_fetch_cache/`). Repeat fetches across regions on the same protein reuse the cached tar. 4. **Extract the chromosome.** The tar contains one gzipped REGENIE file per autosome + X. The parser matches `chr` on a strict word boundary so chr1 doesn't accidentally pull chr10. 5. **Stream-filter to the window.** REGENIE files are plain gzip (not BGZ / tabix), so regional fetches scan one chromosome's file linearly. ~1M rows per chromosome; ~2 s on a modern laptop per window. Rows are normalised to OT `chr_pos_ref_alt` ALT-effect convention; LOG10P is converted to a linear p-value; A1FREQ above 0.5 is folded to MAF. 6. **Write outputs** to `--output /`: a flat `variants.tsv` (effect-allele-aligned, GRCh38, ALT-effect β), a `manifest.yaml` with provenance (study_label, release_label, protein_hgnc, protein_uniprot, olink_reagent_id, olink_panel, ancestry, ancestry_label, n_samples, synapse_id, source_url, fetched-at UTC timestamp, attribution string), and a `report.md` human-readable summary. ## CLI Reference ```bash # Standard usage with a config file (Synapse PAT in env) SYNAPSE_AUTH_TOKEN=... python skills/ukb-ppp-region-fetch/ukb_ppp_region_fetch.py \ --input --output # Bundled demo (SORT1 plasma pQTL in EUR; the canonical 1p13.3 LDL/CHD locus) SYNAPSE_AUTH_TOKEN=... python skills/ukb-ppp-region-fetch/ukb_ppp_region_fetch.py \ --demo sort1_ukb_ppp_eur --output /tmp/sort1_ukbppp_demo # List the bundled demos python skills/ukb-ppp-region-fetch/ukb_ppp_region_fetch.py --list-demos # Via ClawBio runner SYNAPSE_AUTH_TOKEN=... python clawbio.py run ukb-ppp-region-fetch --input ``` Config schema (JSON or YAML): ```json { "protein_label": "SORT1", "ancestry": "EUR", "chromosome": "1", "start_bp": 108774968, "end_bp": 109774968 } ``` ## Example Output Running `--demo sort1_ukb_ppp_eur` (see `examples/expected_output.md` for the full reproduction): ``` info: using bundled demo ukb-ppp-region-fetch: ~120,000 variants -> /tmp/sort1_ukbppp_demo/variants.tsv source: UKB-PPP | SORT1 (Q99523, OID20213) | European (discovery) (EUR) ``` ## Gotchas 1. **Live fetch requires a free Synapse PAT, not anonymous AWS Open Data.** The AWS Open Data Registry page advertises `arn:aws:s3:::ukbiobank.opendata.sagebase.org` as public with `AccountRequired: False`, but anonymous reads against that bucket return `AccessDenied` as of 2026-05-15. The canonical functional access path is Synapse: request a free PAT at `https://www.synapse.org/Profile:settings` and export it as `SYNAPSE_AUTH_TOKEN`. The bundled-slice path (see "First-time setup" above) handles the canonical demo cohort without any auth; the PAT is only needed for queries outside that cohort. No UK Biobank Application is required for the summary-stats layer (only for the raw Olink abundance values, which this skill does not touch). 2. **One protein, one tar, full-genome.** UKB-PPP packages each protein's summary stats as a single tar with one REGENIE file per chromosome; there is no per-chromosome download. First-fetch for a protein downloads ~100–500 MB. Subsequent regional fetches on the same protein reuse the cached tar. 3. **REGENIE LOG10P, not -log10(p).** The REGENIE column reports `|log10(p)|` (always positive). The skill converts to linear `p_value = 10^-LOG10P` at the row boundary. Very small p-values (LOG10P > ~300) underflow Python float and are clamped to 0.0 rather than raising. 4. **A1FREQ is the ALLELE1 (ALT, effect) frequency, not MAF.** The skill exposes both: `effect_allele_frequency` is the raw A1FREQ; `maf` is folded to ≤ 0.5. Downstream code (e.g. palindromic-variant excluder) reads `effect_allele_frequency`. 5. **β is on the ALT allele.** Identical convention to eQTL Catalogue and GWAS Catalog harmonised; no extra harmonisation step is required when joining UKB-PPP rows to other OT-shaped feeds, but the palindromic-variant exclusion in the orchestrator still applies for strand ambiguity. 6. **Some HGNC symbols map to >1 Olink reagent.** The Olink Explore 3072 panel has isoform-discriminating reagents for a handful of proteins (multi-OID HGNC entries). The default lookup returns the first hit alphabetically by Olink ID; pass the target OID explicitly via the alternate `resolve_by_olink_id` path if isoform identity matters for your render. 7. **Per-chromosome file names vary slightly across the release.** The parser matches `chr` on a strict word boundary inside `.tar` members, accepting names like `discovery_chr1__*.regenie.gz` or `chr1_*.tsv.gz`. The strict boundary prevents chr1 from accidentally matching chr10 / chr11, a class of bug that would silently return the wrong chromosome's data. ## Safety **Not for clinical decisions.** This skill returns research-grade summary statistics from a public proteomic GWAS. Do not use the output for direct clinical decision-making, diagnosis, or treatment selection without independent validation by a qualified clinician. **Effect estimates may not generalise across populations.** UKB-PPP's discovery cohort is overwhelmingly European (N=46,673 vs N=931 for African, the next-largest stratum). Effect sizes from EUR-discovery analyses should not be assumed to apply uniformly across other ancestries; the orchestrator's caption layer flags this when the ancestry side of an LD reference panel mismatches the source study. **Plasma vs tissue.** UKB-PPP measures circulating plasma proteins, which is biologically distinct from cell- or tissue-level protein abundance. Downstream interpretation should not assume a plasma cis-pQTL implies an identical effect on intra-cellular abundance for the same protein. ## Agent Boundary The skill returns harmonised summary statistics (β, SE, p-value, MAF, EAF) for variants in a chromosomal window from one (protein × ancestry) UKB-PPP measurement. The agent should: - **Use the output as input to colocalisation, fine-mapping, or Mendelian randomisation tooling.** These are the appropriate downstream methods for inferring causal effects. - **NOT make causal-effect claims directly from a single pQTL p-value.** Statistical association ≠ causation; instrumental-variable assumptions must be satisfied for MR. - **NOT cherry-pick variants by p-value alone.** Statistical inference requires the full credible set / window context. - **NOT compare effect sizes across ancestries without acknowledging cohort N.** EUR's 50x sample-size advantage means EUR effect estimates have much tighter SEs; "no effect" in a small-N ancestry stratum may reflect power, not biology. - **Surface protein identity, Olink reagent ID, and ancestry in the user-facing reply** alongside any β / p-value the agent quotes. Per the user-friendly enum-expansion rule (`CLAUDE.md`), expand all three fields: `protein = SORT1 (Q99523, OID20213); ancestry = European (discovery) (EUR); N = 46,673`. - **NOT silently swap Olink reagents.** If the user asked for `SORT1` and the dataset is `SORT1-AOH2` (a different isoform reagent), the agent must say so explicitly. ## Citations - Sun, B.B., Chiou, J., Traylor, M. et al. (2023). *Plasma proteomic associations with genetics and health in the UK Biobank.* Nature 622, 329–338. doi:10.1038/s41586-023-06592-6 (PMID 37794186). - UKB-PPP data release: (Sage Bionetworks, CC-BY 4.0). - REGENIE: Mbatchou, J. et al. (2021). *Computationally efficient whole-genome regression for quantitative and binary traits.* Nat Genet 53, 1097–1103. - Olink Explore 3072 panel content: . - `synapseclient` Python library: Sage Bionetworks (Apache-2.0). Used by the live-fetch path; not invoked when serving a bundled slice.