README.md

April 22, 2026 · View on GitHub

MicrOSAtellite Instability Classifier (MOSAIC)

Summary

Scripts and pipeline for calling microsatellite instability (MSI) status from paired tumor/normal exomes, accompanying "Classification and characterization of microsatellite instability across 18 cancer types" in Nature Medicine.

Abstract

Microsatellite instability (MSI), the spontaneous loss or gain of nucleotides from repetitive DNA tracts, is a diagnostic phenotype for gastrointestinal, endometrial, and colorectal tumors, yet the landscape of instability events across a wider variety of cancer types remains poorly understood. To explore MSI across malignancies, we examined 5,930 cancer exomes from 18 cancer types at more than 200,000 microsatellite loci and constructed a genomic classifier for MSI. We identified MSI-positive tumors in 14 of the 18 cancer types. We also identified loci that were more likely to be unstable in particular cancer types, resulting in specific instability signatures that involved cancer-associated genes, suggesting that instability patterns reflect selective pressures and can potentially identify novel cancer drivers. We also observed a correlation between survival outcomes and the overall burden of unstable microsatellites, suggesting that MSI may be a continuous, rather than discrete, phenotype that is informative across cancer types. These analyses offer insight into conserved and cancer-specific properties of MSI and reveal opportunities for improved methods of clinical MSI diagnosis and cancer gene discovery.

Install

git clone https://github.com/ronaldhause/mosaic
cd mosaic

# Option 1: Docker (recommended)
docker build -t mosaic:latest pipeline/containers/

# Option 2: Conda
conda env create -f pipeline/containers/environment.yml
conda activate mosaic

Prerequisites: Docker or Conda, Nextflow (for the end-to-end pipeline), and paired tumor/normal exome BAMs aligned to hg19.

Running MOSAIC on Your Own Data

End-to-end pipeline

The preprocessing and classification pipeline is in pipeline/; see pipeline/README.md for a full walkthrough. A minimal Nextflow invocation:

cd pipeline
nextflow run main.nf \
  -profile local,docker \
  --samplesheet my_sample.csv \
  --reference /refs/hg19.fa \
  --microsatellite_bed /refs/microsatellites.bed \
  --outdir ./results

The samplesheet lists paired tumor/normal BAMs. The pipeline performs mSINGS-based preprocessing at each microsatellite locus and then applies the trained MOSAIC classifier to produce MSI-H/MSS calls.

Using MOSAIC as a classifier only

If unstable microsatellite calls have already been generated with a different tool (for example, mSINGS, lobSTR, or HipSTR), the preprocessing stage can be skipped and the trained MOSAIC classifier applied directly in R:

Call microsatellite markers in hg18 or hg19 using MISA, or download them from the UCSC Genome Browser.
Run mSINGS, lobSTR, HipSTR, or an equivalent tool to identify unstable microsatellites from paired tumor/normal exome BAMs at each microsatellite site.
Reformat the output into a table containing, per sample: an identifier for each locus (msi), the average gain in unique alleles in tumor relative to matched normal tissue across all interrogated microsatellites (peak_avg), and a binary variable indicating whether the DEFB105A/B locus at chr. 8:7679723–7679741 (X8.7679723.7679741) is unstable.
Predict MSI classes using the bundled classifier:

load("pipeline/assets/mosaic_classifier_063016.robj")
predict(mosaic, your_data, type = "raw")