Implement channel-based Quarto notebook reporting process

.gitignore

@@ -29,6 +29,15 @@ notebooks/*
 !notebooks/sample_stats_template.qmd
 !notebooks/compare_stats_template.qmd
 !notebooks/gliph2_report_template.qmd
+!notebooks/template_qc.qmd
+!notebooks/template_sample.qmd
+!notebooks/template_sharing.qmd
+!notebooks/template_overlap.qmd
+!notebooks/template_pheno_bulk.qmd
+!notebooks/template_pheno_sc.qmd
+!notebooks/template_gliph.qmd
+!notebooks/template_details_part1.qmd
+!notebooks/template_details_part2.qmd
 
 ## Bash
 tmp

conf/modules.config

@@ -47,4 +47,12 @@ process {
         label = params.matrix_sparsity == 'sparse' ? 'process_medium' : ['process_high', 'process_high_memory']
     }
 
+    withName: RENDER_NOTEBOOK {
+        publishDir = [
+            path: { "${params.outdir}/reports" },
+            mode: params.publish_dir_mode,
+            saveAs: { filename -> filename.equals('versions.yml') ? null : filename }
+        ]
+    }
+
 }

modules/local/compare/gliph2.nf

@@ -50,36 +50,3 @@ process GLIPH2_TURBOGLIPH {
     cat \$input_file > ${patient}/local_similarities.txt
     """
 }
-
-process GLIPH2_PLOT {
-    label 'process_low'
-
-    input:
-    path gliph2_report_template
-    path(motifs)
-    path(clone_network)
-    path(cluster_member_details)
-    path(convergence_groups)
-    path(global_similarities)
-    path(local_similarities)
-    path(parameter)
-
-    output:
-    path 'gliph2_report.html'
-
-    script:   
-    """
-    ## copy quarto notebook to output directory
-    cp $gliph2_report_template gliph2_report.qmd
-
-    ## render qmd report to html
-    quarto render gliph2_report.qmd \
-        -P project_name:$params.project_name \
-        -P workflow_cmd:'$workflow.commandLine' \
-        -P results_dir:'./' \
-
-        # -P clusters:$cluster_member_details \
-        # -P cluster_stats:$convergence_groups \
-        --to html
-    """
-}

modules/local/report/render_notebook.nf

@@ -0,0 +1,32 @@
+// Generic process to render a Quarto notebook to HTML
+process RENDER_NOTEBOOK {
+    tag "${report_name}"
+    label 'process_single'
+
+    input:
+    tuple val(report_name), path(notebook), val(data_dir)
+    val project_name
+    val workflow_cmd
+
+    output:
+    path "${report_name}.html"
+
+    script:
+    """
+    ## copy quarto notebook to working directory
+    cp $notebook ${report_name}.qmd
+
+    ## render qmd report to html
+    quarto render ${report_name}.qmd \\
+        -P project_name:${project_name} \\
+        -P workflow_cmd:'${workflow_cmd}' \\
+        -P project_dir:${data_dir} \\
+        -P sample_table:${file(params.samplesheet)} \\
+        --to html
+    """
+
+    stub:
+    """
+    touch ${report_name}.html
+    """
+}

nextflow.config

@@ -31,8 +31,16 @@ params {
     // Sample + compare parameters
     workflow_level = "sample,compare"
     project_name = "tcrtoolkit_"+ new Date().format("yyyy-MM-dd_HH-mm-ss")
-    sample_stats_template = "${projectDir}/notebooks/sample_stats_template.qmd"
-    compare_stats_template = "${projectDir}/notebooks/compare_stats_template.qmd"
+    sample_stats_template = "${projectDir}/notebooks/template_sample.qmd"
+    compare_stats_template = "${projectDir}/notebooks/template_sharing.qmd"
+
+    // Additional report templates
+    qc_template            = "${projectDir}/notebooks/template_qc.qmd"
+    overlap_template       = "${projectDir}/notebooks/template_overlap.qmd"
+    pheno_bulk_template    = "${projectDir}/notebooks/template_pheno_bulk.qmd"
+    pheno_sc_template      = "${projectDir}/notebooks/template_pheno_sc.qmd"
+    details_part1_template = "${projectDir}/notebooks/template_details_part1.qmd"
+    details_part2_template = "${projectDir}/notebooks/template_details_part2.qmd"
 
     // Sample stats metadata parameters
     samplechart_x_col = 'timepoint'
@@ -50,7 +58,7 @@ params {
 
     // GLIPH2 parameters
     use_gliph2 = false
-    gliph2_report_template = "${projectDir}/notebooks/gliph2_report_template.qmd"
+    gliph2_report_template = "${projectDir}/notebooks/template_gliph.qmd"
     ref_files = "${projectDir}/assets/gliph2_files"
 
     local_min_pvalue = "0.001"

notebooks/template_details_part1.qmd

@@ -0,0 +1,104 @@
+---
+title: "Details"
+format:
+  html:
+    theme: flatly
+    toc: true
+    toc_depth: 3
+    code-fold: true
+    embed-resources: false
+    number-sections: true
+    smooth-scroll: true
+    grid:
+      body-width: 1000px
+      margin-width: 300px
+execute:
+  cache: false
+  warnings: false
+jupyter: python3
+---
+
+Thank you for using TCRtoolkit! This report is generated from the data you provided. 
+
+:::{.callout-note collapse="true"}
+## Document Information
+**Current Version:** 1.0-beta   
+**Last Updated:** March 2026  
+**Maintainer:** BTC Data Science Team   
+**Notes:** 
+:::
+
+::: {.callout-note collapse="true"}
+## Notebook Analysis Scope
+This notebook a more detailed analysis of the samples being analyzed.
+:::
+
+```{python}
+#| tags: [parameters]
+#| include: false
+
+# ---------------------------------------------------------
+# BASE PARAMETERS 
+# ---------------------------------------------------------
+workflow_cmd = '<command used to run the pipeline>'
+project_name='<project_name>'
+project_dir='<path/to/project_dir>'
+sample_table='<path/to/sample_table.csv>'
+
+timepoint_col = 'timepoint'
+timepoint_order_col = 'timepoint_order'
+alias_col = 'alias'
+subject_col = 'subject_id'
+
+```
+
+```{python}
+#| include: false
+
+# ---------------------------------------------------------
+# DERIVED PATHS 
+# ---------------------------------------------------------
+
+# Define files 
+project_dir=f"{project_dir}/{project_name}"
+
+```
+
+# Before You Begin
+
+This pipeline can be used to analyze both **single-cell and bulk TCR data**. Please see the note below to understand some of the **implications** depending on the data type you have:
+
+::: {.callout-note title="Single-cell vs Bulk Data analysis" collapse="true"}
+**<u>Definition of “counts”</u>**  
+- **Single-cell**:  
+  `counts` represent the number of distinct cells carrying a specific clonotype. For example, a count of 12 indicates that 12 individual cells were encapsulated and sequenced.  
+- **Bulk**:  
+  `counts` represent the abundance of sequencing reads (or UMIs) supporting a clonotype. The biological interpretation depends heavily on the starting material:
+
+  - **RNA (cDNA):** Counts are a composite metric of Cellular Abundance $\times$ Transcriptional Expression. Since activation status affects TCR mRNA levels, a high count could indicate a large clone or a highly active small clone. Normalization strategies can mitigate, but not eliminate, this expression bias.
+  - **DNA (gDNA):** Counts are a direct proxy for Cell Number (e.g., Adaptive ImmunoSEQ). Because T-cell genomic templates are constant (one productive rearrangement per cell), DNA sequencing avoids expression bias and allows for accurate estimation of clone size.
+
+**<u>TCR chains</u>**  
+- **Single-cell**:  
+  It's common to have paired α/β chains per cell. However we only focus on the Beta chain here.  
+- **Bulk**:  
+  In bulk repertoire sequencing, you usually amplify TCRα and TCRβ chains separately. The resulting data contains lists of α clonotypes and lists of β clonotypes, but no information about which α and β belong to the same T cell. We focus only on the Beta chain.  
+
+**<u>Diversity & clonality metrics</u>**  
+- **Single-cell**:  
+  Sensitive to sampling (10^3 – 10^5 cells typical).
+  Rare clonotypes may be missed, but you can study functional heterogeneity within clones.  
+- **Bulk**:  
+  Captures broad repertoire diversity (10^5 – 10^6 clonotypes).
+  More accurate for richness, evenness, overlap across samples.
+
+**<u>Downstream biological analyses</u>**  
+- **Single-cell**:  
+  It is possile to link TCRs to phenotypic states (exhaustion, activation, tissue localization), which allows the study of clonotype heterogeneity.  
+- **Bulk**:    
+  It focuses on population-level measures  
+:::
+
+
+{{< include ./template_sample.qmd >}}
+