Split detail report notebooks by workflow level

README.md

@@ -63,22 +63,23 @@ Levels can be combined: `--workflow_level sample,patient,compare`
 
 ## HTML Reports
 
-After the pipeline finishes, `TCRtoolkit` generates interactive HTML reports using [Quarto](https://quarto.org/). Four main report notebooks are rendered automatically:
+After the pipeline finishes, `TCRtoolkit` generates interactive HTML reports using [Quarto](https://quarto.org/). Report notebooks are rendered automatically depending on which `--workflow_level` stages ran:
 
-| Notebook | Description |
-|---|---|
-| `template_qc.qmd` | Quality control metrics and filtering summary |
-| `template_discovery_brief.qmd` | Repertoire discovery most relevant information  |
-| `template_details_part1.qmd` | Detailed repertoire analysis, part 1 |
-| `template_details_part2.qmd` | Detailed repertoire analysis, part 2  |
+| Notebook | Rendered when | Description |
+|---|---|---|
+| `template_qc.qmd` | `sample` | Quality control metrics and filtering summary |
+| `template_discovery_brief.qmd` | `sample` + `compare` | Highest-impact repertoire findings |
+| `template_details_sample.qmd` | `sample` | Detailed per-sample repertoire analysis |
+| `template_details_compare.qmd` | `sample` + `compare` | Detailed cross-sample / longitudinal comparison analysis |
+| `template_details_patient.qmd` | `sample` + `patient` | Patient-level clonotype clustering (GIANA, and GLIPH2 when `--use_gliph2`) |
 
 ### Conditional Report Sections
 
 Certain sub-reports are automatically appended based on input and workflow options:
 
 - `--input_format adaptive` → includes bulk phenotype report
-- `--workflow_level sample,patient,compare` (Patient workflow enabled) → includes patient-level clonotype analysis
-- `--use_gliph2` → additionally includes GLIPH2 clustering report
+- `--workflow_level` includes `sample` and `patient` → renders `template_details_patient.qmd` (patient-level clonotype analysis)
+- `--use_gliph2` → additionally includes GLIPH2 clustering in the patient details report
 
 ## Key Parameters
 

nextflow.config

@@ -71,11 +71,10 @@ params {
     //reports
     template_qc = "${projectDir}/notebooks/template_qc.qmd"
     template_discovery_brief = "${projectDir}/notebooks/template_discovery_brief.qmd"
-    template_details_part1 = "${projectDir}/notebooks/template_details_part1.qmd"
-    template_details_part2 = "${projectDir}/notebooks/template_details_part2.qmd"
+    template_details_sample = "${projectDir}/notebooks/template_details_sample.qmd"
+    template_details_compare = "${projectDir}/notebooks/template_details_compare.qmd"
+    template_details_patient = "${projectDir}/notebooks/template_details_patient.qmd"
     template_pheno_bulk = "${projectDir}/notebooks/template_pheno_bulk.qmd"
-    template_patient_clustering_on = "${projectDir}/notebooks/template_patient_clustering_on.qmd"
-    template_patient_clustering_off = "${projectDir}/notebooks/template_patient_clustering_off.qmd"
 
     // ══════════════════════════════════════════════════════════════════════
     // SINGLE-CELL modality (integration) — see IMPLEMENTATION_SPEC.md

nextflow_schema.json

@@ -124,25 +124,21 @@
                     "type": "string",
                     "description": "Path to discovery brief notebook template."
                 },
-                "template_details_part1": {
+                "template_details_sample": {
                     "type": "string",
-                    "description": "Path to details (part 1) notebook template."
+                    "description": "Path to the sample-level details notebook template (rendered when the sample workflow_level is run)."
                 },
-                "template_details_part2": {
+                "template_details_compare": {
                     "type": "string",
-                    "description": "Path to details (part 2) notebook template."
+                    "description": "Path to the comparison-level details notebook template (rendered when the sample and compare workflow_levels are run)."
                 },
-                "template_pheno_bulk": {
-                    "type": "string",
-                    "description": "Path to bulk (TCRpheno) phenotype notebook template."
-                },
-                "template_patient_clustering_on": {
+                "template_details_patient": {
                     "type": "string",
-                    "description": "Path to patient-level clustering (GIANA/GLIPH2) notebook template, used when patient workflow_level is run."
+                    "description": "Path to the patient-level details notebook template with GIANA/GLIPH2 clustering (rendered when the sample and patient workflow_levels are run)."
                 },
-                "template_patient_clustering_off": {
+                "template_pheno_bulk": {
                     "type": "string",
-                    "description": "Path to placeholder notebook template used when patient workflow_level is not run."
+                    "description": "Path to bulk (TCRpheno) phenotype notebook template."
                 }
             }
         },

notebooks/template_details_compare.qmd

@@ -0,0 +1,117 @@
+---
+title: "Details — Comparison"
+format:
+  html:
+    theme: flatly
+    toc: true
+    toc_depth: 3
+    code-fold: true
+    embed-resources: true
+    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 provides a detailed cross-sample and longitudinal comparison analysis
+(clonal dynamics, repertoire overlap, and TCR publicity).
+:::
+
+```{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'
+# Ordered comma-separated list of timepoint values, e.g. "Base,Week4,EOT" -
+# rank = position in the list. Empty string means: rank numerically if every
+# timepoint value parses as a number, otherwise alphabetically.
+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 possible 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_overlap.qmd >}}
+
+{{< include ./template_sharing.qmd >}}
+
+## Patient-level TCR clustering (GIANA/GLIPH2)
+
+::: {.callout-note}
+Patient-level clonotype clustering (GIANA and GLIPH2) is reported separately in
+the **Patient Details** report (`template_details_patient.html`), which is
+generated when `sample` and `patient` are both included in `--workflow_level`.
+:::

notebooks/template_details_part2.qmd → notebooks/template_details_patient.qmd

@@ -1,5 +1,5 @@
 ---
-title: "Details"
+title: "Details — Patient"
 format:
   html:
     theme: flatly
@@ -30,7 +30,8 @@ Thank you for using TCRtoolkit! This report is generated from the data you provi
 
 ::: {.callout-note collapse="true"}
 ## Notebook Analysis Scope
-This notebook provides a more detailed analysis of the samples being analyzed.
+This notebook provides patient-level clonotype clustering analysis (GIANA, and GLIPH2
+when `--use_gliph2` is enabled), aggregating all samples belonging to each individual.
 :::
 
 ```{python}
@@ -103,8 +104,6 @@ This pipeline can be used to analyze both **single-cell and bulk TCR data**. Ple
   It focuses on population-level measures  
 :::
 
-{{< include ./template_overlap.qmd >}}
+{{< include ./template_giana.qmd >}}
 
-{{< include ./template_sharing.qmd >}}
-
-{{< include ./template_patient_clustering.qmd >}}
+{{< include ./template_gliph.qmd >}}

notebooks/template_giana.qmd

@@ -18,6 +18,7 @@ notebook_results_dir = f"{project_dir}/notebook-analysis/"
 #| code-fold: true
 
 # 1. Load Packages
+import os
 import pandas as pd
 import plotly.express as px
 import plotly.graph_objects as go