Merge pull request #1137 from griffithlab/pvacview_neofox_reviews

pVACview updates for paper review

docs/pvacview/custom_module/custom_upload.rst

@@ -4,8 +4,8 @@
 
 .. _custom_upload:
 
-Custom Upload
--------------
+Usage
+-----
 
 Upload
 ______

docs/pvacview/neofox_module/neofox_features.rst

@@ -12,12 +12,19 @@ _____________________________________
 
 The **Annotated Neoantigen Candidates** table is generated as output from NeoFox and includes many annotations based on published neoantigen features.
 Users can page through the candidates, sort by any feature, and select one or more candidates for further investgation. We have marked the
-features we find most informative with an asterisk.
+features we find most informative with an asterisk. These columns are selected by default but additional columns can
+be selected using the "Column Visibility" dropdown.
+
+Colored heatmap cell backgrounds on binding affinity and rank columns indicate where the value falls in comparison
+to the default 500 nM binding affinity and 0.5 percentile thresholds, respectively. Green background colors indicate
+a value below the threshold while yellow to red colors indicate a progressively higher value above the threshold.
+Horizontal barplot backgrounds on the expression and VAF columns reflect how close the values are to the "ideal"
+values of 50 and 1, respectively.
 
 .. figure:: ../../images/screenshots/pvacview-neofox-maintable.png
     :width: 1000px
     :align: right
-    :alt: pVACview Upload
+    :alt: Screenshot of NeoFox module annotated neoantigen candidates table
     :figclass: align-left
 
 Comparative Violin Plots
@@ -29,7 +36,8 @@ five features which we found informative.
 
 .. figure:: ../../images/screenshots/pvacview-neofox-violin-two.png
             :width: 1000px
-            :align: left
+            :align: right
+            :alt: Screenshot of NeoFox module violin plots
             :figclass: align-left
 
 Dynamic Scatter Plot
@@ -44,7 +52,8 @@ by using the camera icon at the top right corner of the plot.
 
 .. figure:: ../../images/screenshots/pvacview-neofox-dynamic-scatter.png
             :width: 1000px
-            :align: left
+            :align: right
+            :alt: Screenshot of NeoFox module dynamic scatter plots
             :figclass: align-left
 
 

docs/pvacview/neofox_module/neofox_upload.rst

@@ -4,8 +4,8 @@
 
 .. _neofox_upload:
 
-NeoFox Upload
----------------
+Usage
+-----
 
 Upload
 ______
@@ -19,7 +19,7 @@ The module expects all NeoFox annotated features to be in in the file but can al
 .. figure:: ../../images/screenshots/pvacview-neofox-upload.png
     :width: 1000px
     :align: right
-    :alt: pVACview Upload
+    :alt: Screenshot of NeoFox module upload interface
     :figclass: align-left
 
 
@@ -34,14 +34,18 @@ Upon successfully uploading the correct data file, users can now explore the dif
 .. figure:: ../../images/screenshots/pvacview-neofox-maintable.png
     :width: 1000px
     :align: right
-    :alt: pVACview Upload
+    :alt: Screenshot of NeoFox module annotated neoantigen candidates table
     :figclass: align-left
 
 There are three features that can be used to explore data:
 
 - **Annotated Neoantigen Candidates Table**
 
   - Main table showcasing all candidates
+  - Pre-selected columns of interest (denoted by an asterisk)
+  - Colored heatmap and horizontal barplot cell backgrounds help quickly interpret the value of expression, VAF,
+    binding affinity and rank columns
+  - Evaluate candidates as accepted, rejected, or requiring further review
 
 - **Comparative Violin Plots**
 
@@ -64,13 +68,43 @@ To investigate different candidates simple click one or more row from the **Anno
 .. figure:: ../../images/screenshots/pvacview-neofox-violinplots_selected.png
     :width: 1000px
     :align: right
-    :alt: pVACview Upload
+    :alt: Screenshot of NeoFox module violin plot
     :figclass: align-left
 
 Users can explore all candidates together using the **Dynamic Scatter Plot**. To identify a candidates of interest from the scatter plot, simple mouse-over the point of interest for the specific information about that candidate to be shown.
 
 .. figure:: ../../images/screenshots/pvacview-neofox-dynamicscatterplot_selected.png
     :width: 1000px
     :align: right
-    :alt: pVACview Upload
+    :alt: Screenshot NeoFox module dynamic scatter plot
+    :figclass: align-left
+
+Evaluating and Commenting
+*************************
+
+The evaluation buttons at the right of each candidate row can be used to capture the final decision on whether to
+accept, reject, or further review the candidate. The total counts for each type of evaluation are displayed in the
+"Peptide Evaluation Overview" panel.
+
+Users are able to leave a comment on all selected candidates by using the form in the panel on the top right of the
+page. This panel also displays the comments left on each selected candidate. Both the selected evaluation and
+comment are included in the exported table.
+
+.. figure:: ../../images/screenshots/pvacview-neofox-evaluation.png
+    :width: 1000px
+    :align: right
+    :alt: Screenshot of NeoFox module Evaluation and Comment functionality
+    :figclass: align-left
+
+Export
+______
+
+After investigating and evaluating each candidate, users can export the main table, including the final evaluation
+and comment for each candidate. After browsing to the "Export Data" tab, clicking the "Download as TSV" or "Download
+as excel" button will download the table in the desired file format."
+
+.. figure:: ../../images/screenshots/pvacview-neofox-export.png
+    :width: 1000px
+    :align: right
+    :alt: Screenshot of NeoFox module export interface
     :figclass: align-left

docs/pvacview/pvacseq_module/pvacseq_upload.rst

@@ -10,8 +10,8 @@
 .. role:: large
 .. role:: bold
 
-Upload
----------------
+Usage
+-----
 
 The pVACview user interface has four sections:
 
@@ -160,18 +160,21 @@ used originally by clicking the ``Reset to original paramters`` button.
 Investigating Different Variants
 ********************************
 
-To investigate a specific variant in detail (on both the transcript and peptide levels), you will need to click on the investigate button located in the select column of the main aggregate report table (last column).
-Afterwards, you may choose to select a rating for the neoantigen candidate using the Eval column. By default, all peptides are initially in a Pending state when the report is generated from pVACseq. Based on
-exploration and evaluation of the features provided, you can mark the peptide as either ``Accept``, ``Reject``, or ``Review``. Your current state of selections are also counted and shown in the ``Peptide Evaluation Overview`` box.
+To investigate a specific variant in detail (on both the transcript and peptide levels), you will need to click on
+the candidate's row in the main aggregate report table. Afterwards, you may choose to select a rating for the
+neoantigen candidate using the three buttons on the right of the candidate's row. By default, all peptides are initially in a Pending state when the report is generated from pVACseq. Based on
+exploration and evaluation of the features provided an none of the buttons are selected. You can mark the peptide as
+either "Accept" (thumb-up button), "Reject" (thumbs-down button), or "Review" (flag button). Your current state of
+selections are also counted and shown in the ``Peptide Evaluation Overview`` box.
 
 .. figure:: ../../images/screenshots/pvacview-comments.png
     :width: 800px
     :align: right
-    :alt: pVACview Upload
+    :alt: pVACview comment interface
     :figclass: align-left
 
 Users can add comments to each line of variants they are investigating. These comments can be reviewed in the Export page
-and will be in the final output (either tsv or excel) when downloaded. This column is by default ``N/A`` unless the input
+and will be in the final output (either tsv or excel) when downloaded. This column is by default ``No comments`` unless the input
 aggregate report has a ``Comments`` column pre-specified.
 
 :large:`Export`

docs/pvacview/pvacseq_module/pvacseq_vignette.rst

@@ -132,7 +132,9 @@ To set your own Tier-setting parameters, expand the **Advanced Options: Regenera
 
 The second row of the page spans the **Aggregate Report of Best Candidates by Variant** section, which lists all neoantigen candidates in the provided input. Candidates with a higher Tier will be shown first, followed by candidates of lower Tiers (Order of Tiers: ``Pass``, ``Anchor``, ``Subclonal``, ``Low Expr``, ``NoExpr``, ``Poor`` - see `Tiering criteria <https://pvactools.readthedocs.io/en/latest/pvacseq/output_files.html#tiers>`_). Genes that match with the user-input genes of interest list will have a green box around them (for example, ARID1B and MSH6 are covered by a green box in this demo). This feature can be useful for highlighting neoantigens derived from cancer driver genes.
 
-To view the variant, transcript, and peptide level information of a desired candidate, click on the ``Investigate`` button on the right side of the row for that candidate. The candidate currently under investigation will be framed in blue. The number of the row currently being investigated is indicated at the bottom of this section.
+To view the variant, transcript, and peptide level information of a desired candidate, click on the candidate's row
+to select it. The candidate currently under investigation will have a grey background. The number of the row
+currently being investigated is indicated at the bottom of this section.
 
 .. figure:: ../../images/screenshots/vignette/pvacview-aggrReportTable_withCGCgenesHighlighted.png
     :width: 1000px
@@ -237,23 +239,19 @@ Beside Class-I peptide, the best predicted Class-II peptide from user-input can
 
 **Decision:**
 
-Given all the information above, we may conclude that the reviewed Class I peptide is potentially a good binder and choose to Accept this candidate in the ``Eval`` drop-down menu.
-
-.. figure:: ../../images/screenshots/vignette/KIF1C-new/KIF1C_11_Decision_1.png
+.. figure:: ../../images/screenshots/vignette/KIF1C-new/KIF1C_11_Decision.png
     :width: 1000px
     :align: right
     :alt: pVACview Vignette
     :figclass: align-left
 
-.. figure:: ../../images/screenshots/vignette/KIF1C-new/KIF1C_11_Decision_2.png
-    :width: 1000px
-    :align: right
-    :alt: pVACview Vignette
-    :figclass: align-left
+Given all the information above, we may conclude that the reviewed Class I peptide is potentially a good binder and
+choose to accept this candidate by clicking the thumbs-up button.
 
 
 Example 2: a good candidate derived from a variant with multiple transcript sets: ADAR-E806V: AERMGFTVV
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
 .. figure:: ../../images/screenshots/vignette/ADAR/ADAR_0.png
     :width: 1000px
     :align: right
@@ -350,7 +348,8 @@ The candidate sequence also has no match with any known peptide in the human pro
 
 **Decision:**
 
-Given all the information above, we can conclude that the reviewed Class I peptide is potentially a good binder and choose to Accept this candidate in the ``Eval`` drop-down menu.
+Given all the information above, we can conclude that the reviewed Class I peptide is potentially a good binder and
+choose to accept by clicking the thumbs-up button.
 
 Example 3: a bad candidate: ZNF141-H389Y: KIYTGEKPY
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -376,7 +375,8 @@ These potentially problematic characteristics are also flagged by the red boxes
 
 **Decision:**
 
-Since the candidate peptide has a match in the reference proteome, we will reject this candidate.
+Since the candidate peptide has a match in the reference proteome, we will reject this candidate by clicking the
+thumbs-down button.
 
 
 Export

pvactools/tools/pvacview/anchor_and_helper_functions.R

@@ -253,7 +253,7 @@ calculate_mutation_info <- function(metrics_data_row) {
   return(diff_positions)
 }
 ##Generate Tiering for given variant with specific cutoffs
-tier <- function(variant_info, anchor_contribution, dna_cutoff, allele_expr_cutoff, mutation_pos_list, hla_allele, tsl, meta_data, anchor_mode, use_allele_specific_binding_thresholds, binding_threshold) {
+tier <- function(variant_info, anchor_contribution, dna_cutoff, allele_expr_cutoff, mutation_pos_list, hla_allele, tsl, meta_data, anchor_mode, use_allele_specific_binding_thresholds, binding_threshold, percentile_threshold) {
   mt_binding <- as.numeric(variant_info["IC50 MT"])
   wt_binding <- as.numeric(variant_info["IC50 WT"])
   mt_percent <- as.numeric(variant_info["%ile MT"])
@@ -269,9 +269,8 @@ tier <- function(variant_info, anchor_contribution, dna_cutoff, allele_expr_cuto
   trna_vaf <- as.numeric(meta_data["trna_vaf"])
   trna_cov <- as.numeric(meta_data["trna_cov"])
   percentile_filter <- FALSE
-  percentile_threshold <- NULL
-  if (!is.null(meta_data[["percentile_threshold"]])) {
-    percentile_threshold <- as.numeric(meta_data[["percentile_threshold"]])
+  if (!is.null(percentile_threshold)) {
+    percentile_threshold <- as.numeric(percentile_threshold)
     percentile_filter <- TRUE
   }
   tsl_max <- as.numeric(meta_data["maximum_transcript_support_level"])
@@ -374,7 +373,7 @@ tier <- function(variant_info, anchor_contribution, dna_cutoff, allele_expr_cuto
   return("Poor")
 }
 #Determine the Tier Count for given variant with specific cutoffs
-tier_numbers <- function(variant_info, anchor_contribution, dna_cutoff, allele_expr_cutoff, mutation_pos_list, hla_allele, tsl, meta_data, anchor_mode, allele_specific_binding_thresholds, use_allele_specific_binding_thresholds, binding_threshold) {
+tier_numbers <- function(variant_info, anchor_contribution, dna_cutoff, allele_expr_cutoff, mutation_pos_list, hla_allele, tsl, meta_data, anchor_mode, allele_specific_binding_thresholds, use_allele_specific_binding_thresholds, binding_threshold, percentile_threshold) {
   mt_binding <- as.numeric(variant_info["IC50 MT"])
   wt_binding <- as.numeric(variant_info["IC50 WT"])
   mt_percent <- as.numeric(variant_info["%ile MT"])
@@ -390,9 +389,8 @@ tier_numbers <- function(variant_info, anchor_contribution, dna_cutoff, allele_e
   trna_vaf <- as.numeric(meta_data["trna_vaf"])
   trna_cov <- as.numeric(meta_data["trna_cov"])
   percentile_filter <- FALSE
-  percentile_threshold <- NULL
-  if (!is.null(meta_data[["percentile_threshold"]])) {
-    percentile_threshold <- as.numeric(meta_data[["percentile_threshold"]])
+  if (!is.null(percentile_threshold)) {
+    percentile_threshold <- as.numeric(percentile_threshold)
     percentile_filter <- TRUE
   }
   tsl_max <- as.numeric(meta_data["maximum_transcript_support_level"])

pvactools/tools/pvacview/custom_ui.R

@@ -23,7 +23,7 @@ custom_tab <- tabItem("custom",
                     ),
                     box(
                         title = "Option 4: Upload your own custom data files", status = "primary", solidHeader = TRUE, width = NULL,
-                        HTML("<h5><b>(Required)</b> Please upload your neofox output file. This file should be a table generated by NeoFox with the suffix “_neoantigen_candidates_annotated.tsv“"),
+                        HTML("<h5><b>(Required)</b> Please upload your TSV file."),
                         br(), br(),
                         uiOutput("custom_upload_ui")
                     ),

pvactools/tools/pvacview/neofox_ui.R

@@ -33,6 +33,17 @@ neofox_tab <- tabItem("neofox",
             )
         ),
         tabPanel(title = "Explore Data", value = "neofox_explore",
+            fluidRow(
+                box(width = 4, solidHeader = TRUE, title = "Peptide Evaluation Overview", status = "primary",
+                    tableOutput("neofox_checked"), style = "overflow-x: scroll;font-size:100%"),
+                box(width = 8,
+                    title = "Add Comments for last selected variant(s)",
+                    status = "primary", solidHeader = TRUE, collapsible = TRUE,
+                    textAreaInput("neofox_comments", label = "Please add/update your comments for the selected variant(s)", value = ""),
+                    actionButton("neofox_comment", "Update Comment Section"),
+                    h5("Comment:"), tableOutput("neofox_comment_text"),
+                    style = "font-size:100%")
+            ),
             fluidRow(
                     box(width = 12,
                         title = "Annotated Neoantigen Candidates using NeoFox",
@@ -42,22 +53,18 @@ neofox_tab <- tabItem("neofox",
                         DTOutput("neofoxTable") %>% withSpinner(color = "#8FCCFA"),
                         span("Currently investigating row(s): ", verbatimTextOutput("neofox_selected")),
                         style = "overflow-x: scroll;font-size:100%",
-                        "* indicates variable of interested designated by authors"
+                        "* indicates variable of interest designated by authors"
                         )
-
             ),
-
             fluidRow(
               box(width = 12, 
                   title = "Comparative Violin Plots",  status = "primary", solidHeader = TRUE, collapsible = TRUE,
                   h4("Violin Plots showing distribution of various neoantigen features for selected variants."),
                   uiOutput("noefox_features_ui"),
                   plotOutput(outputId = "neofox_violin_plots_row1") %>% withSpinner(color = "#8FCCFA"),
-                  "* indicates variable of interested designated by authors"
+                  "* indicates variable of interest designated by authors"
                   )
-
             ),
-
             fluidRow(
               box(width = 12,
                   title = "Dynamic Scatter Plot", status = "primary", solidHeader = TRUE, collapsible = TRUE,
@@ -77,16 +84,24 @@ neofox_tab <- tabItem("neofox",
                       uiOutput("max_color"),
                       # size
                       uiOutput("size_neofox"),
-                      "* indicates variable of interested designated by authors"
+                      "* indicates variable of interest designated by authors"
                     ),
                     mainPanel(
                       align = "center",
                       plotlyOutput(outputId = "scatter", height = "800px") %>% withSpinner(color = "#8FCCFA"),
                     )
-
               )
             )
-
+        ),
+        ## EXPORT TAB ##
+        tabPanel(title = "Export Data", value = "neofox_export",
+          fluidRow(
+            textInput("exportNeofoxFileName", "Export filename: ", value = "Annotated.Neoantigen_Candidates", width = NULL, placeholder = NULL)
+          ),
+          fluidRow(
+            column(12,
+                   DTOutput("NeofoxExportTable") %>% withSpinner(color = "#8FCCFA"))
+          )
         )
     )
 )