Skip to content

ID89 and ID476 Indel Counts

This optional feature adds the indel classification schemes described by Koh et al. (2025) and explored in the Indel Signature Browser. ID476 captures detailed sequence/repeat features; ID89 groups events into 89 categories. They are mutation categories, not 89 or 476 different extracted signatures.

Existing calls keep generating their usual ID83 and other matrices. To request the additional counts, pass indel_contexts=("89", "476") in Python or --indel_contexts 89 476 on the CLI. Either context can be requested alone.

Install the Development Branch

This feature is on feature/id89-id476, based on the CHM13 support branch. It is not a new PyPI release. Use a separate environment for testing:

python -m venv .venv-id-indels
source .venv-id-indels/bin/activate
python -m pip install --upgrade pip
python -m pip install "git+https://github.com/SigProfilerSuite/SigProfilerMatrixGenerator.git@feature/id89-id476"

Install the reference that matches your variant coordinates before running the examples. See Python installation for standard references and the CHM13 example for the development CHM13 archive. The ID89/ID476 feature itself needs no additional archive.

Python Example

from SigProfilerMatrixGenerator.scripts import SigProfilerMatrixGeneratorFunc as matGen

matrices = matGen.SigProfilerMatrixGeneratorFunc(
    project="my_project",
    reference_genome="CHM13-T2T",
    path_to_input_files="/path/to/vcfs",
    volume="/path/to/reference-folder",
    output_directory="/path/to/output",
    indel_contexts=("89", "476"),
    plot=False,
)

id89 = matrices["ID89"]
id476 = matrices["ID476"]
# Existing matrices["ID"] remains the existing ID83 result.

Use the matching installed reference. GRCh37, GRCh38 and CHM13-T2T are covered by the feature's reference-specific tests. The classifier reads DNA directly from registered chromosome files, so installing this feature does not require rebuilding or replacing a genome archive. See the CHM13 example for local archive installation.

CLI Example

SigProfilerMatrixGenerator matrix_generator my_project CHM13-T2T /path/to/vcfs \
  --volume /path/to/reference-folder \
  --output_directory /path/to/output \
  --indel_contexts 89 476

Add --exome for exome downsampling or --bed_file /path/to/regions.bed for selected regions. Existing --cushion and --chrom_based options also apply. The new matrices always retain all canonical rows, including zero-count rows.

Outputs

Under output/ID/, whole-genome output includes:

  • my_project.ID89.all: 89 rows, one column per sample.
  • my_project.ID476.all: 476 rows, one column per sample.
  • my_project.ID89_ID476.classification.all.tsv: per-event labels and reasons for exclusions, plus normalized position, repeat count, unit length and microhomology length. This audit report is independent of seqInfo.

Exome files use .exome and BED files use .region instead of .all. chrom_based=True additionally writes .chr<chromosome> matrices. Returned ID89/ID476 matrices contain the aggregate counts across chromosomes.

The existing ID83/ID96 and other legacy indel files remain unchanged. Their totals need not match the new matrices: complex-event handling, normalization, and invalid-context rules differ. ID89 and ID476 use the same accepted events and therefore have the same per-sample total within a run.

Input and Filtering Rules

Use uncompressed VCFs with literal, anchored ACGT REF/ALT alleles, in the coordinates of the installed genome. Split multi-allelic records and resolve symbolic alleles before analysis. The new classifier rejects ambiguous (N), symbolic, comma-separated or gapped (-) alleles with an explicit reason. The report covers indel candidates passed by the existing input converter; records that the converter rejects earlier are covered by its existing log. In particular, gap-based MAF/simple-text indels are not supported by the new classifier yet; this does not change the existing ID83 behavior for those inputs.

The complete REF allele must match the genome, not just its anchor. Simple indels undergo common-prefix/suffix trimming and left alignment. The classifier retains the original input position for region selection, so normalization does not move a call into or out of a panel. It follows the existing matrix API's inclusive anchor bounds and cushion, without changing historical interval conventions. Duplicate normalized events are removed within each sample and chromosome, not across different samples.

Unknown flanking sequence and missing required context produce a reported exclusion, not a guessed label or chromosome-end wraparound. Counts do not impose a PASS-only filter beyond the existing input pipeline or automatically apply the authors' optional high-specificity filters. Check the audit report and run log when comparing tools with different input/filter policies.

Long repeats remain included. Open upper bins such as R(9,) mean 9 or more, while the report preserves the actual repeat count. Some historical reference scripts use closed spellings such as R(5,9) and discard high-repeat calls. Results under those filtering policies are not directly interchangeable.

Complex Replacements

A complex replacement (delins) removes DNA and inserts different DNA at the same site. After trimming shared allele ends, this implementation uses abs(deleted_length - inserted_length) for ID476 bins Complex(0,1), Complex(2,5), Complex(6,10), Complex(11,20) and Complex(21,). For example, replacing two bases with four has a net length change of two and enters Complex(2,5). All these events enter ID89 Complex.

This is an explicit implementation convention, not an author-confirmed interpretation for every complex event. The original reference scripts leave some balanced and net-insertion replacements unassigned. Tests verify the stated convention separately; they do not establish unchanged upstream agreement for those cases. Confirmation from the original authors remains a follow-up before making that scientific compatibility claim.

Why We Classify Both Formats from Each Event

ID83 cannot supply the additional sequence/repeat details on its own. Nor is every ID476 category a lossless parent of an ID89 category: deleting six bases from four versus five AT repeats produces the same ID476 channel Del(6,):U2:R(4,) but different ID89 repeat categories. Both labels therefore come from each original event, not a blanket matrix-only conversion.

Validation and Downstream Limits

The source includes synthetic reference-label fixtures covering every ID476 and ID89 channel. The initial external R/C++ comparison matched 15,630 simple indel cases; 11 additional complex cases were checked against the explicit convention above, not treated as unchanged upstream results. Tests also compare original and extended public-API results and legacy output bytes in whole-genome, exome, BED and chromosome modes. Full suites passed with pandas 2 and pandas 3, and independent review included additional CHM13 examples. These checks are not biological or clinical validation. Exact sources and conventions are recorded in reference_data/indel_taxonomy/README.md in the repository.

These outputs are raw mutation counts. No ID89/ID476 opportunity normalization, new transcription-strand channels, signature catalogue, or clinical prediction model is included. plot=True still applies only to previously supported plot types; SigProfilerPlotting needs separate ID89/ID476 work. Extractor and Assignment compatibility must be checked before using the new matrices there. Existing SBS-derived CHM13 opportunity tables do not provide indel opportunities.