docs: strengthen methods narrative and target scoring

Author: Caffeinated-Code

README.md

@@ -9,11 +9,13 @@ The primary analysis uses **GSE136103**, the Ramachandran et al. human cirrhosis
 Start here:
 
 1. [Project navigation](docs/project_navigation.md)
-2. [Rendered executive submission summary](reports/executive_submission_summary.html)
-3. [Translational ranked candidates](reports/tables/ranked_biomarker_target_candidates_translational.csv)
-4. [Marker validation figure](reports/figures/required_compartment_marker_dotplot.png)
-5. [Requirement traceability](reports/requirement_traceability.md)
-6. [Interactive dashboard](dashboard/README.md)
+2. [Analysis walkthrough](docs/analysis_walkthrough.md)
+3. [Rendered executive submission summary](reports/executive_submission_summary.html)
+4. [Translational ranked candidates](reports/tables/ranked_biomarker_target_candidates_translational.csv)
+5. [Scoring components](reports/tables/target_prioritization_scoring_components.csv)
+6. [Marker validation figure](reports/figures/required_compartment_marker_dotplot.png)
+7. [Requirement traceability](reports/requirement_traceability.md)
+8. [Interactive dashboard](dashboard/README.md)
 
 For implementation details:
 

dashboard/app.R

@@ -22,23 +22,40 @@ qc <- read_dash("qc_summary.csv")
 pseudobulk <- if (file.exists(file.path(data_dir, "pseudobulk_priority_gene_de.csv"))) read_dash("pseudobulk_priority_gene_de.csv") else tibble()
 hsc_validation <- if (file.exists(file.path(data_dir, "gse244832_hsc_candidate_validation.csv"))) read_dash("gse244832_hsc_candidate_validation.csv") else tibble()
 refined_clusters <- if (file.exists(file.path(data_dir, "refined_cluster_annotations.csv"))) read_dash("refined_cluster_annotations.csv") else tibble()
+score_components <- if (file.exists(file.path(data_dir, "target_prioritization_scoring_components.csv"))) read_dash("target_prioritization_scoring_components.csv") else tibble()
+score_method <- if (file.exists(file.path(data_dir, "target_prioritization_scoring_method.csv"))) read_dash("target_prioritization_scoring_method.csv") else tibble()
+blood_validation <- if (file.exists(file.path(data_dir, "gse136103_blood_candidate_marker_role_summary.csv"))) read_dash("gse136103_blood_candidate_marker_role_summary.csv") else tibble()
+mouse_validation <- if (file.exists(file.path(data_dir, "gse136103_mouse_candidate_ortholog_summary.csv"))) read_dash("gse136103_mouse_candidate_ortholog_summary.csv") else tibble()
 
 color_choices <- intersect(c("disease_state", "refined_cell_state", "reference_label", "compartment_call", "donor", "fraction"), colnames(umap))
+class_choices <- sort(unique(candidates$candidate_class))
+use_case_choices <- sort(unique(candidates$clinical_use_case))
+class_palette <- c(
+  "diagnostic biomarker" = "#2166AC",
+  "pharmacodynamic biomarker" = "#1B9E77",
+  "therapeutic target" = "#B2182B",
+  "future validation marker" = "#756BB1",
+  "mechanistic marker" = "#756BB1"
+)
 
 ui <- fluidPage(
   titlePanel("Human Liver Fibrosis Single-Cell Target Discovery"),
   sidebarLayout(
     sidebarPanel(
       selectInput("color_by", "UMAP color", choices = color_choices, selected = if ("refined_cell_state" %in% color_choices) "refined_cell_state" else "compartment_call"),
       selectInput("compartment", "DE compartment", choices = sort(unique(de$compartment))),
+      selectInput("candidate_class", "Candidate class", choices = c("All", class_choices), selected = "All"),
+      selectInput("clinical_use_case", "Clinical use case", choices = c("All", use_case_choices), selected = "All"),
       width = 3
     ),
     mainPanel(
       tabsetPanel(
         tabPanel("UMAP", plotlyOutput("umap_plot", height = 650)),
         tabPanel("Candidates", DTOutput("candidate_table")),
+        tabPanel("Scoring", DTOutput("score_component_table"), DTOutput("score_method_table")),
         tabPanel("Pseudobulk DE", DTOutput("pseudobulk_table")),
         tabPanel("GSE244832 HSC Validation", DTOutput("hsc_validation_table")),
+        tabPanel("Blood And Mouse Validation", DTOutput("blood_validation_table"), DTOutput("mouse_validation_table")),
         tabPanel("Reference Labels", DTOutput("refined_cluster_table")),
         tabPanel("Differential Expression", DTOutput("de_table")),
         tabPanel("Pathways", DTOutput("pathway_table")),
@@ -57,8 +74,40 @@ server <- function(input, output, session) {
     ggplotly(p, tooltip = "text")
   })
 
+  candidate_filtered <- reactive({
+    out <- candidates
+    if (!is.null(input$candidate_class) && input$candidate_class != "All") {
+      out <- out |> filter(candidate_class == input$candidate_class)
+    }
+    if (!is.null(input$clinical_use_case) && input$clinical_use_case != "All") {
+      out <- out |> filter(clinical_use_case == input$clinical_use_case)
+    }
+    out
+  })
+
   output$candidate_table <- renderDT({
-    datatable(candidates, filter = "top", options = list(pageLength = 15, scrollX = TRUE))
+    datatable(candidate_filtered(), filter = "top", options = list(pageLength = 15, scrollX = TRUE)) |>
+      formatStyle(
+        "candidate_class",
+        backgroundColor = styleEqual(names(class_palette), unname(class_palette)),
+        color = "white",
+        fontWeight = "bold"
+      ) |>
+      formatRound(c("total_score"), digits = 1)
+  })
+
+  output$score_component_table <- renderDT({
+    datatable(score_components, filter = "top", options = list(pageLength = 20, scrollX = TRUE)) |>
+      formatStyle(
+        "candidate_class",
+        backgroundColor = styleEqual(names(class_palette), unname(class_palette)),
+        color = "white",
+        fontWeight = "bold"
+      )
+  })
+
+  output$score_method_table <- renderDT({
+    datatable(score_method, options = list(pageLength = 10, scrollX = TRUE))
   })
 
   output$pseudobulk_table <- renderDT({
@@ -69,6 +118,14 @@ server <- function(input, output, session) {
     datatable(hsc_validation, filter = "top", options = list(pageLength = 20, scrollX = TRUE))
   })
 
+  output$blood_validation_table <- renderDT({
+    datatable(blood_validation, filter = "top", options = list(pageLength = 20, scrollX = TRUE))
+  })
+
+  output$mouse_validation_table <- renderDT({
+    datatable(mouse_validation, filter = "top", options = list(pageLength = 20, scrollX = TRUE))
+  })
+
   output$refined_cluster_table <- renderDT({
     datatable(refined_clusters, filter = "top", options = list(pageLength = 20, scrollX = TRUE))
   })

dashboard/data/gse136103_blood_candidate_marker_role_summary.csv

@@ -0,0 +1,17 @@
+validation_role,gene,samples,mean_log_normalized_expression,mean_pct_detected
+circulating_myeloid_context,LST1,4,1.3343463199399679,55.48370969280478
+secreted_matrix_remodeling,TIMP1,4,0.6619917796061532,40.101818303370415
+macrophage_state_marker,CD9,4,0.038048120039337725,2.7013580814840896
+macrophage_complement_context,C1QA,4,0.026110274992265804,1.7678401145062455
+stromal_receptor_target,PDGFRB,4,0.007210303549415873,0.5147877528961029
+macrophage_complement_context,C1QB,4,0.005130200286359322,0.3417686805349109
+macrophage_state_marker,GPNMB,4,0.003561616836668437,0.26947837432570065
+scar_endothelial_marker,PLVAP,4,0.002572164891081649,0.21862483537229
+macrophage_complement_context,C1QC,4,0.002495051662545635,0.1670326563328864
+fibrosis_burden,COL1A1,4,8.068243074285524e-4,0.05814926684975656
+stromal_receptor_target,PDGFRA,4,6.312585953687165e-4,0.03806519942244524
+macrophage_state_marker,TREM2,4,4.931101241608432e-4,0.041741162259420594
+secreted_stromal_biomarker,SMOC2,4,3.4047602948941326e-5,0.003537568982595161
+fibrosis_burden,COL3A1,4,0,0
+macrophage_state_marker,SPP1,4,0,0
+scar_endothelial_marker,ACKR1,4,0,0

dashboard/data/gse136103_mouse_candidate_ortholog_summary.csv

@@ -0,0 +1,17 @@
+human_gene,mouse_gene,validation_role,mean_log_normalized_expression_fibrotic,mean_log_normalized_expression_healthy,pct_detected_fibrotic,pct_detected_healthy,fibrotic_vs_healthy_delta,pct_detected_delta,interpretation
+TREM2,Trem2,macrophage_state_marker,1.0512293682579035,0.1331328390522342,60.29879211697393,11.651542649727768,0.9180965292056693,48.64724946724616,higher in fibrotic mouse liver
+C1QC,C1qc,macrophage_complement_context,2.1166999333017773,1.373105850671921,79.72027972027972,66.42468239564428,0.7435940826298564,13.295597324635438,higher in fibrotic mouse liver
+C1QA,C1qa,macrophage_complement_context,2.2173337754169737,1.5226222854522349,82.64462809917356,72.52268602540835,0.6947114899647389,10.121942073765211,higher in fibrotic mouse liver
+GPNMB,Gpnmb,macrophage_state_marker,0.6954218561153479,0.01688457047622952,39.41513032422123,1.3430127041742286,0.6785372856391184,38.072117620047,higher in fibrotic mouse liver
+SPP1,Spp1,macrophage_state_marker,0.6854508544171659,0.07278394495377646,38.97012078830261,7.041742286751361,0.6126669094633894,31.928378501551247,higher in fibrotic mouse liver
+C1QB,C1qb,macrophage_complement_context,2.2261960039816957,1.634115154725198,84.26573426573427,78.33030852994555,0.5920808492564977,5.935425735788712,higher in fibrotic mouse liver
+CD9,Cd9,macrophage_state_marker,0.981694369970411,0.5790053915909423,59.12269548633186,42.28675136116152,0.4026889783794687,16.835944125170336,higher in fibrotic mouse liver
+LST1,Lst1,circulating_myeloid_context,1.7657867924044535,1.3803306367507164,83.6935791481246,72.52268602540835,0.38545615565373703,11.170893122716251,higher in fibrotic mouse liver
+COL3A1,Col3a1,fibrosis_burden,0.16196628332815277,0.004006229211355708,11.951684678957406,0.2903811252268602,0.15796005411679706,11.661303553730546,similar between mouse liver samples
+TIMP1,Timp1,secreted_matrix_remodeling,0.12206173163532573,0.004486580326003503,9.218054672600127,0.5081669691470054,0.11757515130932222,8.709887703453122,similar between mouse liver samples
+COL1A1,Col1a1,fibrosis_burden,0.06850622101722408,3.356822199128776e-4,4.640813731722822,0.03629764065335753,0.06817053879731119,4.604516091069465,similar between mouse liver samples
+PDGFRA,Pdgfra,stromal_receptor_target,0.017943423432898092,3.4540484642526733e-4,1.5257469802924348,0.03629764065335753,0.017598018586472825,1.4894493396390773,similar between mouse liver samples
+PLVAP,Plvap,scar_endothelial_marker,0.045218356679129976,0.030123922329657955,3.9732994278448825,2.577132486388385,0.015094434349472021,1.3961669414564977,similar between mouse liver samples
+ACKR1,Ackr1,scar_endothelial_marker,0.016501014549237712,0.008632968619912145,1.621106166560712,0.7259528130671506,0.007868045929325567,0.8951533534935614,similar between mouse liver samples
+SMOC2,Smoc2,secreted_stromal_biomarker,0.005993300507604406,7.66409891581513e-4,0.540368722186904,0.07259528130671505,0.005226890616022893,0.46777344088018896,similar between mouse liver samples
+PDGFRB,Pdgfrb,stromal_receptor_target,0.009615166183415841,0.005044038769463812,1.1443102352193262,0.5081669691470054,0.004571127413952029,0.6361432660723207,similar between mouse liver samples