MHCflurry

https://openvax.github.io/mhcflurry
Admin
MHCflurry predicts MHC class I peptide binding affinity, antigen processing, and presentation for...
Tokens:10,906
Snippets:172
Trust Score:9.7
Update:1 month ago
Show doc for...
Tokens:
Raw
### Compare models

Source: https://openvax.github.io/mhcflurry/_sources/evaluation.md.txt

Compares a candidate run with installed public models.

```shell
mhcflurry eval compare-models \
    --a results/new_run \
    --b public \
    --out results/new_run/eval_comparison
```

--------------------------------

### Unified command-line interface mapping

Source: https://openvax.github.io/mhcflurry/configuration.html

Examples of mapping legacy command names to the unified MHCflurry 2.3.0 entry point syntax.

```bash
mhcflurry-predict                       = mhcflurry predict
mhcflurry-downloads fetch              = mhcflurry downloads fetch
mhcflurry-class1-train-pan-allele-models = mhcflurry class1-train-pan-allele-models
```

--------------------------------

### Install via Conda

Source: https://openvax.github.io/mhcflurry/_sources/intro.md.txt

Sets up a dedicated conda environment and installs MHCflurry within it.

```shell
conda create -q -n mhcflurry-env python=3.10
conda activate mhcflurry-env
pip install --pre mhcflurry
mhcflurry downloads fetch models_class1_presentation
```

--------------------------------

### Fetch curated training data

Source: https://openvax.github.io/mhcflurry/_sources/training.md.txt

Downloads the curated dataset required for training examples.

```shell
mhcflurry downloads fetch data_curated
```

--------------------------------

### Install MHCflurry

Source: https://openvax.github.io/mhcflurry/_sources/intro.md.txt

Installs the MHCflurry package using pip. Use the --pre flag to include prerelease versions.

```shell
pip install --upgrade --pre mhcflurry
```

--------------------------------

### Display training pipeline help

Source: https://openvax.github.io/mhcflurry/maintainers.html

Access the command-line interface help for the pan-allele release training process.

```bash
mhcflurry train pan-allele-release --help
```

--------------------------------

### Run full verification suite

Source: https://openvax.github.io/mhcflurry/_sources/testing.md.txt

Execute linting and the entire test suite before finalizing changes.

```shell
$ ./lint.sh
$ python -m pytest test/
```

--------------------------------

### Access training command help

Source: https://openvax.github.io/mhcflurry/_sources/training.md.txt

Displays help documentation for pan-allele and release training commands.

```shell
mhcflurry class1-train-pan-allele-models --help
mhcflurry train pan-allele-release --help
```

--------------------------------

### Source development environment

Source: https://openvax.github.io/mhcflurry/_sources/testing.md.txt

Initialize the development environment before running tests.

```shell
$ source develop.sh
```

--------------------------------

### Activate Development Environment

Source: https://openvax.github.io/mhcflurry/_sources/development.md.txt

Source the develop.sh script to create and activate an editable virtual environment for development.

```shell
source develop.sh
```

--------------------------------

### Download pretrained models

Source: https://openvax.github.io/mhcflurry/_sources/intro.md.txt

Fetches the required class I presentation models, which include binding-affinity and antigen-processing components.

```shell
mhcflurry downloads fetch models_class1_presentation
```

--------------------------------

### Display MHCflurry train pan-allele-release help

Source: https://openvax.github.io/mhcflurry/_sources/commandline_tools.md.txt

View help documentation for the pan-allele-release training subcommand.

```console
$ mhcflurry train pan-allele-release --help
```

--------------------------------

### Run lint and focused unit tests

Source: https://openvax.github.io/mhcflurry/_sources/testing.md.txt

Execute linting and specific unit tests for rapid iteration.

```shell
$ ./lint.sh
$ python -m pytest -q test/test_amino_acid.py test/test_random_negative_peptides.py
```

--------------------------------

### Display MHCflurry train help

Source: https://openvax.github.io/mhcflurry/_sources/commandline_tools.md.txt

View the available subcommands for the training workflow.

```console
$ mhcflurry train --help
```

--------------------------------

### Download MHCflurry models

Source: https://openvax.github.io/mhcflurry/commandline_tutorial.html

Fetches the presentation bundle containing binding-affinity and antigen-processing components.

```bash
$ mhcflurry downloads fetch models_class1_presentation
```

--------------------------------

### Run paper-style figures

Source: https://openvax.github.io/mhcflurry/_sources/evaluation.md.txt

Composes comparison, diagnostics, and paper panels for a trained model.

```shell
mhcflurry eval paper-figures run \
    --a results/new_run \
    --b public \
    --out results/new_run/eval_comparison
```

--------------------------------

### Locate model data directory

Source: https://openvax.github.io/mhcflurry/commandline_tutorial.html

Displays the file system path where the specified model bundle is stored.

```bash
$ mhcflurry downloads path models_class1_presentation
/home/runner/work/mhcflurry/mhcflurry/.mhcflurry-data/2.2.0/models_class1_presentation/
```

--------------------------------

### Evaluate and compare trained models

Source: https://openvax.github.io/mhcflurry/commandline_tutorial.html

Compare a custom model against a released predictor and generate diagnostic plots.

```bash
$ mhcflurry eval compare-models \
    --a results/new_run/ \
    --b public \
    --out results/new_run/eval_comparison/

$ mhcflurry eval plot-comparison \
    --input results/new_run/eval_comparison/ \
    --summary-pdf results/new_run/eval_comparison/plots/model_comparison_figures.pdf
```

--------------------------------

### Run allele-specific training

Source: https://openvax.github.io/mhcflurry/_sources/training.md.txt

Executes the training process using the specified hyperparameters and curated data.

```shell
mhcflurry class1-train-allele-specific-models \
    --data "$(mhcflurry downloads path data_curated)/curated_training_data.csv.bz2" \
    --hyperparameters hyperparameters.yaml \
    --allele 'HLA-A*02:01' \
    --min-measurements-per-allele 75 \
    --out-models-dir models
```

--------------------------------

### Fetch and use historical allele-specific models

Source: https://openvax.github.io/mhcflurry/commandline_tutorial.html

Downloads the legacy model bundle and executes a prediction command using the specified model directory.

```bash
$ mhcflurry downloads fetch models_class1
$ mhcflurry predict \
    --alleles HLA-A0201 HLA-A0301 \
    --peptides SIINFEKL SIINFEKD SIINFEKQ \
    --models "$(mhcflurry downloads path models_class1)/models" \
    --out /tmp/predictions.csv
```

--------------------------------

### Display MHCflurry eval help

Source: https://openvax.github.io/mhcflurry/_sources/commandline_tools.md.txt

View the available subcommands for model evaluation and figure generation.

```console
$ mhcflurry eval --help
```

--------------------------------

### Run training internal tests

Source: https://openvax.github.io/mhcflurry/_sources/testing.md.txt

Execute tests targeting specific training-related files.

```shell
$ python -m pytest -q test/test_class1_affinity_training_data.py
$ python -m pytest -q test/test_pytorch_regressions.py
$ python -m pytest -q test/test_train_pan_allele_models_command.py::test_pretrain_network_input_iterator_compact_torch_indices
```

--------------------------------

### Render diagnostic plots

Source: https://openvax.github.io/mhcflurry/_sources/evaluation.md.txt

Generates diagnostic plots and a combined PDF from comparison results.

```shell
mhcflurry eval plot-comparison \
    --input results/new_run/eval_comparison \
    --summary-pdf results/new_run/eval_comparison/plots/model_comparison_figures.pdf
```

--------------------------------

### Run a prediction

Source: https://openvax.github.io/mhcflurry/_sources/intro.md.txt

Executes a prediction for specified alleles and peptides, saving the results to a CSV file.

```shell
mhcflurry predict \
    --alleles HLA-A0201 HLA-A0301 \
    --peptides SIINFEKL SIINFEKD SIINFEKQ \
    --out predictions.csv
```

--------------------------------

### Load MHCflurry Predictor

Source: https://openvax.github.io/mhcflurry/_sources/python_tutorial.md.txt

Initialize the Class1PresentationPredictor using the default release model.

```python
>>> from mhcflurry import Class1PresentationPredictor
>>> predictor = Class1PresentationPredictor.load()
>>> predictor.supported_alleles[:5]
['Atbe-B*01:01', 'Atbe-E*03:01', 'Atbe-G*03:01', 'Atbe-G*03:02', 'Atbe-G*06:01']
```

--------------------------------

### Run broad fast test tier

Source: https://openvax.github.io/mhcflurry/_sources/testing.md.txt

Execute tests while excluding slow integration, cached-bundle, or benchmark checks.

```shell
$ python -m pytest -q test -m "not slow and not downloads"
```

--------------------------------

### Identify slowest tests

Source: https://openvax.github.io/mhcflurry/_sources/testing.md.txt

Analyze test execution times to debug performance issues.

```shell
$ python -m pytest -q test --durations=25 --durations-min=0.5
```

--------------------------------

### Score predictions

Source: https://openvax.github.io/mhcflurry/_sources/evaluation.md.txt

Derives reusable AUC and PPV score tables from benchmark predictions.

```shell
mhcflurry eval paper-figures score-predictions \
    --kind multiallelic \
    --input benchmark.multiallelic.csv.bz2 \
    --out accuracy_scores.multiallelic.csv
```

--------------------------------

### Predict for Multiple Sample Genotypes

Source: https://openvax.github.io/mhcflurry/_sources/python_tutorial.md.txt

Perform predictions across multiple named sample genotypes by passing a dictionary of alleles.

```python
>>> predictions = predictor.predict(
...     peptides=["KSEYMTSWFY", "NLVPMVATV"],
...     alleles={
...        "sample1": ["A0201", "A0301", "B0702", "B4402", "C0201", "C0702"],
...        "sample2": ["A0101", "A0206", "B5701", "C0202"],
...     },
...     verbose=0)
>>> [(row.sample_name, row.peptide, str(row.best_allele))
...  for row in predictions.itertuples()]
[('sample1', 'KSEYMTSWFY', 'C0201'), ('sample1', 'NLVPMVATV', 'A0201'), ('sample2', 'KSEYMTSWFY', 'A0101'), ('sample2', 'NLVPMVATV', 'A0206')]
```

--------------------------------

### Scan protein sequences for MHC I ligands

Source: https://openvax.github.io/mhcflurry/commandline_tutorial.html

Use the predict-scan command to score peptide windows in a FASTA file against specific alleles.

```text
>protein1
MSSSSTPVCPNGPGNCQV
>protein2
MVENKRLLEGMEMIFGQVIPGA
```

```bash
$ mhcflurry predict-scan example.fasta \
    --alleles HLA-A*02:01 \
    --threshold-affinity 100
```

--------------------------------

### Display prediction results

Source: https://openvax.github.io/mhcflurry/_sources/commandline_tutorial.md.txt

Outputs the contents of the generated predictions CSV file.

```shell
cat /tmp/predictions.csv
```

--------------------------------

### Define model hyperparameters

Source: https://openvax.github.io/mhcflurry/_sources/training.md.txt

A YAML configuration defining a four-member ensemble architecture for allele-specific training.

```yaml
- activation: tanh
  dropout_probability: 0.0
  early_stopping: true
  layer_sizes: [8]
  locally_connected_layers: []
  loss: custom:mse_with_inequalities
  max_epochs: 500
  minibatch_size: 16384
  n_models: 4
  output_activation: sigmoid
  patience: 20
  peptide_amino_acid_encoding: BLOSUM62
  random_negative_affinity_max: 50000.0
  random_negative_affinity_min: 20000.0
  random_negative_constant: 25
  random_negative_rate: 0.0
  validation_split: 0.1
```

--------------------------------

### View prediction results

Source: https://openvax.github.io/mhcflurry/commandline_tutorial.html

Displays the contents of the generated CSV file containing affinity and presentation scores.

```bash
$ cat /tmp/predictions.csv
allele,peptide,mhcflurry_affinity,mhcflurry_affinity_percentile,mhcflurry_processing_score,mhcflurry_presentation_score,mhcflurry_presentation_percentile
HLA-A0201,SIINFEKL,11927.164294664875,6.296000000000002,0.26470962166786194,0.020690202037635795,11.6303260869565
HLA-A0201,SIINFEKD,30039.7732437649,41.398,0.024963298812508583,0.00367440114530976,99.28660326086957
HLA-A0201,SIINFEKQ,28026.90603463826,30.226250000000004,0.0615493506193161,0.004470086908147677,62.74467391304348
HLA-A0301,SIINFEKL,29871.588371336024,23.19225,0.26470959186553955,0.00858619019343956,27.61739130434782
HLA-A0301,SIINFEKD,33158.80995716571,62.27625,0.024963300675153732,0.003339329916496058,99.28660326086957
HLA-A0301,SIINFEKQ,29705.410284325066,21.8915,0.0615493506193161,0.004225575360616951,62.74467391304348
```

--------------------------------

### Scan protein sequences for MHC ligands

Source: https://openvax.github.io/mhcflurry/_sources/python_tutorial.md.txt

Uses predict_sequences to identify peptides with specific binding affinity thresholds across multiple genotypes.

```python
>>> scan = predictor.predict_sequences(
...    sequences={
...        'protein1': "MDSKGSSQKGSRLLLLLVVSNLL",
...        'protein2': "SSLPTPEDKEQAQQTHH",
...    },
...    alleles={
...        "sample1": ["A0201", "A0301", "B0702"],
...        "sample2": ["A0101", "C0202"],
...    },
...    result="filtered",
...    comparison_quantity="affinity",
...    filter_value=500,
...    verbose=0)
>>> len(scan)
10
>>> bool(scan.affinity.le(500).all())
True
>>> scan[["sequence_name", "peptide", "best_allele"]].head(2).to_dict("records")
[{'sequence_name': 'protein1', 'peptide': 'LLLVVSNLL', 'best_allele': 'A0201'}, {'sequence_name': 'protein1', 'peptide': 'LLLLVVSNL', 'best_allele': 'A0201'}]
```

--------------------------------

### Orchestrator and Worker Process Control Flow

Source: https://openvax.github.io/mhcflurry/orchestrator.html

Visual representation of the division of labor between the orchestrator process and training worker processes.

```text
orchestrator process               training worker process
─────────────────────              ───────────────────────

parse args                         (forked / spawned)
load training data                  receive WORKER_CONTEXT once
build WORKER_CONTEXT        ─┐
                             │
hoist env knobs              │
  TORCHINDUCTOR_COMPILE_THREADS
                             │
start worker pool            ─┘
                                    fit() builds device-resident
                                      AffinityDeviceTrainingData
                                      (peptide/allele/y/weights and
                                      random-negative slice live on
                                      the active torch device)
collect results  ◀──────────────────  return predictor
```

--------------------------------

### Predict binding affinities directly

Source: https://openvax.github.io/mhcflurry/_sources/python_tutorial.md.txt

Uses Class1AffinityPredictor to obtain binding affinity predictions and ensemble confidence intervals for specific peptides.

```python
>>> from mhcflurry import Class1AffinityPredictor
>>> predictor = Class1AffinityPredictor.load()
>>> affinities = predictor.predict_to_dataframe(
...     allele="HLA-A0201", peptides=["SIINFEKL", "SIINFEQL"])
>>> affinities[["peptide", "allele"]].to_dict("records")
[{'peptide': 'SIINFEKL', 'allele': 'HLA-A*02:01'}, {'peptide': 'SIINFEQL', 'allele': 'HLA-A*02:01'}]
>>> bool(((affinities.prediction_low < affinities.prediction) &
...       (affinities.prediction < affinities.prediction_high)).all())
True
```

--------------------------------

### Predict with Flanking Sequences

Source: https://openvax.github.io/mhcflurry/_sources/python_tutorial.md.txt

Include N-flank and C-flank sequences to improve the accuracy of processing and presentation predictions.

```python
>>> predictions = predictor.predict(
...     peptides=["KSEYMTSWFY", "NLVPMVATV"],
...     n_flanks=["NNNNNNN", "SSSSSSSS"],
...     c_flanks=["CCCCCCCC", "YYYAAAA"],
...     alleles={
...        "sample1": ["A0201", "A0301", "B0702", "B4402", "C0201", "C0702"],
...        "sample2": ["A0101", "A0206", "B5701", "C0202"],
...     },
...     verbose=0)
>>> predictions[["n_flank", "c_flank"]].drop_duplicates().to_dict("records")
[{'n_flank': 'NNNNNNN', 'c_flank': 'CCCCCCCC'}, {'n_flank': 'SSSSSSSS', 'c_flank': 'YYYAAAA'}]
>>> predictions.presentation_score.round(2).tolist()
[0.1, 0.96, 0.9, 0.95]
```

--------------------------------

### Predict Peptide Presentation

Source: https://openvax.github.io/mhcflurry/_sources/python_tutorial.md.txt

Generate binding affinity and presentation scores for a list of peptides against a specific MHC I genotype.

```python
>>> predictions = predictor.predict(
...     peptides=["SIINFEKL", "NLVPMVATV"],
...     alleles=["HLA-A0201", "HLA-A0301"],
...     verbose=0)
>>> [(row.peptide, str(row.best_allele)) for row in predictions.itertuples()]
[('SIINFEKL', 'HLA-A0201'), ('NLVPMVATV', 'HLA-A0201')]
>>> predictions.presentation_score.round(2).tolist()
[0.02, 0.97]
```

--------------------------------

### Predict peptide scores

Source: https://openvax.github.io/mhcflurry/commandline_tutorial.html

Scores peptides against specified alleles and saves the results to a CSV file.

```bash
$ mhcflurry predict --alleles HLA-A0201 HLA-A0301 --peptides SIINFEKL SIINFEKD SIINFEKQ --out /tmp/predictions.csv
Predicting processing.
Predicting affinities.
```

--------------------------------

### Predict peptide binding affinity

Source: https://openvax.github.io/mhcflurry/_sources/commandline_tutorial.md.txt

Scores specific peptides against provided alleles and saves the results to a CSV file.

```shell
mhcflurry predict --alleles HLA-A0201 HLA-A0301 --peptides SIINFEKL SIINFEKD SIINFEKQ --out /tmp/predictions.csv
```
Tokens:
Raw