Patient Harmonic-mean Best Rank (PHBR) - version 0.2.4-beta ============================================================================================ Introduction ------------ This package (**PHBR**) computes Patient Harmonic-mean Best Rank scores for neoepitopes. Given a list of peptides and a set of HLA alleles for a single patient, each peptide is run through MHC class I and/or class II binding predictions and scored according to the harmonic mean of their ranks across the panel of alleles. Release Notes ------------- v0.2.4 Refactored from previous version to increase stability. Minor result table format change. Prerequisites ------------- - Python 3.10 or higher http://www.python.org/ - External Tcell Class I and/or Class II prediction tools (paths configured in paths.py) Installation ------------ Below, we use the example of installing to ~/iedb_tools. 1. Extract the code and change directory: mkdir ~/iedb_tools tar -xvzf IEDB_NG_PHBR-0.2.4-beta.tar.gz -C ~/iedb_tools cd ~/iedb_tools/ng_phbr-0.2.4-beta 2. (Optional) Create and activate a Python 3.10+ virtual environment. Example using venv: python3 -m venv ~/venvs/phbr source ~/venvs/phbr/bin/activate 3. Install Python requirements: pip3 install --upgrade pip pip3 install -r requirements.txt 4. Run the configure script to set up path variables: ./configure Note: This script creates a .env file in the project root, which is critical for the application to function correctly. 5. Edit paths.py to set the paths to external Tcell Class I and Class II tools: tcell_class_i_path = "/path/to/tcell-class-i" tcell_class_ii_path = "/path/to/tcell-class-ii" Optional settings include virtual environment paths, environment module names, and LD_LIBRARY_PATH overrides for each tool. Quick Start ----------- The simplest way to run a prediction: # Using a JSON configuration file: python3 src/run_phbr.py predict -j examples/json/mhci/pep-seq.json -o result -f json # Using a JSON file with TSV output (default): python3 src/run_phbr.py predict -j examples/json/mhci/pep-seq.json -o result For help on any command: python3 src/run_phbr.py --help Basic Usage - Predict Command ------------------------------ The predict command computes PHBR scores for each peptide. It accepts a JSON configuration file specifying input data, alleles, and prediction method. python3 src/run_phbr.py predict -j examples/json/mhci/pep-seq.json -o result -f json python3 src/run_phbr.py predict -j examples/json/combined/neo-multilocus.json -o result -d /tmp Predict Command Arguments -------------------------- Required: -j, --input-json Path to JSON configuration file Optional: -o, --output-prefix Output file prefix (e.g., result) -f, --output-format Output format: tsv (default) or json -d, --output-dir Output directory (default: /tmp) Advanced Usage - Distributed Processing --------------------------------------- For processing large inputs, you can use a three-step workflow that allows distributed processing: 1. Preprocess: Split input into job units python3 src/run_phbr.py preprocess -j examples/json/mhci/pep-seq.json -o output-directory This creates individual parameter files in predict-inputs/params/ and a job_descriptions.json file listing all jobs to be executed. Options: --include-mhci-mhcii-result Include MHC I & II peptide tables in job descriptions 2. Predict: Run each command listed in job_descriptions.json. These jobs can be distributed across multiple machines, or run sequentially with the included job runner: python3 jd_runner.py output-directory/job_descriptions.json 3. Postprocess: Aggregate results python3 src/run_phbr.py postprocess --job-desc-file=output-directory/job_descriptions.json -o output-directory/final-result -f json Options: --job-desc-file Path to job_descriptions.json file (required) -o, --output-prefix Output file prefix (e.g., output-directory/final-result) -f, --output-format Output format: json (default: json) --include-mhci-mhcii-result Include MHC I & II peptide tables in aggregated output Example Files (examples/) ------------------------- Example inputs are organized by MHC class: examples/json/mhci/ MHC class I JSON inputs examples/json/mhcii/ MHC class II JSON inputs examples/json/combined/ Combined class I + II JSON inputs examples/tsv/ TSV input files referenced by JSON configs Naming convention for example JSON configs: - pep-seq.json Peptide + sequence table input - pep-seq-mutcol.json Peptide + sequence with mutation column - seq-mutpos-all.json Sequence table with mutation positions - mutref-tsv.json Mutation vs reference peptide table - neo-multilocus.json Neoepitopes with multi-locus alleles - neo-mutref.json Neoepitopes with mutation vs reference - uri-homo.json Binding result URI with homozygous loci - uri-mutpos.json Binding result URI with mutation positions JSON Input Format ----------------- JSON input files specify the input data, MHC classes, alleles, and prediction methods. A file may include class_i, class_ii, or both sections. Example 1: MHC class I with peptide and sequence tables { "mhc_peptide_tsv": "examples/tsv/mhci-pep-bind.tsv", "mhc_sequence_tsv": "examples/tsv/mhci-seq-names.tsv", "class_i": { "prediction_method": { "method": "netmhcpan_el" } } } Example 2: MHC class I with alleles and mutation table { "mhc_sequence_tsv": "examples/tsv/mhci-mutref.tsv", "class_i": { "prediction_method": { "method": "netmhcpan_el" }, "alleles": { "A": "HLA-A*01:01", "C": "HLA-C*02:02" } } } Example 3: Combined class I + II with neoepitopes { "class_i": { "alleles": { "A": "HLA-A*02:01,HLA-A*01:02", "B": "HLA-B*07:02,HLA-B*07:03", "C": "HLA-C*06:02,HLA-C*06:04" }, "prediction_method": { "method": "netmhcpan_el" } }, "class_ii": { "alleles": { "DPA": "HLA-DPA1*01:03", "DPB": "HLA-DPB1*03:01,HLA-DPB1*04:02", "DQA": "HLA-DQA1*01:01", "DQB": "HLA-DQB1*02:01,HLA-DQB1*06:32", "DRB": "HLA-DRB1*01:01,HLA-DRB1*01:15" }, "prediction_method": { "method": "netmhciipan_el-4.3" } }, "input_neoepitopes": "peptide\tmutation_postion\nDDESKQNFHFLYRGH\t5\n..." } Example 4: Binding result URI { "mhc_result_uri": "https://api-nextgen-tools.iedb.org/api/v1/results/", "class_i": { "homozygous_loci": "A,C" } } JSON Field Descriptions ------------------------ - mhc_sequence_tsv Path to a TSV file containing sequences. Columns may include: sequence, peptide, mutation_position, mut_peptide, ref_peptide. Required for sequence table and peptide sequence table input categories. - mhc_peptide_tsv Path to a TSV file containing peptide binding data. Used in combination with mhc_sequence_tsv for peptide sequence table inputs. - input_neoepitopes Inline TSV string with neoepitope data. Must include a header row with at minimum a "peptide" column. May include "mutation_postion" column. - mhc_result_uri URL to a pre-computed binding result from the IEDB API. - mhc_aggregated_result Pre-aggregated binding result data. - class_i / class_ii Per-class configuration sections. Each may contain: - alleles Object with locus keys mapping to comma-separated allele strings. Class I loci: A, B, C Class II loci: DRB, DPA, DPB, DQA, DQB - prediction_method Object with "method" key specifying the binding prediction method (e.g., "netmhcpan_el", "netmhciipan_el-4.3"). - homozygous_loci Comma-separated locus names to treat as homozygous (e.g., "A,C"). Input Categories ----------------- The tool automatically detects the input category based on which fields are present in the JSON: - NEOEPITOPES_STRING input_neoepitopes field present - MHC_SEQUENCE_TABLE mhc_sequence_tsv only (no mhc_peptide_tsv) - PEPTIDE_SEQUENCE_TABLE both mhc_peptide_tsv and mhc_sequence_tsv - BINDING_RESULT_URI mhc_result_uri field present - AGGREGATED_BINDING_RESULT mhc_aggregated_result field present Output Format ------------- The tool generates output with the following JSON structure: { "warnings": [], "results": [ { "result_type": "peptide_table", "table_columns": ["col1", "col2", ...], "table_data": [[...], [...], ...] } ] } Output files are saved to the path specified by -o with the format extension appended. For distributed processing workflows, intermediate results are stored in the predict-outputs/ subdirectory. Caveats ------- All IEDB next-generation standalone tools are developed primarily to support the website. Some user-facing features may be limited but will improve as the tools mature. Contact ------- Please contact us with any issues or questions using the channels below: IEDB Help Desk: https://help.iedb.org/ Email: help@iedb.org