bio-clinical-databases-msi-detection

What this skill does

## Version Compatibility

Reference examples tested with: MSIsensor-pro 1.2+, MSIsensor 0.6+, MSIngs 1.0+, MANTIS 1.0.5+, samtools 1.19+, mSINGS 5.6+, pandas 2.2+, cyvcf2 0.30+. FDA pembrolizumab MSI-H / dMMR pan-tumor approval is from 2017 (Le 2015 *NEJM*; KEYNOTE-016/164/158); approval extended to colorectal first-line in 2020.

Before using code patterns, verify installed versions match. If versions differ:
- Python: `pip show <package>` then `help(module.function)` to check signatures
- CLI: `<tool> --version`

If code throws ImportError, AttributeError, or TypeError, introspect the installed package and adapt the example to match the actual API rather than retrying. MSIsensor-pro replaces MSIsensor for tumor-only assays; MSIsensor-ct is the bTMB-equivalent for ctDNA panels.

# MSI Detection; The Companion ICI Biomarker to TMB

**'Detect MSI status from this somatic sequencing data'** -> Profile microsatellite instability across canonical loci (Bethesda 5 panel + extended NGS-derived sites); classify MSI-H / MSS / MSI-L per Bethesda / FDA / KEYNOTE convention.

- CLI (recommended tumor-only): `msisensor-pro msi -d microsatellites.list -t tumor.bam -o msi_out -b 16`
- CLI (paired tumor-normal): `msisensor msi -d microsatellites.list -n normal.bam -t tumor.bam -o msi_out`
- CLI (ctDNA / blood MSI): `msisensor-ct ...`
- CLI (older WES standard): `mantis -t tumor.bam -n normal.bam -b targets.bed --threads 8`
- CLI (panel-only): MSIPanel for clinical assays

## The Regulatory and Trial Landscape

| Event | Year | Threshold | Notes |
|-------|------|-----------|-------|
| **Le 2015** *NEJM* | 2015 | MSI-H + ICI in CRC | The seminal paper: pembrolizumab in MSI-H CRC ORR 40% vs 0% MSS |
| **FDA pembrolizumab MSI-H / dMMR pan-tumor** | 2017 | MSI-H | First tissue-agnostic FDA approval (KEYNOTE-016/164/158) |
| **FDA pembrolizumab first-line MSI-H CRC** | 2020 | MSI-H + first-line CRC | KEYNOTE-177 |
| **CheckMate 142** | 2017-2018 | MSI-H + nivolumab/ipilimumab | Pan-tumor MSI-H second-line |
| **ESMO 2024** | 2024 | MSI-H | Maintained pan-tumor MSI-H biomarker |
| **Universal Lynch screening** | -- | IHC + MSI on all CRC <= 70 yr | NCCN / ACG / EGAPP guidelines |

## MSI vs dMMR vs TMB-H: The Conceptual Hierarchy

| Term | Definition | Method | Relationship |
|------|-----------|--------|--------------|
| **dMMR (deficient MMR)** | Loss of MMR protein function | IHC (MLH1, MSH2, MSH6, PMS2) | Causes MSI |
| **MSI-H** | Microsatellite instability high | PCR-based Bethesda or NGS | Consequence of dMMR |
| **Lynch syndrome** | Germline MMR mutation | Germline sequencing | Causes ~50% of MSI-H CRC; rest are sporadic (MLH1 hyper-methylation) |
| **TMB-H** | >= 10 mut/Mb | NGS panel / WES | Statistical correlate of MSI-H |
| **POLE-exo hypermutator** | POLE proofreading defect | Sequencing / signatures | Hypermutator WITHOUT MMR-D; MSI-stable typically |

**MSI-H + TMB-H overlap** (Salem ME et al 2018 *Mol Cancer Res* 16(5):805-812):
- ~80% of MSI-H tumors in CRC and endometrial are TMB-H.
- ~16% of TMB-H solid tumors are MSI-H.
- Sha 2020 *Cell Rep Med*: MSI-H supersedes TMB-H for ICI biomarker decision; TMB-H not additive.

**POLE-exo vs MMR-D:**
- POLE-exo (SBS10a/10b): hypermutator (100-300 mut/Mb pure); typically MSI-stable.
- MMR-D (SBS6/15/26/44 + ID1/2): 30-50 mut/Mb typical; MSI-H.
- POLE-exo + MMR-D (SBS14 + SBS20): ultra-hypermutator >=500 mut/Mb; MSI-H.

## Tool Taxonomy

| Tool | Paired | Tumor-only | ctDNA | Algorithm | Fails when |
|------|--------|-----------|-------|-----------|-----------|
| **MSIsensor** (Niu 2014 *Bioinformatics*) | Yes | No | No | Bayesian + read-length distribution | Tumor-only data (no baseline); cohort baseline missing |
| **MSIsensor-pro** (Jia 2020 *Genom Proteom Bioinform*) | Optional | **Yes** | No | Distribution comparison to baseline | Baseline cohort not provided; panel < 50 loci |
| **MSIsensor-ct** (Han 2021 *Brief Bioinform*) | -- | -- | **Yes** | cfDNA-aware | Tumor fraction < 3%; low ctDNA shed |
| **MANTIS** (Kautto 2017 *Oncotarget*) | Yes | No | No | Step-wise difference | Tumor-only; low coverage at microsatellites |
| **MSIngs** (Salipante 2014 *Clin Chem*) | Yes | No | No | Number of unstable loci | Tumor-only; outdated vs MSIsensor-pro |
| **mSINGS** (Salipante 2014) | -- | Yes | No | Background panel | Background panel poorly characterized for cohort |
| **MSIPanel** | -- | Yes | -- | Panel-specific calibration | Panel not in vendor calibration table |
| **ngsMSI** | Yes | Yes | -- | Algorithmic variations | Limited benchmarking; rarely first choice |
| **MSIDetect** | Various | -- | -- | DL-based | New tool; reproducibility data still maturing |
| **MMR-MS** | IHC concordance check | -- | -- | -- | Not a direct MSI caller; for orthogonal validation |

**Operational consensus 2024-2026:**
- **Tumor + paired normal WES:** MSIsensor or MANTIS.
- **Tumor-only assay** (commercial panels, often unpaired): MSIsensor-pro with reference baseline.
- **ctDNA / liquid biopsy:** MSIsensor-ct.
- **Lynch screening:** IHC FIRST (rules out 90%+); MSI-PCR / NGS confirmatory.

## Decision Tree by Scenario

| Scenario | Recommended path | Why |
|----------|------------------|-----|
| Tumor + paired normal WES | MSIsensor (standard) | Reference paired-normal comparison |
| Tumor-only WES/panel | MSIsensor-pro with panel baseline | No matched normal needed |
| ctDNA / liquid biopsy | MSIsensor-ct | cfDNA-aware |
| Lynch syndrome screening | Universal IHC + MSI (NCCN) | IHC catches 90%+; MSI for IHC-equivocal |
| FDA pembrolizumab eligibility | Validate per FoCR PCR + IHC + NGS concordance | Cross-platform required |
| MSI-H + TMB-H concurrence | MSI-H is primary biomarker | Sha 2020; TMB-H not additive |
| POLE+MMR ultra-hypermutator | Sigprofiler signatures (SBS14, SBS20) | Mechanism beyond MSI alone |
| Sporadic MSI-H | Confirm MLH1 hypermethylation; rule out Lynch | Distinguishes sporadic vs germline |
| MSI-stable + TMB-H | Investigate POLE-exo signature (SBS10a/10b) | POLE-exo causes hypermutator without MSI |
| Pan-tumor screening | MSI + IHC + TMB combined | Multiple modalities for ICI eligibility |

## Bethesda Panel and Modern NGS-Derived Loci

The **Bethesda 5-locus panel** (Boland 1998) is the PCR-based reference:
- **BAT-25** (chr4)
- **BAT-26** (chr2)
- **NR-21** (chr14)
- **NR-24** (chr2)
- **MONO-27** (chr2; also called BAT-25/Penta C in some nomenclature)

NGS-based MSI panels use 50-1000+ microsatellite loci. MSI-H requires unstable status at >=40% of tested loci typically (varies by panel calibration).

## Standard Workflow: MSIsensor-pro Tumor-Only

**Goal:** Compute MSI status from tumor-only WES/panel.

**Approach:** Generate baseline from population reference; compare patient tumor.

```bash
# Generate microsatellite list from reference genome (one-time)
msisensor-pro scan -d /reference/GRCh38.fa -o microsatellites.list -p 1 -m 5

# Generate baseline from N normal control samples (one-time per panel)
msisensor-pro baseline -d microsatellites.list -i normal_samples.list -o baseline.list -b 16

# Score tumor sample. The `-i sample_id` flag is uncommon: in typical msisensor-pro
# usage the sample identifier is derived from the BAM file -- verify the flag set
# against `msisensor-pro pro --help` for the installed release.
msisensor-pro pro \
    -d microsatellites.list \
    -t tumor.bam \
    -o msi_output \
    -b 16 \
    --baseline baseline.list

# Output: msi_output_all (raw); msi_output_unstable (unstable loci); msi_output.txt (summary)
# Critical column: %_unstable. Threshold MSI-H typically >= 20-30% depending on panel.
```

## Paired Tumor-Normal MSIsensor

```bash
msisensor msi \
    -d microsatellites.list \
    -n normal.bam \
    -t tumor.bam \
    -o msi_paired_out \
    -b 16

# Output: %_unstable in paired comparison
# MSI-H threshold: >= 20% by FoCR guidance; varies 10-30% across studies
```

## MANTIS Step-wise Difference

```bash
mantis.py \
    -t tumor.bam \
    -n normal.bam \