Update to version 5.1.0

griffithlab · Jan 17, 2025 · e899319 · e899319
1 parent 3a420bb
commit e899319
Show file tree

Hide file tree

Showing 10 changed files with 115 additions and 27 deletions.
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 = '5.0'
+version = '5.1'
 # The full version, including alpha/beta/rc tags.
-release = '5.0.1'
+release = '5.1.0'
 
 
 # The language for content autogenerated by Sphinx. Refer to documentation

diff --git a/docs/index.rst b/docs/index.rst
@@ -60,11 +60,36 @@ Contents
 New in Version |release|
 ------------------------
 
-This is a bugfix release. It fixes the following problem(s):
-
-- The ``--aggregate-inclusion-count-limit`` was not being passed along to the
-  aggregate report module in the pVACsplice pipeline correctly. This release
-  fixes that issue. by @susannasiebert in https://github.com/griffithlab/pVACtools/pull/1167
+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|
 ------------------------

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/pvacsplice/output_files.rst b/docs/pvacsplice/output_files.rst
@@ -259,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``

diff --git a/docs/pvacvector.rst b/docs/pvacvector.rst
@@ -30,9 +30,38 @@ peptides are tested by removing leading and/or trailing amino acids and
 constructing junctions with the clipped peptides. The maximum number of amino
 acids to clip is controlled by the ``--max-clip-length`` argument.
 
-The final vaccine ordering is
-achieved through a simulated annealing procedure that returns a near-optimal
-solution, when one exists.
+In some cases, the (core) neoantigen candidate of a peptide sequence may be located
+toward the beginning or end of the sequence. In these cases, clipping may
+accidentially remove amino acids of the core neoantigen. To prevent this, the
+``--max-clip-length`` should be set to the shortest number of flanking amino
+acids of any of the peptides to include in the vector. Alternatively, pVACvector also
+supports specifying the core neoantigen in the FASTA header when using a FASTA
+file as the input to pVACvector. If the core neoantigens for each sequence are specified in the
+input FASTA file, pVACvector will not clip into these neoantigens, even if the
+flanking sequence is smaller than the ``--max-clip-length``. The core neoantigen should
+be specified like so:
+
+.. code-block:: none
+
+    >Peptide1 {"Best Peptide": "LYYSYGLLHI"}
+    WLYYSYGLLHIYGSGGYALYF
+
+In this example ``Peptide1`` is the ID of the sequence, ``LYYSYGLLHI`` is
+the core neoantigen candidate, and ``WLYYSYGLLHIYGSGGYALYF`` is the peptide
+sequence to include in the vector. The Best Peptide information will already
+be included in the FASTA headers if the FASTA file is created by using the ``pvacseq
+generate_protein_fasta`` command in conjunction with an aggregated report TSV
+as the ``--input-tsv`` parameter.
+
+If no solution is found after testing all spacers and after clipping peptides, pVACvector
+will attempt to find a partial solution by excluding peptide sequences. The
+number of peptide sequences that are allowed to be removed is controlled via
+the ``--allow-n-peptide-exclusion`` parameter. Partial solutions will be
+written to their own result subdirectory. The subdirectory name reflects which
+peptide(s) were removed from the partial solution.
+
+The final vaccine ordering is achieved through a simulated annealing procedure that
+returns a near-optimal solution, when one exists.
 
 .. toctree::
    :glob:

diff --git a/docs/pvacvector/output_files.rst b/docs/pvacvector/output_files.rst
@@ -5,15 +5,7 @@
 Output Files
 ============
 
-The pVACseq pipeline will write its results in separate folders depending on
-which prediction algorithms were chosen:
-
-- ``MHC_Class_I``: for MHC class I prediction algorithms
-- ``MHC_Class_II``: for MHC class II prediction algorithms
-- ``combined``: If both MHC class I and MHC class II prediction algorithms were run, this folder combines the neoepitope predictions from both
-
-Each folder will contain the same list of output files (listed in the order
-created):
+pVACvector will create the following output files:
 
 .. list-table::
    :header-rows: 1
@@ -30,10 +22,19 @@ created):
      - The final output file with the peptide sequences and best spacers in the optimal order.
    * - ``junctions.tsv``
      - A tab-separated file listing all of the valid junctions found by pVACvector including spacer and clipping information.
-   * - ``vector.jpg``
-     - A JPEG visualization of the above result.
+   * - ``vector.png``
+     - A PNG visualization of the above result.
    * - ``<sample_name>_results.dna.fa``
      - The final output file with the backtranslated DNA sequences of the included peptides and best spacers in the optimal order.
+   * - ``without_<peptide_id(s)>`` (directory
+     - If no solution was found with spacers and clipping peptides, these
+       directories contain result files for partial solutions obtained by removing
+       peptide(s) as indicated in each directory name. These directories
+       in turn contain a ``junctions.tsv`` file of all of the junctions
+       remaining after the respective peptide(s) were removed, as well as a
+       ``<sample_name>_results.fa``, a ``<sample_name>_results.dna.fa``, and a
+       ``vector.png`` file if a solution was found by removing the indicated
+       peptide(s).
 
 .. figure:: ../images/vector.jpg
    :align: center

diff --git a/docs/pvacvector/run.rst b/docs/pvacvector/run.rst
@@ -43,6 +43,36 @@ peptides are tested by removing leading and/or trailing amino acids and
 constructing junctions with the clipped peptides. The maximum number of amino
 acids to clip is controlled by the ``--max-clip-length`` argument.
 
+In some cases, the (core) neoantigen candidate of a peptide sequence may be located
+toward the beginning or end of the sequence. In these cases, clipping may
+accidentially remove amino acids of the core neoantigen. To prevent this, the
+``--max-clip-length`` should be set to the shortest number of flanking amino
+acids of any of the peptides to include in the vector. Alternatively, pVACvector also
+supports specifying the core neoantigen in the FASTA header when using a FASTA
+file as the input to pVACvector. If the core neoantigens for each sequence are specified in the
+input FASTA file, pVACvector will not clip into these neoantigens, even if the
+flanking sequence is smaller than the ``--max-clip-length``. The core neoantigen should
+be specified like so:
+
+.. code-block:: none
+
+    >Peptide1 {"Best Peptide": "LYYSYGLLHI"}
+    WLYYSYGLLHIYGSGGYALYF
+
+In this example ``Peptide1`` is the ID of the sequence, ``LYYSYGLLHI`` is
+the core neoantigen candidate, and ``WLYYSYGLLHIYGSGGYALYF`` is the peptide
+sequence to include in the vector. The Best Peptide information will already
+be included in the FASTA headers if the FASTA file is created by using the ``pvacseq
+generate_protein_fasta`` command in conjunction with an aggregated report TSV
+as the ``--input-tsv`` parameter.
+
+If no solution is found after testing all spacers and after clipping peptides, pVACvector
+will attempt to find a partial solution by excluding peptide sequences. The
+number of peptide sequences that are allowed to be removed is controlled via
+the ``--allow-n-peptide-exclusion`` parameter. Partial solutions will be
+written to their own result subdirectory. The subdirectory name reflects which
+peptide(s) were removed from the partial solution.
+
 Our current recommendation is to run pVACvector several different ways, and
 choose the path resulting from the most conservative set of parameters.
 

diff --git a/pvactools/tools/pvacview/server.R b/pvactools/tools/pvacview/server.R
@@ -24,7 +24,7 @@ options(shiny.port = 3333)
 server <- shinyServer(function(input, output, session) {
   ## pVACtools version
 
-  output$version <- renderText({"pVACtools version 5.0.1"})
+  output$version <- renderText({"pVACtools version 5.1.0"})
 
   ##############################DATA UPLOAD TAB###################################
   ## helper function defined for generating shinyInputs in mainTable (Evaluation dropdown menus)

diff --git a/setup.py b/setup.py
@@ -56,7 +56,7 @@
 
 setup(
     name="pvactools",
-    version="5.0.1",
+    version="5.1.0",
     packages=[
         "pvactools.tools",
         "pvactools.tools.pvacbind",