Neoantigen Predictor

Source: https://github.com/aipoch/medical-research-skills

Neoantigen Predictor

Predicts patient-specific neoantigen candidate peptides with high immunogenicity based on HLA typing and tumor mutation profiles, providing target screening for tumor immunotherapy.

When to Use

• Use this skill when the task is to Predict neoantigens that may be recognized by the immune system based.
• Use this skill for data analysis tasks that require explicit assumptions, bounded scope, and a reproducible output format.
• Use this skill when you need a documented fallback path for missing inputs, execution errors, or partial evidence.

Key Features

• Scope-focused workflow aligned to: Predict neoantigens that may be recognized by the immune system based.
• Packaged executable path(s): scripts/main.py.
• Reference material available in references/ for task-specific guidance.
• Structured execution path designed to keep outputs consistent and reviewable.

Dependencies

Required:

• Python 3.8+
• biopython (sequence processing)
• pandas, numpy (data analysis)
• requests (API calls)

Optional (enhanced features):

• NetMHCpan 4.1 local installation (improved performance)
• samtools (VCF processing)
• matplotlib, seaborn (visualization)

Example Usage

See ## Usage above for related details.

cd "20260318/scientific-skills/Data Analytics/neoantigen-predictor"
python -m py_compile scripts/main.py
python scripts/main.py --help

Example run plan:

1. Confirm the user input, output path, and any required config values.
2. Edit the in-file CONFIG block or documented parameters if the script uses fixed settings.
3. Run python scripts/main.py with the validated inputs.
4. Review the generated output and return the final artifact with any assumptions called out.

Implementation Details

See ## Workflow above for related details.

• Execution model: validate the request, choose the packaged workflow, and produce a bounded deliverable.
• Input controls: confirm the source files, scope limits, output format, and acceptance criteria before running any script.
• Primary implementation surface: scripts/main.py.
• Reference guidance: references/ contains supporting rules, prompts, or checklists.
• Parameters to clarify first: input path, output path, scope filters, thresholds, and any domain-specific constraints.
• Output discipline: keep results reproducible, identify assumptions explicitly, and avoid undocumented side effects.

Quick Check

Use this command to verify that the packaged script entry point can be parsed before deeper execution.

python -m py_compile scripts/main.py

Audit-Ready Commands

Use these concrete commands for validation. They are intentionally self-contained and avoid placeholder paths.

python -m py_compile scripts/main.py
python scripts/main.py --help

Workflow

1. Confirm the user objective, required inputs, and non-negotiable constraints before doing detailed work.
2. Validate that the request matches the documented scope and stop early if the task would require unsupported assumptions.
3. Use the packaged script path or the documented reasoning path with only the inputs that are actually available.
4. Return a structured result that separates assumptions, deliverables, risks, and unresolved items.
5. If execution fails or inputs are incomplete, switch to the fallback path and state exactly what blocked full completion.

Function Overview

Neoantigens are variant peptides generated by non-synonymous mutations in tumor cells, which can be presented by the patient's own HLA molecules and recognized by T cells. This tool integrates the following analysis workflows:

1. Mutant Peptide Generation - Extract 8-11mer variant peptides from mutation sites
2. HLA Binding Prediction - Predict peptide binding affinity to patient HLA molecules
3. Immunogenicity Assessment - Assess potential to elicit immune response
4. Priority Ranking - Comprehensive scoring to screen optimal neoantigen candidates

Input Format

HLA Typing Input

Mutation Data Input

VCF Format Example:

#CHROM	POS	ID	REF	ALT	QUAL	FILTER	INFO
chr17	7579472	.	G	A	100	PASS	GENE=TP53;AA=p.R273H
chr13	32915005	.	C	T	100	PASS	GENE=BRCA2;AA=p.S1172L

Table Format:

FASTA Format (Variant Peptides):

>TP53_R273H_mut
GSDLWPGYFSH
>TP53_R273H_wt
GSDLWPGYFSP

Usage

Python API

from scripts.main import NeoantigenPredictor

# Initialize predictor
predictor = NeoantigenPredictor()

# Set patient HLA typing
hla_alleles = ["HLA-A*02:01", "HLA-A*11:01", "HLA-B*07:02"]

# Define mutation data
mutations = [
    {
        "gene": "TP53",
        "chrom": "chr17",
        "pos": 7579472,
        "ref": "G",
        "alt": "A",
        "protein_change": "p.R273H"
    }
]

# Predict neoantigens
results = predictor.predict(
    hla_alleles=hla_alleles,
    mutations=mutations,
    peptide_length=[9, 10],  # 9-10mer peptides
    mhc_method="netmhcpan"   # Use NetMHCpan prediction
)

# Get high-affinity neoantigens
high_affinity = predictor.filter_by_binding(results, rank_threshold=0.5)

Command Line Usage

# Basic prediction
python scripts/main.py \
  --hla "HLA-A*02:01,HLA-A*11:01,B*07:02" \
  --vcf mutations.vcf \
  --output neoantigen_results.json

# Use table format input
python scripts/main.py \
  --hla-file hla_genotype.txt \
  --mutations mutations.csv \
  --peptide-length 9,10,11 \
  --rank-cutoff 0.5 \
  --output results.json

# Predict HLA binding for existing variant peptides
python scripts/main.py \
  --hla "A*02:01" \
  --variant-peptides peptides.fasta \
  --wildtype-peptides wt_peptides.fasta \
  --output binding_predictions.csv

Output Format

{
  "patient_hla": ["HLA-A*02:01", "HLA-A*11:01", "HLA-B*07:02"],
  "prediction_method": "NetMHCpan 4.1",
  "total_predictions": 156,
  "strong_binders": 12,
  "neoantigens": [
    {
      "rank": 1,
      "mutation_id": "TP53_R273H",
      "gene": "TP53",
      "chromosome": "chr17",
      "position": 7579472,
      "ref_aa": "R",
      "alt_aa": "H",
      "hla_allele": "HLA-A*02:01",
      "peptide_sequence": "S DDLWPGYFSH",
      "peptide_length": 9,
      "mutant_position": 9,
      "mhc_binding": {
        "rank_percentile": 0.12,
        "affinity_nM": 34.5,
        "binding_level": "Strong",
        "core_peptide": "DLWPGYFSH",
        "anchor_residues": [2, 9]
      },
      "immunogenicity": {
        "foreignness_score": 0.87,
        "self_similarity": 0.23,
        "amino_acid_change": "R->H",
        "anchor_mutation": true,
        "hydrophobicity_change": -0.45
      },
      "priority_score": 0.92,
      "clinical_relevance": {
        "variant_allele_frequency": 0.42,
        "expression_level": "High",
        "clonality": "Clonal"
      }
    }
  ],
  "summary": {
    "top_candidates": 5,
    "binding_distribution": {
      "strong": 12,
      "weak": 44,
      "non_binder": 100
    }
  }
}

Scoring Algorithms

MHC Binding Affinity Prediction

Using NetMHCpan 4.1 algorithm to predict peptide binding to HLA molecules:

Immunogenicity Score

Immunogenicity Score = Σ(wi × fi)

Components:
1. Foreignness Score (w=0.30): Difference from wild-type protein
2. Anchor Mutation (w=0.25): Whether mutation is at HLA binding anchor position
3. Self-similarity (w=0.20): Similarity to self-antigen pool (lower is better)
4. Hydrophobicity Change (w=0.15): Magnitude of hydrophobicity change
5. Clonality (w=0.10): Tumor clonality (clonal mutation > subclonal)

Priority Score

priority_score = (
    binding_weight × (1 - rank_percentile) +
    immunogenicity_weight × immunogenicity_score +
    clinical_weight × clinical_score
)

# Weight configuration
weights = {
    'mhc_binding': 0.40,      # MHC binding affinity
    'immunogenicity': 0.35,   # Immunogenicity
    'clinical': 0.25          # Clinical relevance (expression, clonality)
}

HLA Support List

MHC Class I Molecules

• HLA-A: A01:01, A02:01, A02:03, A02:06, A03:01, A11:01, A23:01, A24:02, A26:01, A30:01, A30:02, A31:01, A32:01, A33:01, A68:01, A68:02
• HLA-B: B07:02, B08:01, B15:01, B27:05, B35:01, B40:01, B44:02, B44:03, B51:01, B53:01, B57:01, B58:01
• HLA-C: C03:03, C04:01, C05:01, C06:02, C07:01, C07:02, C08:02, C12:03, C14:02, C15:02

Mouse MHC (for preclinical research)

• H2-Db, H2-Kb, H2-Kd, H2-Ld

Technical Difficulty: HIGH

⚠️ AI Autonomous Acceptance Status: Manual review required

This skill involves complex immunoinformatics calculations:

• MHC binding prediction algorithms (NetMHCpan neural network)
• Peptide sequence processing and variant positioning
• Multi-dimensional immunogenicity assessment
• Large-scale parallel computing optimization
• Tumor genomics data integration

Data Dependencies

Algorithm Limitations

• MHC binding prediction accuracy: ~85% (Rank < 0.5 threshold)
• Immunogenicity prediction requires experimental validation, correlation ~60-70%
• Does not consider HLA molecule expression levels on cell surface
• Cannot predict immune tolerance or suppressive T cell responses
• Uncertainty in the correlation between neoantigen generation and T cell response