Merge branch 'staging' of github.com:ldhtnp/pVACtools into issues/1142

griffithlab · Jan 29, 2025 · 864384b · 864384b
2 parents 493bb75 + e899319
commit 864384b
Show file tree

Hide file tree

Showing 125 changed files with 215,382 additions and 158,652 deletions.
diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
@@ -11,7 +11,7 @@ jobs:
   run_tests:
     name: "Test pVACtools in various Python versions"
 
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-22.04
     strategy:
       matrix:
         python-version: ['3.7', '3.8', '3.9', '3.10', '3.11']

diff --git a/docs/citation.rst b/docs/citation.rst
@@ -19,3 +19,5 @@ L. Griffith, Elaine R. Mardis, and Malachi Griffith. `pVACseq: A genome-guided
 in silico approach to identifying tumor neoantigens <http://www.genomemedicine.com/content/8/1/11>`_. Genome Medicine. 2016,
 8:11, DOI: 10.1186/s13073-016-0264-5. PMID: `26825632
 <http://www.ncbi.nlm.nih.gov/pubmed/26825632>`_.
+
+Huiming Xia, My H. Hoang, Evelyn Schmidt, Susanna Kiwala, Joshua McMichael, Zachary L. Skidmore, Bryan Fisk, Jonathan J. Song, Jasreet Hundal, Thomas Mooney, Jason R. Walker, S. Peter Goedegebuure, Christopher A. Miller, William E. Gillanders, Obi L. Griffith,  Malachi Griffith. `pVACview: an interactive visualization tool for efficient neoantigen prioritization and selection <https://genomemedicine.biomedcentral.com/articles/10.1186/s13073-024-01384-7>`_. Genome Medicine. 2024, 16:132, DOI: 10.1186/s13073-024-01384-7. PMID: `39538339 <http://www.ncbi.nlm.nih.gov/pubmed/39538339>`_. 
diff --git a/docs/conf.py b/docs/conf.py
@@ -60,17 +60,17 @@
 
 # General information about the project.
 project = 'pVACtools'
-copyright = '2018-2023 Washington University in St. Louis'
+copyright = '2018-2025 Washington University in St. Louis'
 author = 'Jasreet Hundal, Susanna Kiwala, Joshua McMichael, Yang-Yang Feng, Christopher A. Miller, Aaron Graubert, Alex Wollam, Amber Wollam, Connor Liu, Jonas Neichin, Megan Neveau, Jason Walker, Elaine R. Mardis, Obi L. Griffith, Malachi Griffith'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
 # The short X.Y version.
-version = '4.4'
+version = '5.1'
 # The full version, including alpha/beta/rc tags.
-release = '4.4.1'
+release = '5.1.0'
 
 
 # The language for content autogenerated by Sphinx. Refer to documentation

diff --git a/docs/frequently_asked_questions.rst b/docs/frequently_asked_questions.rst
@@ -40,3 +40,4 @@ in silico approach to identifying tumor neoantigens <http://www.genomemedicine.c
 8:11, DOI: 10.1186/s13073-016-0264-5. PMID: `26825632
 <http://www.ncbi.nlm.nih.gov/pubmed/26825632>`_.
 
+Huiming Xia, My H. Hoang, Evelyn Schmidt, Susanna Kiwala, Joshua McMichael, Zachary L. Skidmore, Bryan Fisk, Jonathan J. Song, Jasreet Hundal, Thomas Mooney, Jason R. Walker, S. Peter Goedegebuure, Christopher A. Miller, William E. Gillanders, Obi L. Griffith,  Malachi Griffith. `pVACview: an interactive visualization tool for efficient neoantigen prioritization and selection <https://genomemedicine.biomedcentral.com/articles/10.1186/s13073-024-01384-7>`_. Genome Medicine. 2024, 16:132, DOI: 10.1186/s13073-024-01384-7. PMID: `39538339 <http://www.ncbi.nlm.nih.gov/pubmed/39538339>`_. 
diff --git a/docs/images/pVACsplice_logo_trans-bg_v4b.png b/docs/images/pVACsplice_logo_trans-bg_v4b.png
diff --git a/docs/images/pVACtools_main-figure_v8.png b/docs/images/pVACtools_main-figure_v8.png
diff --git a/docs/index.rst b/docs/index.rst
@@ -25,7 +25,7 @@ tools:
    users in reviewing, exploring and prioritizing neoantigens from the results of
    pVACtools processes for personalized cancer vaccine design.
 
-.. image:: images/pVACtools_main-figure_v7.png
+.. image:: images/pVACtools_main-figure_v8.png
     :align: center
     :alt: pVACtools immunotherapy workflow
 
@@ -57,22 +57,78 @@ Contents
    contact
    mailing_list
 
-New in Release |release|
+New in Version |release|
 ------------------------
 
-This is a bugfix release. It fixes the following problem(s):
+This is a minor feature release. It adds the following features:
+
+- This update allows pVACvector to remove peptides in order to find a partial solution if a full solution cannot be found.
+  The number of peptides permitted to be removed can be controlled by the ``--allow-n-peptide-exclusion`` parameter. by
+  @susannasiebert in https://github.com/griffithlab/pVACtools/pull/1168
+- This update adds functionalities to pVACvector to prevent the core neoantigen candidate from getting clipped. by
+  @susannasiebert in https://github.com/griffithlab/pVACtools/pull/1174
+- When only elution algorithms are chosen and no binding affinity algorithms,
+  the pipelines will now output a warning message that no aggregated report
+  can be created. by @ldhtnp in https://github.com/griffithlab/pVACtools/pull/1165
+- When creating the aggregated report, the Best Peptide for some variants
+  may not match the aggregate inclusion criteria and no detail information
+  would be available for this peptide when investigating the variant. This
+  update ensures that the Best Peptide is always included in the metrics file
+  and counted toward the Num Included Peptides count. by @susannasiebert in
+  https://github.com/griffithlab/pVACtools/pull/1177
+- The evaluation buttons in pVACview will now be colored green for Accept, red
+  for Reject, and orange for Review to visually differentiate the different
+  statuses. by @susannasiebert in https://github.com/griffithlab/pVACtools/pull/1173
+
+It also fixes the following problem(s):
+
+- This release removes two parameters from pVACvector: ``--aggregate-inclusion-binding-threshold`` and ``--aggregate-inclusion-count-limit``
+  which are not applicable to this pipeline. by @susannasiebert in https://github.com/griffithlab/pVACtools/pull/1180
+- This release fixes various pVACview bugs. Specifically, it fixes a bug that
+  would result in pVACview crashing when a variant with a Num Included
+  Peptides of 0 was selected. It also fixes a bug where re-tiering the
+  candidates before selecting evaluations would result in evaluations being
+  associated with incorrect variants. Additionally, it fixes several
+  deprecation warnings and typos. by @susannasiebert in https://github.com/griffithlab/pVACtools/pull/1173
+
+New in Version |version|
+------------------------
 
-- Previously, pVACview would add an additional header line to Excel spreadsheets
-  when exporting a TSV. This has been fixed so that the first line in the spreadsheet
-  is the actual header line.
-  by @susannasiebert in https://github.com/griffithlab/pVACtools/pull/1143
-- One of the pVACview figures used to describe various anchor scenarios has been updated
-  so that the ordering of the scenarios is consistent with other figures and descriptions
-  throughout. Screenshots and documentation has been updated appropriately.
-  by @susannasiebert in https://github.com/griffithlab/pVACtools/pull/1144
-- The class II pVACview demo data was out-of-date and not reflecting recent updates to the
-  HLA alpha-beta chain handling. This file has now been updated.
-  by @susannasiebert in https://github.com/griffithlab/pVACtools/pull/1145
+This is a major version release. Please note that pVACtools 5.0 is not guaranteed to be
+backwards-compatible and certain changes could break old workflows.
+
+New Tools
+_________
+
+This release adds a new tool, pVACsplice, for prediction neoantigens from
+splice sites. Please see the :ref:`full tool documentation <pvacsplice>` for more information.
+by @mrichters in https://github.com/griffithlab/pVACtools/pull/911
+
+New Features
+____________
+
+- This release refactors the pVACvector graph building algorithm in order to increase the probability
+  for finding a solution and reduce the number of iterations needed before a solution is found. Please
+  see the PR describtion for the full details. by @susannasiebert in https://github.com/griffithlab/pVACtools/pull/1163
+- Add a new ``--aggregate-inclusion-count-limit`` parameter to set the maximum number of epitopes
+  to include in the metrics.json detailed data for variants that have a large number of candidate
+  neoantigens (e.g., frameshifts). by @susannasiebert in https://github.com/griffithlab/pVACtools/pull/1147
+- Add a new ``--biotypes`` parameter which defines a list of transcript consequence biotypes that the
+  predictions from pVACseq and pVACsplice should be limited to. by @mrichters in https://github.com/griffithlab/pVACtools/pull/911
+- Add support for additional alleles that weren't previously supported, includings ones for dog,
+  mouse, and MHC class II. by @susannasiebert in https://github.com/griffithlab/pVACtools/pull/1148
+
+Bugfixes
+________
+
+- This relase fixes a bug with the ``--agregate-inclusion-binding-threshold`` which would not be used if
+  the ``--allele-specific-binding-thresholds`` flag was set. by @susannasiebert in https://github.com/griffithlab/pVACtools/pull/1147
+- The pVACview percentile plots have been updated to include percentiles from elution and immunogenicity
+  algorithms. by @susannasiebert in https://github.com/griffithlab/pVACtools/pull/1149
+- This release fixes a bug where the incorrect neoantigen fasta entry may be used for the reference proteome
+  search if there were multiple variants or alt alleles located at the same genomic position. by @susannasiebert in https://github.com/griffithlab/pVACtools/pull/1153
+- Add additional trailing amino acids for frameshift insertions when creating fasta in order to capture a
+  matched wildtype entry in large repetitive regions. by @susannasiebert in https://github.com/griffithlab/pVACtools/pull/1155
 
 Past release notes can be found on our :ref:`releases` page.
 
@@ -100,6 +156,8 @@ in silico approach to identifying tumor neoantigens <http://www.genomemedicine.c
 8:11, DOI: 10.1186/s13073-016-0264-5. PMID: `26825632
 <http://www.ncbi.nlm.nih.gov/pubmed/26825632>`_.
 
+Huiming Xia, My H. Hoang, Evelyn Schmidt, Susanna Kiwala, Joshua McMichael, Zachary L. Skidmore, Bryan Fisk, Jonathan J. Song, Jasreet Hundal, Thomas Mooney, Jason R. Walker, S. Peter Goedegebuure, Christopher A. Miller, William E. Gillanders, Obi L. Griffith,  Malachi Griffith. `pVACview: an interactive visualization tool for efficient neoantigen prioritization and selection <https://genomemedicine.biomedcentral.com/articles/10.1186/s13073-024-01384-7>`_. Genome Medicine. 2024, 16:132, DOI: 10.1186/s13073-024-01384-7. PMID: `39538339 <http://www.ncbi.nlm.nih.gov/pubmed/39538339>`_. 
+
 Source code
 -----------
 The pVACtools source code is available in `GitHub <https://github.com/griffithlab/pVACtools>`_.

diff --git a/docs/install.rst b/docs/install.rst
@@ -90,8 +90,8 @@ Download the archives for `class II <http://tools.iedb.org/mhcii/download/>`_ an
 .. code-block:: none
 
    apt-get update && apt-get install -y tcsh gawk
-   wget https://downloads.iedb.org/tools/mhcii/3.1.11/IEDB_MHC_II-3.1.11.tar.gz
-   tar -zxvf IEDB_MHC_II-3.1.11.tar.gz
+   wget https://downloads.iedb.org/tools/mhcii/3.1.12/IEDB_MHC_II-3.1.12.tar.gz
+   tar -zxvf IEDB_MHC_II-3.1.12.tar.gz
    cd mhc_ii
    ./configure.py
 

diff --git a/docs/pvacbind/output_files.rst b/docs/pvacbind/output_files.rst
@@ -170,7 +170,8 @@ that offer suggestions as to the suitability of variants for use in vaccines.
 Only epitopes meeting the ``--aggregate-inclusion-binding-threshold`` are included in this report (default: 5000).
 If the number of unique epitopes for a mutation meeting this threshold exceeds the
 ``--aggregate-inclusion-count-limit``, only the n best-binding epitopes up to this
-limit are included (default: 15).
+limit are included (default: 15). If the Best Peptide does not meet the aggregate inclusion criteria, it will be still be
+counted in the ``Num Included Peptides``.
 
 Whether the median or the lowest binding affinity metrics are used for determining the
 included eptiopes, selecting the best-scoring epitope, and which values are output in the ``IC50 MT``

diff --git a/docs/pvacfuse/output_files.rst b/docs/pvacfuse/output_files.rst
@@ -203,7 +203,8 @@ that offer suggestions as to the suitability of variants for use in vaccines.
 Only epitopes meeting the ``--aggregate-inclusion-binding-threshold`` are included in this report (default: 5000).
 If the number of unique epitopes for a fusion meeting this threshold exceeds the
 ``--aggregate-inclusion-count-limit``, only the n best-binding epitopes up to this
-limit are included (default: 15).
+limit are included (default: 15). If the Best Peptide does not meet the aggregate inclusion criteria, it will be still be
+counted in the ``Num Included Peptides``.
 
 Whether the median or the lowest binding affinity metrics are used for determining the
 included eptiopes, selecting the best-scoring epitope, and which values are output in the ``IC50 MT``

diff --git a/docs/pvacseq/input_file_prep/readcounts.rst b/docs/pvacseq/input_file_prep/readcounts.rst
@@ -134,7 +134,7 @@ from a VCF and run bam-readcount. Information on that Docker container can be fo
 .. code-block:: none
 
    /usr/bin/python /usr/bin/bam_readcount_helper.py \
-   <decomposed_vcf> <sample_name> <reference_fasta> <bam_file> <output_dir>
+   <decomposed_vcf> <sample_name> <reference_fasta> <bam_file> NOPREFIX <output_dir>
 
 This will write two bam-readcount files to the ``<output_dir>``:
 ``<sample_name>_bam_readcount_snv.tsv`` and

diff --git a/docs/pvacseq/output_files.rst b/docs/pvacseq/output_files.rst
@@ -279,7 +279,13 @@ transcripts covered by those epitopes, as well as the HLA alleles that those
 epitopes are well-binding to. Lastly, the report will bin variants into tiers
 that offer suggestions as to the suitability of variants for use in vaccines.
 
-Only epitopes meeting the ``--aggregate-inclusion-binding-threshold`` are included in this report (default: 5000).
+Additionally, a metrics.json file gets created, containing metadata about the
+Best Peptide as well as alternate neoantigen canddiates for each variant. This
+file can be loaded into pVACview in conjunction with the aggregated report in
+order to visualize the candidates. In order to limit the size of the
+metrics.json file, only a limited number of neoantigen candidates are included
+in this file. Only neoantigen candidates meeting the ``--aggregate-inclusion-binding-threshold``
+are included in this file (default: 5000).
 If the number of unique epitopes for a mutation meeting this threshold exceeds the
 ``--aggregate-inclusion-count-limit``, only the top n epitopes up to this
 limit are included (default: 15). The method for selecting the top n epitopes is analogous to
@@ -293,8 +299,12 @@ anchor criteria was passed, the MT IC50 score, the transcript length,
 and the MT percentile. From this sorted list the top n entries are selected up
 to the ``--aggregate-inclusion-count-limit``.
 
+If the Best Peptide does not meet the aggregate inclusion criteria, it will be still be
+included in the metrics.json file and counted in the ``Num Included
+Peptides``.
+
 Whether the median or the lowest binding affinity metrics are used for determining the
-included eptiopes, selecting the best-scoring epitope, and which values are output in the ``IC50 MT``,
+included epitopes, selecting the best-scoring epitope, and which values are output in the ``IC50 MT``,
 ``IC50 WT``, ``%ile MT``, and ``%ile WT`` columns is controlled by the
 ``--top-score-metric`` parameter.
 
@@ -371,9 +381,7 @@ included eptiopes, selecting the best-scoring epitope, and which values are outp
 Best Peptide Criteria
 _____________________
 
-To determine the Best Peptide, all peptides meeting the
-``--aggregate-inclusion-threshold`` and ``--aggregate-inclusion-count-limit``
-(see above) are evaluated as follows:
+To determine the Best Peptide, all peptides for a variant are evaluated as follows:
 
 - Pick all entries with a variant transcript that have a ``protein_coding`` Biotype
 - Of the remaining entries, pick the ones with a variant transcript having

diff --git a/docs/pvacsplice.rst b/docs/pvacsplice.rst
@@ -1,3 +1,10 @@
+.. image:: images/pVACsplice_logo_trans-bg_v4b.png
+    :align: right
+    :alt: pVACsplice logo
+    :width: 175px
+
+.. _pvacsplice:
+
 pVACsplice
 ==========
 

diff --git a/docs/pvacsplice/additional_commands.rst b/docs/pvacsplice/additional_commands.rst
@@ -1,6 +1,7 @@
-.. .. image:: ../images/pVACseq_logo_trans-bg_sm_v4b.png
+.. image:: ../images/pVACsplice_logo_trans-bg_v4b.png
     :align: right
-    :alt: pVACseq logo
+    :alt: pVACsplice logo
+    :width: 175px
 
 Additional Commands
 ===================

diff --git a/docs/pvacsplice/features.rst b/docs/pvacsplice/features.rst
@@ -1,6 +1,7 @@
-.. .. image:: ../images/pVACseq_logo_trans-bg_sm_v4b.png
+.. image:: ../images/pVACsplice_logo_trans-bg_v4b.png
     :align: right
     :alt: pVACsplice logo
+    :width: 175px
 
 Features
 ========

diff --git a/docs/pvacsplice/filter_commands.rst b/docs/pvacsplice/filter_commands.rst
@@ -1,6 +1,7 @@
-.. .. image:: ../images/pVACseq_logo_trans-bg_sm_v4b.png
+.. image:: ../images/pVACsplice_logo_trans-bg_v4b.png
     :align: right
-    :alt: pVACseq logo
+    :alt: pVACsplice logo
+    :width: 175px
 
 .. _pvacsplice_filter_commands:
 

diff --git a/docs/pvacsplice/getting_started.rst b/docs/pvacsplice/getting_started.rst
@@ -1,3 +1,8 @@
+.. image:: ../images/pVACsplice_logo_trans-bg_v4b.png
+    :align: right
+    :alt: pVACsplice logo
+    :width: 175px
+
 Getting Started
 ===============
 

diff --git a/docs/pvacsplice/input_file_prep.rst b/docs/pvacsplice/input_file_prep.rst
@@ -1,3 +1,8 @@
+.. image:: ../images/pVACsplice_logo_trans-bg_v4b.png
+    :align: right
+    :alt: pVACsplice logo
+    :width: 175px
+
 .. _pvacsplice_prerequisites_label:
 
 Input File Preparation

diff --git a/docs/pvacsplice/optional_downstream_analysis_tools.rst b/docs/pvacsplice/optional_downstream_analysis_tools.rst
@@ -1,6 +1,7 @@
-.. .. image:: ../images/pVACseq_logo_trans-bg_sm_v4b.png
+.. image:: ../images/pVACsplice_logo_trans-bg_v4b.png
     :align: right
     :alt: pVACsplice logo
+    :width: 175px
 
 .. _pvacsplice_optional_downstream_analysis_tools_label:
 

diff --git a/docs/pvacsplice/output_files.rst b/docs/pvacsplice/output_files.rst
@@ -1,6 +1,7 @@
-.. .. image:: ../images/pVACseq_logo_trans-bg_sm_v4b.png
+.. image:: ../images/pVACsplice_logo_trans-bg_v4b.png
     :align: right
-    :alt: pVACseq logo
+    :alt: pVACsplice logo
+    :width: 175px
 
 .. _pvacsplice_output_files:
 
@@ -258,7 +259,8 @@ that offer suggestions as to the suitability of variants for use in vaccines.
 Only epitopes meeting the ``--aggregate-inclusion-binding-threshold`` are included in this report (default: 5000).
 If the number of unique epitopes for a variant meeting this threshold exceeds the
 ``--aggregate-inclusion-count-limit``, only the n best-binding epitopes up to this
-limit are included (default: 15).
+limit are included (default: 15). If the Best Peptide does not meet the aggregate inclusion criteria, it will be still be
+counted in the ``Num Included Peptides``.
 
 Whether the median or the lowest binding affinity metrics are used for determining the
 included eptiopes, selecting the best-scoring epitope, and which values are output in the ``IC50 MT``
@@ -297,6 +299,10 @@ and ``%ile MT`` columns is controlled by the ``--top-score-metric`` parameter.
      - A list of positions in the Best Peptide that are problematic.
        ``None`` if the ``--problematic-pos`` parameter was not set during
        the pVACseq run
+   * - ``Num Included Peptides``
+     - The number of included peptides according to the
+       ``--aggregate-inclusion-binding-threshold`` and
+       ``--aggregate-inclusion-count-limit``
    * - ``Num Passing Peptides``
      - The number of unique well-binding peptides for this mutation.
    * - ``IC50 MT``

diff --git a/docs/pvacsplice/run.rst b/docs/pvacsplice/run.rst
@@ -1,3 +1,8 @@
+.. image:: ../images/pVACsplice_logo_trans-bg_v4b.png
+    :align: right
+    :alt: pVACsplice logo
+    :width: 175px
+
 Usage
 =====
Original file line number	Diff line number	Diff line change
Expand Up		@@ -40,3 +40,4 @@ in silico approach to identifying tumor neoantigens <http://www.genomemedicine.c
		8:11, DOI: 10.1186/s13073-016-0264-5. PMID: `26825632
		<http://www.ncbi.nlm.nih.gov/pubmed/26825632>`_.

		Huiming Xia, My H. Hoang, Evelyn Schmidt, Susanna Kiwala, Joshua McMichael, Zachary L. Skidmore, Bryan Fisk, Jonathan J. Song, Jasreet Hundal, Thomas Mooney, Jason R. Walker, S. Peter Goedegebuure, Christopher A. Miller, William E. Gillanders, Obi L. Griffith, Malachi Griffith. `pVACview: an interactive visualization tool for efficient neoantigen prioritization and selection <https://genomemedicine.biomedcentral.com/articles/10.1186/s13073-024-01384-7>`_. Genome Medicine. 2024, 16:132, DOI: 10.1186/s13073-024-01384-7. PMID: `39538339 <http://www.ncbi.nlm.nih.gov/pubmed/39538339>`_.