Merge branch 'develop' into 'master'

Release 1.1.0

See merge request tron/addannot!259

.gitlab-ci.yml

@@ -18,7 +18,7 @@
 ## along with this program. If not, see <http://www.gnu.org/licenses/>.##
 
 # this image contains multiple Python interpreters
-image: fkrull/multi-python:bionic
+image: python:3.8.14-buster
 
 # Change pip's cache directory to be inside the project directory since we can
 # only cache local items.
@@ -27,7 +27,6 @@ variables:
 
 # Pip's cache doesn't store the python packages
 # https://pip.pypa.io/en/stable/reference/pip_install/#caching
-#
 # If you want to also cache the installed packages, you have to install
 # them in a virtualenv and cache it as well.
 cache:

MANIFEST.in

@@ -1,16 +1,12 @@
-include neofox/published_features/neoag/neoag-master/*
 include neofox/published_features/self_similarity/BLOSUM62-2.matrix.txt
 include neofox/published_features/Tcell_predictor/amino-acids-features.pickle
 include neofox/published_features/Tcell_predictor/genes-expression.pickle
 include neofox/published_features/Tcell_predictor/SIRdata.mat
 include neofox/published_features/Tcell_predictor/Classifier.pickle
 include neofox/references/install_r_dependencies.R
 include neofox/references/h2_database_allele_list.csv
-include neofox/published_features/hex/BLOSUM62.rda
-include neofox/published_features/hex/EPItOMe_modified.R
-include neofox/published_features/hex/hex.R
 include neofox/expression_imputation/tcga_cohort_code.tab
 include neofox/expression_imputation/tcga_exp_summary_modified.tab.gz.tbi
 include neofox/expression_imputation/tcga_exp_summary_modified.tab.gz
 include requirements.txt
-include README.md
+include README.md

README.md

@@ -29,8 +29,8 @@ NeoFox covers the following neoantigen features and prediction algorithms:
 |---------------------------------------------------------|--------------------------------------------------------------------------|-------------------------------------------------------------------------------------------|
 | MHC I binding affinity/rank score (netMHCpan-v4.1)      | Reynisson et al, 2020, Nucleic Acids Research                             | https://doi.org/10.4049/jimmunol.1700893                                                  |
 | MHC II binding affinity/rank score (netMHCIIpan-v4.0)   | Reynisson et al, 2020, Nucleic Acids Research                                           | https://doi.org/10.1111/imm.12889                                                         |
-| MixMHCpred score v2.1  §                              | Bassani-Sternberg et al., 2017, PLoS Comp Bio; Gfeller, 2018, J Immunol. | https://doi.org/10.1371/journal.pcbi.1005725 ,   https://doi.org/10.4049/jimmunol.1800914 |
-| MixMHC2pred score v1.2  §                              | Racle et al, 2019, Nat. Biotech. 2019                                    | https://doi.org/10.1038/s41587-019-0289-6                                                 |
+| MixMHCpred score v2.2  §                              | Bassani-Sternberg et al., 2017, PLoS Comp Bio; Gfeller, 2018, J Immunol. | https://doi.org/10.1371/journal.pcbi.1005725 ,   https://doi.org/10.4049/jimmunol.1800914 |
+| MixMHC2pred score v2.0.2  §                              | Racle et al, 2019, Nat. Biotech. 2019                                    | https://doi.org/10.1038/s41587-019-0289-6                                                 |
 | Differential Agretopicity Index (DAI)                   | Duan et al, 2014, JEM; Ghorani et al., 2018, Ann Oncol.                  | https://doi.org/10.1084/jem.20141308                                                      |
 | Self-Similarity                                         | Bjerregaard et al, 2017, Front Immunol.                                  | https://doi.org/10.3389/fimmu.2017.01566                                                  |
 | IEDB immunogenicity                                     | Calis et al, 2013, PLoS Comput Biol.                                     | https://doi.org/10.1371/journal.pcbi.1003266                                              |
@@ -42,7 +42,6 @@ NeoFox covers the following neoantigen features and prediction algorithms:
 | Vaxrank                                                 | Rubinsteyn, 2017, Front Immunol                                          | https://doi.org/10.3389/fimmu.2017.01807                                                  |
 | Priority score                                          | Bjerregaard et al, 2017, Cancer Immunol Immunother.                      | https://doi.org/10.1007/s00262-017-2001-3                                                 |
 | Tcell predictor                                         | Besser et al, 2019, Journal for ImmunoTherapy of Cancer                  | https://doi.org/10.1186/s40425-019-0595-z                                                 |
-| neoag                                                   | Smith et al, 2019, Cancer Immunology Research                            | https://doi.org/10.1158/2326-6066.CIR-19-0155                                             |
 | PRIME  §                                                 | Schmidt et al., 2021, Cell Reports Medicine                            | https://doi.org/10.1016/j.xcrm.2021.100194                                             |
 | HEX §                                                   | Chiaro et al., 2021, Cancer Immunology Research                            | https://doi.org/10.1158/2326-6066.CIR-20-0814                                             |
 
@@ -57,9 +56,9 @@ NeoFox depends on the following tools:
 - BLAST 2.10.1
 - netMHCpan 4.1
 - netMHCIIpan 4.0
-- MixMHCpred 2.1
-- MixMHC2pred 1.2
-- PRIME 1.0
+- MixMHCpred 2.2 (optional)
+- MixMHC2pred 2.0.2 (optional)
+- PRIME 2.0 (optional)
 
 Install from PyPI:
 ```
@@ -101,18 +100,18 @@ NEOFOX_RSCRIPT=`which Rscript`
 NEOFOX_BLASTP=path/to/ncbi-blast-2.10.1+/bin/blastp
 NEOFOX_NETMHCPAN=path/to/netMHCpan-4.1/netMHCpan
 NEOFOX_NETMHC2PAN=path/to/netMHCIIpan-4.0/netMHCIIpan
-NEOFOX_MIXMHCPRED=path/to/MixMHCpred-2.1/MixMHCpred
-NEOFOX_MIXMHC2PRED=path/to/MixMHC2pred-1.2/MixMHC2pred_unix
+NEOFOX_MIXMHCPRED=path/to/MixMHCpred-2.2/MixMHCpred
+NEOFOX_MIXMHC2PRED=path/to/MixMHC2pred-2.0.1/MixMHC2pred_unix
 NEOFOX_MAKEBLASTDB=path/to/ncbi-blast-2.8.1+/bin/makeblastdb
-NEOFOX_PRIME=/path/to/PRIME/PRIME
+NEOFOX_PRIME=/path/to/PRIME-2.0/PRIME
 ````
 
 ## 4 Input data
 
 ### 4.1 Neoantigen candidates in tabular format
 This is an dummy example of a table with neoantigen candidates:  
 
-| gene  | mutation.wildTypeXmer       | mutation.mutatedXmer        | patientIdentifier | rnaExpression | rnaVariantAlleleFrequency | dnaVariantAlleleFrequency | external_annotation_1 | external_annotation_2 |
+| gene  | wildTypeXmer       | mutatedXmer        | patientIdentifier | rnaExpression | rnaVariantAlleleFrequency | dnaVariantAlleleFrequency | external_annotation_1 | external_annotation_2 |
 |-------|-----------------------------|-----------------------------|-------------------|---------------|---------------------------|---------------------------|-----------------------|-----------------------|
 | BRCA2 | AAAAAAAAAAAAALAAAAAAAAAAAAA | AAAAAAAAAAAAAFAAAAAAAAAAAAA | Ptx               | 7.942         | 0.85                      | 0.34                      | some_value            | some_value            |
 | BRCA2 | AAAAAAAAAAAAAMAAAAAAAAAAAAA | AAAAAAAAAAAAARAAAAAAAAAAAAA | Ptx               | 7.942         | 0.85                      | 0.34                      | some_value            | some_value            |
@@ -122,8 +121,8 @@ This is an dummy example of a table with neoantigen candidates:
 
 where:
 - `gene`: the HGNC gene symbol   
-- `mutation.mutatedXmer`: the neoantigen candidate sequence, i.e. the mutated amino acid sequence. The mutation should be located in the middle, flanked by 13 amino acid on both sites (IUPAC 1 respecting casing, eg: A)
-- `mutation.wildTypeXmer`: the equivalent non-mutated amino acid sequence (IUPAC 1 respecting casing, eg: A)
+- `mutatedXmer`: the neoantigen candidate sequence, i.e. the mutated amino acid sequence. The mutation should be located in the middle, flanked by 13 amino acid on both sites (IUPAC 1 respecting casing, eg: A)
+- `wildTypeXmer`: the equivalent non-mutated amino acid sequence (IUPAC 1 respecting casing, eg: A)
 - `patientIdentifier`: the patient identifier
 - `rnaExpression`: RNA expression. (**optional**) (see *NOTE*) This value can be in any format chosen by the user (e.g. TPM, RPKM) but it is recommended to be consistent for data that should be compared.
 - `rnaVariantAlleleFrequency`: the variant allele frequency calculated from the RNA (**optional**, this will be estimated using the `dnaVariantAlleleFrequency` if not available)

docs/source/01_overview.md

@@ -30,8 +30,8 @@ A list of implemented features and their references are given in Table 1. Please
 |---------------------------------------------------------|--------------------------------------------------------------------------|-------------------------------------------------------------------------------------------|
 | MHC I binding affinity/rank score (netMHCpan-v4.1)      | Reynisson et al., 2020, Nucleic Acids Res.                             | https://doi.org/10.1093/nar/gkaa379                                                  |
 | MHC II binding affinity/rank score (netMHCIIpan-v4.0)   | Reynisson et al., 2020, Nucleic Acids Res.                                            | https://doi.org/10.1093/nar/gkaa379                                                         |
-| MixMHCpred score v2.1 §                                   | Bassani-Sternberg et al., 2017, PLoS Comp Bio; Gfeller, 2018, J Immunol. | https://doi.org/10.1371/journal.pcbi.1005725 ,   https://doi.org/10.4049/jimmunol.1800914 |
-| MixMHC2pred score v1.2 §                                 | Racle et al., 2019, Nat. Biotech. 2019                                    | https://doi.org/10.1038/s41587-019-0289-6                                                 |
+| MixMHCpred score v2.2 §                                   | Bassani-Sternberg et al., 2017, PLoS Comp Bio; Gfeller, 2018, J Immunol. | https://doi.org/10.1371/journal.pcbi.1005725 ,   https://doi.org/10.4049/jimmunol.1800914 |
+| MixMHC2pred score v2.0.2 §                                 | Racle et al., 2019, Nat. Biotech. 2019                                    | https://doi.org/10.1038/s41587-019-0289-6                                                 |
 | Differential Agretopicity Index (DAI)                   | Duan et al., 2014, JEM; Ghorani et al., 2018, Ann Oncol.                  | https://doi.org/10.1084/jem.20141308                                                      |
 | Self-Similarity                                         | Bjerregaard et al., 2017, Front Immunol.                                  | https://doi.org/10.3389/fimmu.2017.01566                                                  |
 | IEDB immunogenicity                                     | Calis et al., 2013, PLoS Comput Biol.                                     | https://doi.org/10.1371/journal.pcbi.1003266                                              |
@@ -43,8 +43,7 @@ A list of implemented features and their references are given in Table 1. Please
 | Vaxrank                                                 | Rubinsteyn, 2017, Front Immunol                                          | https://doi.org/10.3389/fimmu.2017.01807                                                  |
 | Priority score                                          | Bjerregaard et al., 2017, Cancer Immunol Immunother.                      | https://doi.org/10.1007/s00262-017-2001-3                                                 |
 | Tcell predictor                                         | Besser et al., 2019, Journal for ImmunoTherapy of Cancer                  | https://doi.org/10.1186/s40425-019-0595-z                                                 |
-| neoag                                                   | Smith et al., 2019, Cancer Immunology Research                            | https://doi.org/10.1158/2326-6066.CIR-19-0155                                             |
-| PRIME §                                                  | Schmidt et al., 2021, Cell Reports Medicine                            | https://doi.org/10.1016/j.xcrm.2021.100194                                             |
+| PRIME v2.0 §                                                  | Schmidt et al., 2021, Cell Reports Medicine                            | https://doi.org/10.1016/j.xcrm.2021.100194                                             |
 | HEX §                                                  | Chiaro et al., 2021, Cancer Immunology Research                            | https://doi.org/10.1158/2326-6066.CIR-20-0814                                             | 
 
 
@@ -56,7 +55,7 @@ model Neofox's input and output data: neoantigens, patients, MHC alleles and neo
 
 **Figure 1**
 
-![Neofox model](../figures/figure1_v3.png)
+![Neofox model](../figures/figure1_v3b.png)
 
 For detailed information about the required input data, output data and usage please refer to the [User guide](03_user_guide.rst).  
 

docs/source/02_installation.md

@@ -1,7 +1,7 @@
 # Installation
 
 This guide contains two alternatives to install NeoFox:
-- Building a docker image that automates the installation into a container
+- Building a docker image that automates the installation into a container (**NOTE**: the docker recipe is not supported in neofox-v1.1.0. Please use an older version (<v1.1.0) for building the docker image at the moment.)
 - A set of detailed step by step installation instructions without docker
 
 The first approach has the lowest entry barrier to use NeoFox as a command line tool.
@@ -20,6 +20,8 @@ the sites indicated below.
 - NetMHCpan-4.1: https://services.healthtech.dtu.dk/service.php?NetMHCpan-4.1 (`netMHCpan-4.1b.Linux.tar.gz`)
 - NetMHCIIpan-4.0: https://services.healthtech.dtu.dk/software.php (`netMHCIIpan-4.0.Linux.tar.gz`)
 
+Please also check the licences of the other third party dependencies ( e.g. listed in the docker recipe `Dockerfile`). 
+
 Store these in the root folder of the repository, next to the `Dockerfile`. Do not rename the installer files.
 
 Build the docker image: `docker build --platform linux/amd64 --tag neofox-docker .`
@@ -37,7 +39,7 @@ Python 3.7 or 3.8 should be preinstalled.
 
 The libz compression development library is required. This can be installed in Ubuntu as follows:
 ```
-apt-get install libz-dev
+apt-get install libbz2-dev
 ```
 
 ### Install NeoFox
@@ -54,6 +56,7 @@ conda install bioconda::neofox
 
 ### Install third-party dependencies
 
+**NOTE**: Please, check the licences of third-party dependencies. 
 
 #### Install R
 
@@ -122,39 +125,41 @@ export NEOFOX_NETMHC2PAN=/path/to/netMHCIIpan-4.0/netMHCIIpan
 Configure NetMHCIIpan-4.0 as explained in the file `netMHCIIpan-4.0/netMHCIIpan-4.0.readme`
 
 
-#### Install MixMHCpred-2.1 (recommended but optional)
+#### Install MixMHCpred-2.2 (recommended but optional)
 
 ```
-wget https://github.com/GfellerLab/MixMHCpred/archive/v2.1.tar.gz
-tar -xvf v2.1.tar.gz
+wget https://github.com/GfellerLab/MixMHCpred/archive/refs/tags/v2.2.tar.gz
+tar -xvf v2.2.tar.gz
 ```
 
 Set the environment variable pointing to `MixMHCpred`, there will be no search in the path as the installation folder
 is also needed to determine the supported alleles.
 ```
-export NEOFOX_MIXMHCPRED=/path/to/MixMHCpred-2.1/MixMHCpred
+export NEOFOX_MIXMHCPRED=/path/to/MixMHCpred-2.2/MixMHCpred
 ```
 
-Configure MixMHCpred-2.1 as explained in the file `MixMHCpred-2.1/README`
+Configure MixMHCpred-2.2 as explained in the file `MixMHCpred-2.2/README`
+
+
 
-#### Install MixMHC2pred-1.2 (recommended but optional)
+#### Install MixMHC2pred-2.0.2 (recommended but optional)
 
 ```
-wget https://github.com/GfellerLab/MixMHC2pred/archive/v1.2.tar.gz
-tar -xvf v1.2.tar.gz
+wget https://github.com/GfellerLab/MixMHC2pred/archive/refs/tags/v2.0.2.2.tar.gz
+tar -xvf v2.0.2.2.tar.gz
 ```
 
 Set the environment variable pointing to `MixMHC2pred_unix`, there will be no search in the path as the installation 
 folder is also needed to determine the supported alleles.
 ```
-export NEOFOX_MIXMHC2PRED=`pwd`/MixMHC2pred-1.2/MixMHC2pred_unix
+export NEOFOX_MIXMHC2PRED=`pwd`/MixMHC2pred-2.0.2/MixMHC2pred_unix
 ```
 
 #### PRIME-1.0 (recommended but optional)
 
 ```
-wget https://github.com/GfellerLab/PRIME/archive/master.tar.gz
-tar -xvf master.tar.gz
+wget https://github.com/GfellerLab/PRIME/archive/refs/tags/v2.0.tar.gz
+tar -xvf v2.0.tar.gz
 ```
 
 Set the environment variable pointing to `PRIME`, there will be no search in the path as the installation folder
@@ -186,13 +191,18 @@ export NEOFOX_HLA_DATABASE=https://raw.githubusercontent.com/ANHIG/IMGTHLA/Lates
 
 Run the following to configure the NeoFox reference folder:
 ```
-neofox-configure --reference-folder /your/neofox/folder [--install-r-dependencies]
+neofox-configure --reference-folder /your/neofox/folder [--install-r-dependencies --install_mouse_mixmhc2pred]
 ```
 
 **NOTE**: when installing from conda `--install-r-dependencies` is not needed. 
 
-The above command will install several resources and store in the annotations metadata their version, MD5 checksum and 
-download timestamp.
+The above command will download and transform several resources and store in the annotations metadata their version, MD5 checksum and 
+download timestamp. 
+
+
+To run NeoFox on data from mouse with MixMHC2pred, mouse-specific PMWs are required. For such use cases the reference folder needs to be configured with `--install_mouse_mixmhc2pred` (see also )
+
+Depending on your use case please check the licences of these third-party resources (see urls in neofox/references/installer.py). 
 
 Unless indicated to the installer by flag `--install-r-dependencies` you will need to install manually some R packages. These packages are the following:
 ```