Implement changes from quarto-notebooks branch

README.md

@@ -37,3 +37,59 @@ With the update to [Nextflow strict syntax](https://docs.seqera.io/nextflow/stri
 nextflow run KarchinLab/TCRtoolkit \
     -params-file params.yml
 ```
+
+## Input Formats
+
+`TCRtoolkit` accepts three input formats, specified via `--input_format`:
+
+| Format | Description |
+|---|---|
+| `adaptive` | Adaptive Biotechnologies output files |
+| `cellranger` | 10x Genomics CellRanger 'airr_rearrangement.tsv' output files (single-cell pseudo-bulk) |
+| `airr` | AIRR-compliant tab-separated files |
+
+## Workflow Levels
+
+The pipeline supports multiple levels of analysis, controlled by `--workflow_level`:
+
+| Level | Description |
+|---|---|
+| `sample` | Per-sample QC and repertoire statistics |
+| `patient` | Patient-level clonotype aggregation and comparison |
+| `compare` | Cross-cohort repertoire comparison and overlap |
+
+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:
+
+| 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  |
+
+### Conditional Report Sections
+
+Certain sub-reports are automatically appended based on input and workflow options:
+
+- `--input_format cellranger` → includes single-cell phenotype report
+- `--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
+
+## Key Parameters
+
+| Parameter | Default | Description |
+|---|---|---|
+| `--samplesheet` | — | Path or URL to sample sheet CSV |
+| `--outdir` | `out` | Output directory |
+| `--input_format` | `airr` | Input format: `airr`, `adaptive`, or `cellranger` |
+| `--workflow_level` | `sample,compare` | Analysis level(s): `sample`, `patient`, `compare` |
+| `--use_gliph2` | `false` | Enable GLIPH2 CDR3 motif clustering |
+| `--sobject_gex` | — | Path to TSV file containing cell-barcode phenotypes for pseudo-bulk phenotyping |
+| `--max_memory` | `768.GB` | Maximum memory allocation |
+| `--max_cpus` | `192` | Maximum CPU allocation |
+

env.yml

@@ -9,7 +9,7 @@ dependencies:
   - numpy=1.25.2
   - scipy=1.11.3
   - seaborn=0.13.0
-  - dash=2.14.1
+  - dash>=2.15.0
   - matplotlib=3.8.1
   - pip=23.2.1
   - jupyterlab=4.0.8
@@ -26,6 +26,7 @@ dependencies:
   - rpy2=3.6.4
   - unzip
   - openjdk=8
+  - upsetplot=0.9.0
 
   # R and R packages
   - r-base=4.4.2

nextflow.config

@@ -37,6 +37,12 @@ params {
     vgene_subject_col = 'patient'
     vgene_x_cols = 'origin,timepoint'
 
+    // Notebooks parameters
+    timepoint_col = 'timepoint'
+    timepoint_order_col = 'timepoint_order'
+    alias_col = 'alias'
+    subject_col = 'subject_id'
+
     // OLGA parameters
     olga_chunk_length = 100000 // larger chunk size = less parallelization
 

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 provides 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 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_sample.qmd >}}
+

notebooks/template_details_part2.qmd

@@ -0,0 +1,108 @@
+---
+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 provides 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 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 >}}
+
+{{< include ./template_giana.qmd >}}
+
+{{< include ./template_gliph.qmd >}}