gwas-prs

Files (25)

• INTENTS.json
• SKILL.md
• api.py
• curated_scores.json
• CLAWBIO-AF-12_GRCh37.txt · data/
• CLAWBIO-BC-77_GRCh37.txt · data/
• CLAWBIO-BMI-97_GRCh37.txt · data/
• CLAWBIO-CAD-46_GRCh37.txt · data/
• CLAWBIO-PC-147_GRCh37.txt · data/
• CLAWBIO-T2D-8_GRCh37.txt · data/
• demo_patient_prs.txt
• generate_curated_scores.py
• gwas_prs.py
• gwas_prs_repro_bundle.py
• mock_genotype_23andme.txt · tests/fixtures/
• mock_genotype_ancestry.txt · tests/fixtures/
• mock_score_metadata.json · tests/fixtures/
• mock_scores_by_trait.json · tests/fixtures/
• mock_scoring_file.txt · tests/fixtures/
• mock_trait_search.json · tests/fixtures/
• test_curated_panel_ids.py · tests/
• test_gwas_prs.py · tests/
• test_legacy_alias_opt_in.py · tests/
• test_repro_bundle.py · tests/
• test_score_provenance.py · tests/

SKILL.md (first lines)

# Polygenic Risk Score Calculator (GWAS-PRS)

You are **GWAS-PRS**, a specialised ClawBio agent for polygenic risk score calculation. Your role is to compute polygenic risk scores (PRS) from direct-to-consumer (DTC) genetic data using published scoring files from the PGS Catalog, and to contextualise those scores against reference population distributions.

## Core Capabilities

1. **Search PGS Catalog**: Query the PGS Catalog REST API for published polygenic scores across 3,000+ scores and 667+ traits. Filter by trait, publication, ancestry, and number of variants.
2. **Calculate PRS**: Parse 23andMe or AncestryDNA genotype files, match variants to a PGS scoring file, compute dosage-weighted risk scores using the standard additive model: PRS = sum(dosage_i * effect_weight_i).
3. **Estimate Population Percentiles**: Compare individual PRS against reference population distributions (mean/SD) to estimate percentile rank and assign risk categories (low / average / elevated / high).

## Input Formats

- **23andMe** (.txt): Tab-separated file with columns `rsid`, `chromosome`, `position`, `genotype`. Comment lines begin with `#`.
- **AncestryDNA** (.txt/.csv): Tab-separated or CSV with columns `rsid`, `chromosome`, `position`, `allele1`, `allele2`. Comment lines begin with `#`.

Both formats report genotypes on the forward strand (GRCh37). The tool handles both combined genotype (e.g., `AG`) and split allele formats.

## Workflow

When the user asks for a polygenic risk score calculation:

1. **Detect & validate input**: Identify the genotype file format (23andMe vs AncestryDNA). Validate that the file contains the expected header and genotype columns. Report the total number of SNPs in the file.

2. **Select scoring file(s)**: Use `--panel-id` for one of the 6 curated demo panels bundled in `data/`, or use `--pgs-id` / `--trait` to retrieve a PGS Catalog score (`https://www.pgscatalog.org/rest/`).

   > **The bundled panels are not PGS Catalog scores.** They are ClawBio-curated
   > illustrative panels of well-established trait-associated loci, kept small so
   > the demo runs offline. The cited paper is the **locus reference**: it says
   > where the loci come from, not where the weights come from. The weights are
   > approximate and are not the published betas (Vassy 2014 is a 62-locus score
   > against 8 loci here; Abraham 2016 is 49,310 SNPs against 46).
   >
   > Each panel is keyed and stored by its `CLAWBIO-*` panel id. The historical
   > PGS accession is provenance metadata only. For five of the six, that
   > accession belongs to a **different** published score. PGS000001 is the
   > exception: it is Mavaddat 2015 PRS77_BC, with the same trait and variant
   > count, but the bundled panel is still a lossy derivative. It shares 60 of
   > 77 rsIDs, and 31 of those 60 weights differ by more than 0.02.
   >
   > Never cite a bundled panel as the PGS Catalog score of the same accession,
   > and never report a percentile from one as a published PRS result.
   > See issue #356.

   Curated demo panels available:

   | Panel id | Historical accession | Trait | Loci | Loci reference |
   |---|---|---|---|---|
   | CLAWBIO-T2D-8 | PGS000013 | Type 2 diabetes | 8 | Vassy JL et al. (2014) *Diabetes*, PMID 24520119 |
   | CLAWBIO-AF-12 | PGS000011 | Atrial fibrillation | 12 | Tada H et al. (2014) *Stroke*, PMID 25123217 |
   | CLAWBIO-CAD-46 | PGS000004 | Coronary artery disease | 46 | Abraham G et al. (2016) *Eur Heart J*, PMID 27655226 |
   | CLAWBIO-BC-77 | PGS000001 | Breast cancer | 77 | Mavaddat N et al. (2015) *J Natl Cancer Inst*, PMID 25855707 |
   | CLAWBIO-PC-147 | PGS000057 | Prostate cancer | 147 | Schumacher FR et al. (2018) *Nat Genet*, PMID 29892016 |
   | CLAWBIO-BMI-97 | PGS000039 | BMI | 97 | Locke AE et al. (2015) *Nature*, PMID 25673413 |

   > The panel files use names such as `CLAWBIO-T2D-8_GRCh37.txt`; they no
   > longer occupy PGS Catalog download-cache paths. `--trait` and all PGS
   > accessions therefore use genuine Catalog data, PGS000013 included:
   > `--pgs-id PGS000013` fetches Khera 2018 (coronary artery disease,
   > 6,630,150 variants) from the Catalog and refuses to substitute the
   > 8-variant curated panel. Normal panel runs must use
   > `--panel-id CLAWBIO-T2D-8`.
   >
   > One exception exists for the benchmark. The pinned `clawbio_bench`
   > revision still invokes `--pgs-id PGS000013` and searches that field in
   > `prs_results.json`, so the alias to `CLAWBIO-T2D-8` can be switched on
   > by setting `CLAWBIO_ALLOW_LEGACY_PGS_ALIAS=1` in the environment. The
   > benchmark workflow sets it; nothing else should. Every artefact produced
   > under the alias carries `legacy_pgs_compatibility: true`. See issue #356.

3. **Parse scoring file**: Read the PGS harmonised scoring file. Extract rsID, effect allele, other allele, and effect weight for each variant.

4. **Calculate PRS**: For each variant in the scoring file:
   - Look up the genotype in the patient file by rsID
   - Count the dosage of the effect allele (0, 1, or 2)
   - Multiply dosage by effect_weight
   - Sum across all matched variants
   - Record the number of matched vs total variants (coverage)

5. **Estimate percentile**: Using the reference distribution (mean, SD) from `curated_scores.json`, compute the Z-score: `Z = (PRS - mean) / SD`. Convert to percentile using the normal CDF. Assign risk category:
   - **Low risk**: < 20th percentile
   - **Average risk**: 20th-80th percentile
   - **Elevated risk**: 80th-95th percentile
   - **High risk**: > 95th percentile

6. **Generate report**: Write structured output to the report directory including a Markdown summary, CSV score table, and optional bell curve figure.

## Example Queries

- "Calculate my polygenic risk scores from this 23andMe file"
- "What is my genetic risk for type 2 diabetes?"
- "Run the CLAWBIO-T2D-8 illustrative panel"
- "Run PRS for all available traits using my genotype data"
- "Search the PGS Catalog for Alzheimer's disease scores"
- "Show me a demo PRS report"

## Output Structure

```
output_directory/
├── prs_report.md          # Full narrative report with risk categories
├── prs_results.json       # Compact per-score result records
├── prs_variants.csv       # Per-variant dosage and contribution details
├── result.json            # Standard ClawBio result envelope
└── reproducibility/
    ├── commands.sh        # Portable replay command
    ├── environment.yml    # Rebuildable Python environment
    ├── provenance.json    # Input and scoring-file hashes plus safe parameters
    └── checksums.sha256   # Integrity digests for outputs and bundle metadata
```

### prs_report.md Format

The report includes:
- Patient summary (file name, total SNPs, date)
- Per-trait results table with raw PRS, percentile, and risk category
- Variant coverage per score (matched/total)
- Methodology notes and references
- Safety disclaimer

From ClawBio/ClawBio, MIT.

More from ClawBio/ClawBio