ssimpy

ssimpy is a Python command-line tool for detecting statistically significant pairwise somatic co-mutations in cancer genomics data. It implements the SelectSim algorithm, testing both co-occurrence (two genes mutated together more frequently than expected by chance) and mutual exclusivity (two genes mutated together less frequently than expected by chance) using a simulation-based FDR framework.

Features

• rcRAS simulation engine — generates null GAMs that exactly preserve each gene's observed mutation count
• TMB-aware penalty — down-weights hypermutated samples to avoid signal dominated by outlier tumors
• Bidirectional FDR — separately calibrated FDR for co-occurrence and mutual exclusivity
• Sample class covariates — per-subtype expected mutation matrices (e.g. LUAD vs LUSC)
• Mutation type covariates — element-wise max of per-type E matrices (e.g. missense + truncating)

Installation

Requires Python ≥ 3.9 and numpy + pandas:

pip install numpy pandas

Clone the repository and run from within the ssimpy/ directory:

git clone https://github.com/CSOgroup/ssimpy.git
cd ssimpy
python ssimpy.py --gam <gam.tsv> [options]

Input files

File	Required	Description
GAM (TSV)	Yes	Binary matrix: rows = genes, columns = samples
TMB (TSV)	No	Per-sample mutation burden; columns: sample, tmb/mutation, optional class
MAF (TSV)	No	Mutation Annotation Format file (alternative TMB source, single-GAM mode only)

When the TMB file includes a class column, ssimpy automatically computes separate expected mutation matrices per class.

Usage

Minimal run

python ssimpy.py --gam lung_gam.tsv --output results.tsv

With pre-calculated TMB and sample class covariates

python ssimpy.py \
    --gam lung_gam_complete.tsv \
    --tmb lung_tmb_complete.tsv \
    --N 1000 --seed 42 \
    --output results.tsv

Multiple mutation types (missense + truncating)

python ssimpy.py \
    --gam lung_gam_missense.tsv lung_gam_truncating.tsv \
    --tmb lung_tmb_missense.tsv lung_tmb_truncating.tsv \
    --N 1000 --seed 42 \
    --output results_multitype.tsv

All GAM files must share identical genes and samples. The combined GAM is their element-wise union; the expected matrix E is the element-wise maximum across per-type E matrices.

Key parameters

Argument	Default	Description
--N	1000	Number of rcRAS simulations
--min-mut	5	Minimum mutated samples to retain a gene
--fdr	0.1	FDR threshold for significance calls
--tau	1.0	TMB fold-change threshold for penalization
--lam	0.3	Rate of TMB-based penalization
--filter-pct	0.10	Fraction of worst simulations to discard
--seed	None	Random seed for reproducibility
--output	selectsim_results.tsv	Output file path

Output

A TSV file with one row per gene pair, sorted by |nES| descending. Key columns:

Column	Description
gene1, gene2	Gene pair
n_comut	Samples mutated in both genes
nES	Normalized effect size (+ co-occurrence, − mutual exclusivity)
direction	co-occurrence or mutual_exclusivity
FDR	Estimated false discovery rate
significant	True if FDR < threshold

Preparing input files from a MAF

The companion script maf_to_ssimpy.py converts a standard MAF file into the GAM and TMB files required by ssimpy.

Basic usage

python maf_to_ssimpy.py --maf input.maf --prefix cohort --output-dir ./data

This produces cohort_gam.tsv and cohort_tmb.tsv ready to pass to ssimpy.

Separate missense and truncating files

python maf_to_ssimpy.py --maf input.maf --split-by-type --prefix cohort

Produces six files: cohort_gam.tsv, cohort_gam_missense.tsv, cohort_gam_truncating.tsv, and the corresponding TMB files. Pass the per-type GAMs and TMBs to ssimpy with --gam and --tmb to enable mutation-type covariates.

Restrict to a gene list and set mutation thresholds

python maf_to_ssimpy.py \
    --maf input.maf \
    --gene-list cancer_genes.txt \
    --min-samples 2 \
    --min-mutations 5 \
    --split-by-type \
    --prefix cohort

cancer_genes.txt is a plain text file with one gene name per line (lines starting with # are ignored).

MAF converter parameters

Argument	Default	Description
--maf	required	Input MAF TSV file
--output-dir	.	Directory for output files
--prefix	ssimpy	Filename prefix for all output files
--split-by-type	off	Also produce separate missense and truncating GAM/TMB files
--metadata	None	TSV with sample and class columns — adds a class column to all TMB files
--gene-list	None	Text file (one gene per line) — restricts the GAM to listed genes only
--min-samples	2	Minimum number of mutated samples for a gene to be retained
--min-mutations	1	Minimum total non-synonymous mutations across all samples for a gene to be retained

Note on TMB: sample TMB is computed from all non-silent mutations genome-wide (not limited to the genes retained in the GAM), which is the correct measure of overall mutational activity used by ssimpy's penalty vector.

Mutation type classification

Category	Variant classifications
Silent (excluded from TMB and GAM)	Silent, Synonymous_Mutation
Missense	Missense_Mutation, In_Frame_Del, In_Frame_Ins
Truncating	Nonsense_Mutation, Frame_Shift_Del, Frame_Shift_Ins, Splice_Site, Splice_Region, Nonstop_Mutation, Translation_Start_Site
Other non-silent	all remaining — counted in TMB and combined GAM, excluded from per-type files

Full pipeline example (MAF → ssimpy results)

# Step 1: convert MAF to ssimpy input files
python maf_to_ssimpy.py \
    --maf lung.maf \
    --metadata sample_classes.tsv \
    --split-by-type \
    --min-samples 2 --min-mutations 5 \
    --prefix lung --output-dir ./data

# Step 2: run ssimpy with mutation-type and class covariates
python ssimpy.py \
    --gam data/lung_gam_missense.tsv data/lung_gam_truncating.tsv \
    --tmb data/lung_tmb_missense.tsv data/lung_tmb_truncating.tsv \
    --N 1000 --seed 42 \
    --output results.tsv

Reference

ssimpy is the Python implementation of the SelectSim methodology. See also:

• SelectSim R package
• SelectSim analysis scripts