NeoHeadHunter

NeoHeadHunter (NHH, nhh) is a neoantigen prioritization pipeline. NHH uses state-of-the-art bioinformatics sofware packages and neoantigen-prioritization algorithms. NHH is able to accurately rank neoantigen candidates. Additionally, NHH is able to estimate the probability that each neoantigen candidate is immunogenic (i.e., true positive).

How to install

First, follow the instruction at https://bioconda.github.io/ to install bioconda if you haven't done so.

Then, run the following commands:

# If the working directory is not neoheadhunter, then change it to neoheadhunter
sh -evx install-step-1-by-conda.sh nhh # install all dependencies by conda
conda run -n hhh sh install-step-2.sh # download databases and build database indexes

If the "$conda install" command in install-step-1-by-conda.sh ran into any error, you can try replacing this command by each of the following commands:

conda create     --name nhh --file env/requirements.list_e_no_pypi.txt    # if this command does not work then try the next one below
conda env create --name nhh --file env/freeze.env_export.yml              # if this command does not work then try the next one below
conda env create --name nhh --file env/freeze.env_export_no_builds.yml    # if this command does not work then try the next one below
conda env create --name nhh --file env/freeze.env_export_from_history.yml

Next, you have to manually set up netMHCpan, netMHCstabpan and MixCR (due to their licensing requirements). Please refer to https://services.healthtech.dtu.dk/services/NetMHC-4.0/ and https://services.healthtech.dtu.dk/services/NetMHCstabpan-1.0/ . For how to manually download, install and activate netMHCpan and netMHCstabpan. After doing so, please set the full paths of netMHCpan and netMHCstabpan in the config.ini file accordingly. Please obtain a license for MixCR from https://licensing.milaboratories.com/ and then run the command software/mixcr activate-license to activate MixCR.

Last but no the least, please be aware that UVC, netMHCpan, netMHCstabpan and MixCR are free for academic use but require commercial licensing for for-profit use.

How to run

Example shell command to run NeoHeadHunter on FASTQ files as input:

# If the working directory is not neoheadhunter, then change it to neoheadhunter
conda run -n hhh snakemake --configfile config.yaml --config \
		res=/mnt/d/TESLA/snake-out/patient01.outdir prefix=patient01 \
		dna_tumor_fq1=/mnt/d/TESLA/TESLA_1_1.fastq.gz \
		dna_tumor_fq2=/mnt/d/TESLA/TESLA_1_2.fastq.gz \
		dna_normal_fq1=/mnt/d/TESLA/TESLA_2_1.fastq.gz \
		dna_normal_fq2=/mnt/d/TESLA/TESLA_2_2.fastq.gz \
		rna_tumor_fq1=/mnt/d/TESLA/TESLA_3_1.fastq.gz \
		rna_tumor_fq2=/mnt/d/TESLA/TESLA_3_2.fastq.gz \
		--resources mem_mb=960000 --cores 24

After a successful run, you should be able check neoantigen prioritization results at: /mnt/d/TESLA/snake-out/patient01.outdir/prioritization/patient01_neoantigen_rank_neoheadhunter.tsv

Example shell command to run NeoHeadHunter on a peptide FASTA file and a string of HLA alleles as input:

snakemake --configfile config.yaml --config \
    res=/tmp/pMHCinput prefix=pMHCinput \
    dna_tumor_fq1=/ dna_tumor_fq2=/ dna_normal_fq1=/ dna_normal_fq2=/ rna_tumor_fq1=/ rna_tumor_fq2=/ \
    comma_sep_hla_list='HLA-A01:01,HLA-A02:01' all_vars_peptide_faa=/mnt/d/TESLA/nhh-extra-4.1/TESLA-fig7_4.outdir/pmhcs/TESLA-fig7_4_all_peps.fasta \
    --cores 4 Prioritization_with_all_TCRs_with_minimal_varinfo

where the TESLA-fig7_4_all_peps.fasta file contains

>SNV_D0_B0 WT=ARDPHSGHFV MT=ALDPHSGHFV TPM=145.492026549908 SOURCE=...ARDPHSGHFV... MAX_BIT_DIST=0
ALDPHSGHFV
>SNV_D0_A WT=ARDPHSGHFV MT=ALDPHSGHFV TPM=145.492026549908
ARDPHSGHFV
>SNV_D1_B0 WT=ALGPGVPHI MT=ALSPVIPHI TPM=6.306862689603 SOURCE=...ALGPGVPHI... MAX_BIT_DIST=0
ALSPVIPHI
>SNV_D1_A WT=ALGPGVPHI MT=ALSPVIPHI TPM=6.306862689603
ALGPGVPHI
>SNV_D2_B0 WT=ALIHFLMIL MT=AMVHYLMIL TPM=0.259926390800257 SOURCE=...ALIHFLMIL... MAX_BIT_DIST=0
AMVHYLMIL

as its first ten lines. The MT tag specifies the mutant-type peptide and is required for each peptide record. The WT tag specifies the wild-type peptide and is optional. All other tags (such as TPM denoting transcript-per-million) are also optional. Each peptide sequence specified by the MT or WT tag must occurs exactly once in the sequences of the input peptide FASTA file.

For advanced usage of the Snakefile, please refer to https://snakemake.readthedocs.io/en/stable/

Trouble-shooting

If you have encountered an error with conda, please show us the full error log generated by conda. If you have encountered an error with snakemake, please show us the full stdout and stderr generated by snakemake. Most of the third-party tools that this pipeline uses were not developed by us, so we are not guaranteed to find the root causes of the errors that are specific to these tools.