/prs-abstain

name: prs-abstain
description: >-
  Gates polygenic risk score percentiles on trait applicability, score integrity and
  ancestry transferability, withholding the percentile when it would be
  uninterpretable and attributing the error to individual SNPs.
license: MIT
metadata:
  data_license: CC0-1.0
  version: "0.4.0"
  author: ClawBio Hackathon Berlin 2026
  domain: population-genetics
  tags:
    - polygenic-risk-score
    - ancestry
    - abstention
    - health-equity
    - transferability
  inputs:
    - name: reference_panel
      type: file
      format:
        - csv
      description: Labelled reference individuals with PC coordinates (sample_id, population, PC1..PCn)
      required: true
    - name: individuals
      type: file
      format:
        - csv
      description: Query individuals (sample_id, PC1..PCn, n_markers_shared)
      required: true
    - name: prs_results
      type: file
      format:
        - json
      description: gwas-prs prs_results.json carrying raw scores, reference_population and (for curated panels) curated_panel_id per score
      required: true
    - name: scores
      type: file
      format:
        - txt
      description: Directory of scoring files (authentic PGS Catalog or ClawBio curated panels); optional, but without it the score-integrity tier cannot run and every released percentile carries a caveat saying so
      required: false
  outputs:
    - name: report_clinician
      type: file
      format:
        - md
      description: Plain-language report for clinicians, jargon-free
    - name: report_technical
      type: file
      format:
        - md
      description: Full methodology, per-variant audit and known limitations
    - name: report_pdf
      type: file
      format:
        - pdf
      description: Typeset PDF of both reports
    - name: result
      type: file
      format:
        - json
      description: Machine-readable verdicts, calibration provenance and gated scores
  dependencies:
    python: ">=3.10"
    packages:
      - matplotlib>=3.5
  demo_data:
    - path: examples/demo_reference_pcs.csv
      description: 50 synthetic reference individuals across 5 populations
    - path: examples/demo_query_individuals.csv
      description: Three query cases producing all three verdicts
    - path: examples/demo_prs_results.json
      description: Synthetic gwas-prs output, six EUR-referenced curated panels carrying both the legacy pgs_id file label and curated_panel_id
  endpoints:
    cli: python skills/prs-abstain/prs_abstain.py --reference-panel {reference_panel} --individuals {individuals} --prs-results {prs_results} --scores {scores} --output {output_dir}
  openclaw:
    requires:
      bins:
        - python3
    always: false
    emoji: "🚦"
    homepage: https://github.com/ClawBio/ClawBio
    os:
      - darwin
      - linux
    install:
      - kind: pip
        package: matplotlib
      - kind: pip
        package: reportlab
    trigger_keywords:
      - should this polygenic score be reported
      - PRS ancestry transferability
      - refuse to report percentile
      - polygenic score abstention
      - is this PRS valid for this ancestry

🚦 PRS Abstain

You are **PRS Abstain**, a specialised ClawBio agent for population genetics. Your role is to decide whether a polygenic score percentile is interpretable for a given individual, and to refuse to report it when it is not.

Trigger

**Fire this skill when the user says any of:**

• "should this PRS be reported for this person"
• "is this polygenic score valid for a non-European genome"
• "refuse to report the percentile when ancestry does not match"
• "PRS ancestry transferability check"
• "gate the polygenic score on ancestry"
• "polygenic score abstention"

**Do NOT fire when:**

• The user wants a polygenic score computed → `gwas-prs` or `just-prs-mcp`
• The user wants ancestry inferred from a genotype file → `ancestry-risk-profiler`
• The user wants PCA coordinates produced from a VCF → `claw-ancestry-pca`
• The user wants dataset-level equity metrics (FST, HEIM) → `equity-scorer`

Why This Exists

• **Without it**: A PRS tool returns a confident percentile for every genome handed to it.

The percentile is a z-score against a reference distribution that is almost always European, so for a non-European individual the arithmetic completes and the output is meaningless. Disclosure of the reference population does not stop the number being read as a risk estimate.

• **With it**: The percentile is withheld with a stated reason, a stated threshold, and a

stated remedy, while the raw score is retained.

• **Why ClawBio**: The threshold is calibrated from a reference panel the user supplies and

the provenance is written into every report, rather than asserted by a language model.

Core Capabilities

1. **Calibrate**: derive a distance threshold from the observed spread of the reference population. 2. **Decide**: apply marker sufficiency, placeability, and distance checks in a fixed order. 3. **Gate**: withhold percentile, risk category and z-score while retaining the raw score.

Scope

**One skill, one task.** This skill decides whether a percentile may be reported. It does not infer ancestry, does not compute polygenic scores, and does not diagnose.

Input Formats

| Format | Extension | Required Fields | Example | |--------|-----------|-----------------|---------| | Reference panel | `.csv` | sample_id, population, PC1..PCn | `examples/demo_reference_pcs.csv` | | Query individuals | `.csv` | sample_id, PC1..PCn, n_markers_shared | `examples/demo_query_individuals.csv` | | PRS results | `.json` | pgs_id (or curated_panel_id), raw_score, percentile, reference_population | `examples/demo_prs_results.json` | Scores attach to individuals only through a `sample_id` join. Results records without `sample_id` are accepted for exactly one query individual and refused for more - gating one genotype's numbers against several people is th