Oncology Analytics troubleshooting

Oncology Analytics troubleshooting

This page helps you diagnose unexpected results across the oncology analytics 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 to confirm expected value ranges
4. Describe the issue to Ivy

Read next