---
title: Oncology Analytics troubleshooting
description: >-
  Resolve threshold interpretation issues, input format errors, and unexpected
  results.
tags:
  - oncology
  - troubleshooting
---

## Oncology Analytics troubleshooting

This page helps you diagnose unexpected results across the [oncology analytics](/docs/oncology) tools — low TMB values, MSI results that disagree with IHC, MHC and neoantigen predictions that look wrong, and jobs that time out on large inputs.

## TMB calculation returns zero or very low values

**Symptom**: TMB is 0 or near 0 despite providing mutation data.

**Fixes**:

- Check that the `panel_size_mb` parameter matches your sequencing panel. An incorrect panel size will produce wrong normalization
- Verify that mutations include coding region variants. Set `coding_only: false` temporarily to check if mutations are only in non-coding regions
- Check the `min_vaf` threshold. The default is 0.05 (5%). Lowering this may capture more low-frequency variants
- Ensure the `min_depth` threshold is not filtering out all variants. Lower it from the default of 20 if your sequencing depth is low
- For VCF input, confirm that the file contains the FILTER column and that variants are marked as PASS

## MSI status disagrees with IHC results

**Symptom**: Computational MSI status differs from immunohistochemistry (IHC) for mismatch repair proteins.

**Explanation**: MSI testing and IHC measure different aspects of mismatch repair deficiency. IHC detects protein loss, while MSI evaluates microsatellite repeat instability. Discordance occurs in approximately 5-10% of cases.

**Fixes**:

- IHC-positive/MSI-stable: The protein may be present but non-functional (missense mutations). Computational MSI is more specific in this case
- IHC-negative/MSI-stable: The gene may be silenced without causing detectable microsatellite instability. Consider re-running with more microsatellite loci
- Ensure sufficient microsatellite sites are evaluated (at least 40-50 loci). Targeted panels with few microsatellite markers have lower sensitivity

## MHC binding predictions seem incorrect

**Symptom**: Known immunogenic peptides predicted as non-binders, or vice versa.

**Fixes**:

- Verify HLA allele nomenclature. Use four-digit resolution (e.g., `HLA-A*02:01` not `HLA-A2`). Incorrect allele specification produces wrong binding predictions
- Check peptide length matches the MHC class. Class I requires 8-11mers; class II requires 13-25mers. Peptides outside these ranges will not bind
- MHC binding prediction has inherent false positive and false negative rates of approximately 5-15%. A peptide predicted as non-binding may still elicit immune responses through alternative mechanisms
- Try both available methods (`netmhcpan` and `mhcflurry`). Consensus between methods increases confidence
- Note that binding affinity alone does not guarantee immunogenicity. T cell recognition depends on additional factors (processing, stability, TCR repertoire)

## Neoantigen prediction returns no candidates

**Symptom**: Zero neoantigens passing filters despite providing mutations.

**Fixes**:

- Lower the `binding_threshold` from 500 nM to 1000 nM to include weaker binders
- If expression filtering is removing all candidates, set `min_expression: 0` to see all binding predictions regardless of expression
- Check that HLA alleles are specified correctly. Incorrect alleles produce no strong binding predictions
- Verify that input mutations are coding mutations that produce amino acid changes. Synonymous and non-coding variants do not generate neoantigens
- Some tumor types (e.g., pediatric tumors) have very few somatic mutations and may produce few or no neoantigen candidates. This is biologically expected

## Job times out or fails on large inputs

**Symptom**: "Timeout" or "Out of memory" error for large VCF files.

**Fixes**:

- For VCF files with >100,000 variants, consider pre-filtering to coding regions before submission
- Neoantigen prediction with many mutations and many HLA alleles can be computationally expensive. Reduce peptide lengths to `[9]` only for an initial scan
- If the job fails repeatedly, try splitting the input into smaller batches (e.g., by chromosome)

## Getting help

If issues persist:

1. Check the tool error message for specific suggestions
2. Verify your input format matches the expected specifications
3. Review the clinical thresholds in the [overview](/docs/oncology) to confirm expected value ranges
4. Describe the issue to Ivy

## Read next