Merge pull request #1185 from ldhtnp/issues/1142

Behavior to allow different percentile threshold strategies for candidates
griffithlab · Feb 19, 2025 · 337358c · 337358c
2 parents f7a03bf + 332e4c6
commit 337358c
Show file tree

Hide file tree

Showing 38 changed files with 379 additions and 195 deletions.
diff --git a/docs/pvacbind/filter_commands.rst b/docs/pvacbind/filter_commands.rst
@@ -55,6 +55,12 @@ to ``lowest``, this threshold is applied to the ``Best Percentile`` column. When
 it is set to ``median``, the threshold is applied to the ``Median
 Percentile`` column.
 
+When the ``--percentile-threshold`` flag is set, the candidate inclusion strategy can be
+specified by using the ``--percentile-threshold-strategy`` parameter. The parameter has two
+options ``conservative`` (default) and ``exploratory``. The 'conservative' option requires a candidate 
+to pass BOTH the binding threshold and percentile threshold, while the 'exploratory' option requires
+a candidate to pass EITHER the binding threshold or percentile threshold.
+
 By default, entries with ``NA`` values will be included in the output. This
 behavior can be turned off by using the ``--exclude-NAs`` flag.
 

diff --git a/docs/pvacbind/output_files.rst b/docs/pvacbind/output_files.rst
@@ -234,6 +234,11 @@ provided to the pVACfuse run:
    * - ``--percentile-threshold``
      - When set, use this threshold to filter epitopes on the %ile MT score in addition to having to meet the binding threshold.
      - None
+   * - ``--percentile-threshold-strategy``
+     - Specify the candidate inclusion strategy. The ``conservative`` option requires a candidate to pass BOTH the binding threshold
+       and percentile threshold (if set). The ``exploratory`` option requires a candidate to pass EITHER the binding threshold or
+       the percentile threshold.
+     - conservative
 
 Tiers
 *****
@@ -259,7 +264,9 @@ Criteria Details
    * - Binding Criteria
      - Pass if Best Peptide is strong binder
      - ``IC50 MT < binding_threshold`` and ``%ile MT < percentile_threshold``
-       (if ``--percentile-threshold`` parameter is set)
+       (if ``--percentile-threshold`` parameter is set and 'conservative' ``--percentile-threshold-strategy`` is used) or
+       ``IC50 MT < binding_threshold`` or ``%ile MT < percentile_threshold``
+       (if 'exploratory' ``--percentile-threshold-strategy`` is used)
 
 
 .. _pvacbind_reference_matches:

diff --git a/docs/pvacfuse/filter_commands.rst b/docs/pvacfuse/filter_commands.rst
@@ -54,6 +54,12 @@ to ``lowest``, this threshold is applied to the ``Best Percentile`` column. When
 it is set to ``median``, the threshold is applied to the ``Median
 Percentile`` column.
 
+When the ``--percentile-threshold`` flag is set, the candidate inclusion strategy can be
+specified by using the ``--percentile-threshold-strategy`` parameter. The parameter has two
+options ``conservative`` (default) and ``exploratory``. The 'conservative' option requires a candidate 
+to pass BOTH the binding threshold and percentile threshold, while the 'exploratory' option requires
+a candidate to pass EITHER the binding threshold or percentile threshold.
+
 By default, entries with ``NA`` values will be included in the output. This
 behavior can be turned off by using the ``--exclude-NAs`` flag.
 

diff --git a/docs/pvacfuse/output_files.rst b/docs/pvacfuse/output_files.rst
@@ -279,6 +279,11 @@ provided to the pVACfuse run:
    * - ``--percentile-threshold``
      - When set, use this threshold to filter epitopes on the %ile MT score in addition to having to meet the binding threshold.
      - None
+   * - ``--percentile-threshold-strategy``
+     - Specify the candidate inclusion strategy. The ``conservative`` option requires a candidate to pass BOTH the binding threshold
+       and percentile threshold (if set). The ``exploratory`` option requires a candidate to pass EITHER the binding threshold or
+       the percentile threshold.
+     - conservative
    * - ``--read-support``
      - The threshold used for filtering epitopes on the Read Support.
      - 5
@@ -317,7 +322,9 @@ Criteria Details
    * - Binding Criteria
      - Pass if Best Peptide is strong binder
      - ``IC50 MT < binding_threshold`` and ``%ile MT < percentile_threshold``
-       (if ``--percentile-threshold`` parameter is set)
+       (if ``--percentile-threshold`` parameter is set and 'conservative' ``--percentile-threshold-strategy`` is used) or
+       ``IC50 MT < binding_threshold`` or ``%ile MT < percentile_threshold``
+       (if 'exploratory' ``--percentile-threshold-strategy`` is used)
    * - Read Support Criteria
      - Pass if the variant has read support
      - ``Read Support < read_support``

diff --git a/docs/pvacseq/filter_commands.rst b/docs/pvacseq/filter_commands.rst
@@ -71,6 +71,12 @@ to ``lowest``, this threshold is applied to the ``Best MT Percentile`` column. W
 it is set to ``median``, the threshold is applied to the ``Median MT
 Percentile`` column.
 
+When the ``--percentile-threshold`` flag is set, the candidate inclusion strategy can be
+specified by using the ``--percentile-threshold-strategy`` parameter. The parameter has two
+options ``conservative`` (default) and ``exploratory``. The 'conservative' option requires a candidate 
+to pass BOTH the binding threshold and percentile threshold, while the 'exploratory' option requires
+a candidate to pass EITHER the binding threshold or percentile threshold.
+
 By default, entries with ``NA`` values will be included in the output. This
 behavior can be turned off by using the ``--exclude-NAs`` flag.
 

diff --git a/docs/pvacseq/output_files.rst b/docs/pvacseq/output_files.rst
@@ -421,6 +421,11 @@ To tier the Best Peptide, several cutoffs can be adjusted using arguments provid
    * - ``--percentile-threshold``
      - When set, use this threshold to filter epitopes on the %ile MT score in addition to having to meet the binding threshold.
      - None
+   * - ``--percentile-threshold-strategy``
+     - Specify the candidate inclusion strategy. The ``conservative`` option requires a candidate to pass BOTH the binding threshold
+       and percentile threshold (if set). The ``exploratory`` option requires a candidate to pass EITHER the binding threshold or
+       the percentile threshold.
+     - conservative
    * - ``--tumor-purity``
      - Value between 0 and 1 indicating the fraction of tumor cells in the tumor sample. Information is used for a simple estimation of
        whether variants are subclonal or clonal based on VAF. If not provided, purity is estimated directly from the VAFs.
@@ -483,9 +488,11 @@ Criteria Details
 .. list-table::
 
    * - Binding Criteria
-     - Pass if Best Peptide is a strong binder
+     - Pass if Best Peptide is strong binder
      - ``IC50 MT < binding_threshold`` and ``%ile MT < percentile_threshold``
-       (if ``--percentile-threshold`` parameter is set)
+       (if ``--percentile-threshold`` parameter is set and 'conservative' ``--percentile-threshold-strategy`` is used) or
+       ``IC50 MT < binding_threshold`` or ``%ile MT < percentile_threshold``
+       (if 'exploratory' ``--percentile-threshold-strategy`` is used)
    * - Expression Criteria
      - Pass if Best Transcript is expressed
      - ``Allele Expr > trna_vaf * expn_val``

diff --git a/docs/pvacsplice/filter_commands.rst b/docs/pvacsplice/filter_commands.rst
@@ -59,6 +59,12 @@ to ``lowest``, this threshold is applied to the ``Best MT Percentile`` column. W
 it is set to ``median``, the threshold is applied to the ``Median MT
 Percentile`` column.
 
+When the ``--percentile-threshold`` flag is set, the candidate inclusion strategy can be
+specified by using the ``--percentile-threshold-strategy`` parameter. The parameter has two
+options ``conservative`` (default) and ``exploratory``. The 'conservative' option requires a candidate 
+to pass BOTH the binding threshold and percentile threshold, while the 'exploratory' option requires
+a candidate to pass EITHER the binding threshold or percentile threshold.
+
 By default, entries with ``NA`` values will be included in the output. This
 behavior can be turned off by using the ``--exclude-NAs`` flag.
 

diff --git a/docs/pvacsplice/output_files.rst b/docs/pvacsplice/output_files.rst
@@ -368,6 +368,11 @@ To tier the Best Peptide, several cutoffs can be adjusted using arguments provid
    * - ``--percentile-threshold``
      - When set, use this threshold to filter epitopes on the %ile MT score in addition to having to meet the binding threshold.
      - None
+   * - ``--percentile-threshold-strategy``
+     - Specify the candidate inclusion strategy. The ``conservative`` option requires a candidate to pass BOTH the binding threshold
+       and percentile threshold (if set). The ``exploratory`` option requires a candidate to pass EITHER the binding threshold or
+       the percentile threshold.
+     - conservative
    * - ``--tumor-purity``
      - Value between 0 and 1 indicating the fraction of tumor cells in the tumor sample. Information is used for a simple estimation of
        whether variants are subclonal or clonal based on VAF. If not provided, purity is estimated directly from the VAFs.
@@ -427,9 +432,11 @@ Criteria Details
 .. list-table::
 
    * - Binding Criteria
-     - Pass if Best Peptide is a strong binder
+     - Pass if Best Peptide is strong binder
      - ``IC50 MT < binding_threshold`` and ``%ile MT < percentile_threshold``
-       (if ``--percentile-threshold`` parameter is set)
+       (if ``--percentile-threshold`` parameter is set and 'conservative' ``--percentile-threshold-strategy`` is used) or
+       ``IC50 MT < binding_threshold`` or ``%ile MT < percentile_threshold``
+       (if 'exploratory' ``--percentile-threshold-strategy`` is used)
    * - Expression Criteria
      - Pass if Best Transcript is expressed
      - ``Allele Expr > trna_vaf * expn_val``