wes-clinical-report-en

# WES Clinical Report (English)

Skill for generating professional clinical PDF reports in English from
whole exome sequencing (WES) data. Designed for Novogene WES data
(GATK + ANNOVAR pipeline) but adaptable to any WES pipeline with
equivalent annotations.

## Trigger

**Fire this skill when the user says any of:**
- "generate WES clinical report in English"
- "English exome PDF report"
- "WES report PDF"
- "clinical report from exome data"
- "Novogene report English"
- "exome clinical PDF"

**Do NOT fire when:**
- User asks for a Spanish report (use `wes-clinical-report-es`)
- User asks for variant annotation only (use `variant-annotation`)
- User asks for ACMG classification only (use `clinical-variant-reporter`)

## Scope

One skill, one task: convert WES markdown reports into professional
English-language clinical PDFs with interpretation.

## Workflow

1. Parse WES markdown report (structured sections 1-7)
2. Extract KPI metrics from Exome Summary
3. Extract pathogenic variants, PGx alerts, rare damaging variants
4. Build interpretive summary paragraph
5. Render all sections as styled PDF with clinical tables
6. Add ancestry estimation (section 8) if data available
7. Add limitations section (section 9)
8. Add disclaimer and report metadata
9. Output PDF to specified directory

## Capabilities

1. **Clinical interpretation summary**: key findings, high-risk PGx alerts,
   prioritised rare variants, clinical follow-up recommendations.
2. **Clinically significant variants**: ClinVar P/LP, ACMG SF v3.2,
   cancer predisposition panel, conflicting variants.
3. **Pharmacogenomics**: CPIC star alleles, clinical effects, affected
   medications with contextualised high-risk alerts.
4. **Fitness and nutrition traits**: genotypes with evidence grades
   (Corpas et al. 2021).
5. **Rare damaging variant prioritisation**: REVEL, CADD, gnomAD AF.
6. **Disease and pathway context**: OMIM, GWAS, COSMIC, KEGG.
7. **Institutional logos**: configurable left/right logos on cover and header.

## Example Output

```
Page 1 (cover):
  [Logo Left]                    [Logo Right]
  +---------------------------------------------+
  |  Whole Exome Sequencing Report  [SampleN]   |
  |  Platform / Reference / Date                |
  +---------------------------------------------+
  [KPIs: Total SNPs | Missense | Stopgain | Rare Damaging | ClinVar]

  Results Interpretation
  (auto-generated clinical summary paragraph)

Pages 2+:
  1. Exome Summary
  2. Clinically Significant Variants
  3. Pharmacogenomics
  4. Fitness and Nutrition Traits
  5. Prioritised Rare Damaging Variants
  6. Disease and Pathway Context
  7. Methods
  8. Ancestry Estimation
  9. Limitations
  [Disclaimer]
```

## Usage

```bash
# Generate reports for all samples
python skills/wes-clinical-report-en/wes_clinical_report_en.py \
  --report-dir /path/to/REPORTS/ \
  --output-dir /path/to/PDF-EN/ \
  --logo-left /path/to/logo_left.jpg \
  --logo-right /path/to/logo_right.jpg

# Generate report for a single sample
python skills/wes-clinical-report-en/wes_clinical_report_en.py \
  --report-dir /path/to/REPORTS/ \
  --output-dir /path/to/PDF-EN/ \
  --samples Sample3

# Demo with default Novogene data
python skills/wes-clinical-report-en/wes_clinical_report_en.py --demo
```

## Input format

The skill consumes WES reports in markdown format generated by the
analysis pipeline (scripts 02-12 in `ANALYSIS/SCRIPTS/`). Each markdown
report must follow this structure:

```markdown
# Whole Exome Sequencing Report: SampleN
> **Project** ... | **Platform** ... | ...
## 1. Exome Summary
## 2. Clinically Significant Variants
## 3. Pharmacogenomics
## 4. Fitness and Nutrition Traits
## 5. Prioritised Rare Damaging Variants
## 6. Disease and Pathway Context
## 7. Methods
```

## Gotchas

1. **Logo paths must exist**: if logo files are missing, the report still
   generates but without institutional branding. The script silently skips
   missing logos.
2. **Table truncation**: tables with more than 20 rows are truncated in
   the PDF with a note to consult TSV files. Do not assume all data is
   visible in the PDF.
3. **Ancestry data is optional**: section 8 requires
   `ancestry_results.json` in the ancestry output directory. If absent,
   the section shows "No ancestry data available."
4. **ClinVar classifications are time-sensitive**: the report reflects
   ClinVar state at annotation time. Do not treat classifications as
   permanent.
5. **PGx star alleles from SNVs only**: CYP2D6 CNV analysis is not
   included. Do not claim complete metaboliser phenotyping.

## Safety

ClawBio is a research and educational tool. It is not a medical device
and does not provide clinical diagnoses. Consult a healthcare professional
before making any medical decisions.

## Agent Boundary

The agent dispatches and explains; the skill executes. The agent should
not modify PDF generation logic inline. All report customisation goes
through CLI flags.

## Chaining Partners

- `variant-annotation`: upstream VCF annotation feeding markdown reports
- `clinical-variant-reporter`: ACMG classification for deeper analysis
- `wes-clinical-report-es`: Spanish language version of the same report

## Maintenance

- Review cadence: quarterly (aligned with ClinVar release cycle)
- Staleness signals: ClinVar version drift, CPIC guideline updates
- Deprecation: if WES is superseded by WGS-only clinical pipelines

## Requirements

- Python 3.9+
- reportlab >= 4.0
- WES markdown reports (see input format above)
- Institutional logos in JPG/PNG (optional)

## Privacy

This skill is **private** and not included in the ClawBio public catalog.
It contains institutional report templates that should not be distributed
publicly.

## References

- Corpas et al. (2021) "Whole Genome Interpretation for a Family of Five"
  *Frontiers in Genetics* 12:535123
- CPIC guidelines for pharmacogenomics
- ClinVar / gnomAD / OMIM / COSMIC / KEGG for variant annotation