Add dropdowns to all chapter for key takeaways and `environment set…

…up` (#333) * env info for one chapter * changes to preprocessing and visualization section * undo random changes to execution_count * add env info box to the top of all chapters * Revert random changes to muon_to_seurat.ipynb * default text improvements + some design options * design options * add boxes to air_repertoire * boxes for conditions * boxes for cellular-structure + new (unique) anchor logic * updating new anchor logic to existing boxes * first two boxes for chromatin-accessibility * all boxes chromatin accessibility * box for deconvolution * boxes for mechanisms and multimodal integration * boxes for trajectories * boxes for preprocessing * boxes for spatial * boxes for surface protein * boxes for introduction --------- Co-authored-by: Luis <ge34lah@mytum.de>
theislab · Feb 20, 2025 · 41b1cb5 · 41b1cb5
1 parent 248eb74
commit 41b1cb5
Show file tree

Hide file tree

Showing 43 changed files with 1,792 additions and 377 deletions.
diff --git a/jupyter-book/_static/default_text_env_setup.md b/jupyter-book/_static/default_text_env_setup.md
@@ -0,0 +1,32 @@
+1. **Install conda**:
+
+   - Before creating the environment, ensure that [conda](https://docs.conda.io/projects/conda/en/latest/user-guide/install/index.html) is installed on your system.
+
+2. **Save the yml content**:
+
+   - Copy the content from the yml tab into a file named `environment.yml`.
+
+3. **Create the environment**:
+
+   - Open a terminal or command prompt.
+   - Run the following command:
+     ```bash
+     conda env create -f environment.yml
+     ```
+
+4. **Activate the environment**:
+
+   - After the environment is created, activate it using:
+     ```bash
+     conda activate <environment_name>
+     ```
+   - Replace `<environment_name>` with the name specified in the `environment.yml` file. In the yml file it will look like this:
+     ```yaml
+     name: <environment_name>
+     ```
+
+5. **Verify the installation**:
+   - Check that the environment was created successfully by running:
+     ```bash
+     conda env list
+     ```
diff --git a/jupyter-book/air_repertoire/clonotype.ipynb b/jupyter-book/air_repertoire/clonotype.ipynb
@@ -10,11 +10,53 @@
     "# Clonotype analysis"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "56750b9d",
+   "metadata": {},
+   "source": [
+    "```{dropdown} <i class=\"fas fa-brain\"></i>&nbsp;&nbsp;&nbsp;Key takeaways\n",
+    "\n",
+    ":::{card}\n",
+    ":link: air-repertoire-clonotype-key-takeaway-1\n",
+    ":link-type: ref\n",
+    "Clonal Expansion: Specific lymphocytes proliferate in response to immune stimuli, reducing clonal diversity but increasing the abundance of expanded clones.\n",
+    "This process is critical for understanding immune responses, as it reflects the transition from naive to effector and memory cells.\n",
+    ":::\n",
+    "\n",
+    ":::{card}\n",
+    ":link: air-repertoire-clonotype-key-takeaway-2\n",
+    ":link-type: ref\n",
+    "Gene Segment Usage & Spectratype: The rearrangement of V(D)J gene segments shows preferential usage, and spectratype analysis measures CDR3 length diversity.\n",
+    "Together, they help identify immunodominant clonotypes and characterize immune repertoire patterns.\n",
+    ":::\n",
+    "\n",
+    "```\n",
+    "\n",
+    "``````{dropdown} <i class=\"fa-solid fa-gear\"></i>&nbsp;&nbsp;&nbsp;Environment setup\n",
+    "`````{tab-set}\n",
+    "   \n",
+    "````{tab-item} Steps\n",
+    "```{include} ../_static/default_text_env_setup.md\n",
+    "```\n",
+    "````\n",
+    "\n",
+    "````{tab-item} yml\n",
+    "```{literalinclude} compositional.yml\n",
+    ":language: yaml\n",
+    "```\n",
+    "````\n",
+    "\n",
+    "`````\n",
+    "``````"
+   ]
+  },
   {
    "cell_type": "markdown",
    "id": "b4976e28",
    "metadata": {},
    "source": [
+    "(air-repertoire-clonotype-key-takeaway-1)=\n",
     "## Clonal expansion: diversity and abundance\n",
     "\n",
     "In general, lymphocytes are in a dormant state until receiving an external signal (epitope recognition of foreign agent) or stimulation from autocrine agents (signaling from the same organism as a response from the innate immune system). As a consequence, the specific cells proliferate dramatically to fulfill the defense response they are programmed to perform in a process known as clonal expansion {cite}`polonsky2016clonal`. This refers to the recognition of the proliferation of specific cells given the high number of the same IR through many, different cells (expanded clones). This expansion provides hints of differentiation from naive lymphocytes to mature effector and memory lymphocytes, helping in the interpretation and expected results regarding previous cell annotation {cite}`polonsky2016clonal`. On the other hand, the analysis of expanded clones should consider derivative processes such as clonal competitions (two or more clones in expansion competing for the same space), clonal dominance (one single clonal expanded cell outnumbering the rest of the clonal cells), and bystander activation (activation of T-cells by cytokines but not for T-cell receptor coupling) {cite}`naxerova2020clonal`{cite}`ashcroft2017clonal`{cite}`kim2019activation`.\n",
@@ -27,6 +69,7 @@
    "id": "3e3cd4d4",
    "metadata": {},
    "source": [
+    "(air-repertoire-clonotype-key-takeaway-2)=\n",
     "## Gene segment usage and spectratype\n",
     "\n",
     "The process shaping a T-cell or B-cell receptor by rearrangement of the V(D)J segments is thinking to generate random sequences and, in consequence, the distribution of V(D)J sequences should follow a uniform distribution. Nevertheless, it has been observed that V(D)J gene usage frequency is largely consistent across different individuals, which suggests a preference selection in terms of the V(D)J gene segments used {cite}`elhanati2014quantifying`. That allows the analysis of gene segment usage in terms of abundance of most used gene segments per cell type and frequency of most abundant segment per cell type per individual {cite}`chernyshev2021vdj`. Likewise, considering we know the amino aicd composition of the immune receptors for each cell, it is possible to identify the exact combinations of V(D)J segments of interest.\n",

diff --git a/jupyter-book/air_repertoire/ir_profiling.ipynb b/jupyter-book/air_repertoire/ir_profiling.ipynb
@@ -8,6 +8,51 @@
     "# Immune Receptor Profiling        "
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "f55a6006",
+   "metadata": {},
+   "source": [
+    "```{dropdown} <i class=\"fas fa-brain\"></i>&nbsp;&nbsp;&nbsp;Key takeaways\n",
+    "\n",
+    ":::{card}\n",
+    ":link: air-repertoire-ir-profiling-key-takeaway-1\n",
+    ":link-type: ref\n",
+    "VDJ-sequencing measures the sequence information of AIRs, which provides us insights into the function of B- and T-cells.\n",
+    ":::\n",
+    "\n",
+    ":::{card}\n",
+    ":link: air-repertoire-ir-profiling-key-takeaway-2\n",
+    ":link-type: ref\n",
+    "To detect doublets, cells with multiple AIRs should be identified or filtered.\n",
+    ":::\n",
+    "\n",
+    ":::{card}\n",
+    ":link: air-repertoire-ir-profiling-key-takeaway-3\n",
+    ":link-type: ref\n",
+    "Depending on the analysis, we additional filter cells with incomplete AIR information.\n",
+    ":::\n",
+    "\n",
+    "```\n",
+    "\n",
+    "``````{dropdown} <i class=\"fa-solid fa-gear\"></i>&nbsp;&nbsp;&nbsp;Environment setup\n",
+    "`````{tab-set}\n",
+    "   \n",
+    "````{tab-item} Steps\n",
+    "```{include} ../_static/default_text_env_setup.md\n",
+    "```\n",
+    "````\n",
+    "\n",
+    "````{tab-item} yml\n",
+    "```{literalinclude} compositional.yml\n",
+    ":language: yaml\n",
+    "```\n",
+    "````\n",
+    "\n",
+    "`````\n",
+    "``````"
+   ]
+  },
   {
    "cell_type": "markdown",
    "id": "81a16281",
@@ -74,6 +119,7 @@
    "id": "4b1a926e",
    "metadata": {},
    "source": [
+    "(air-repertoire-ir-profiling-key-takeaway-1)=\n",
     "## VDJ-sequencing\n",
     "\n",
     "### Cell isolation\n",
@@ -2633,19 +2679,13 @@
     "adata_bcr.obs.head()"
    ]
   },
-  {
-   "cell_type": "markdown",
-   "id": "5e729d42",
-   "metadata": {},
-   "source": [
-    "## Quality Control"
-   ]
-  },
   {
    "cell_type": "markdown",
    "id": "3ab5b0ed",
    "metadata": {},
    "source": [
+    "(air-repertoire-ir-profiling-key-takeaway-2)=\n",
+    "## Quality Control\n",
     "For analysis, we rely on high quality input data. It is therefore of great importance, to identify cells with incorrect or incomplete AIR information:\n",
     "- **Incomplete AIRs**: A cell is assigned only either a VJ and or a VDJ chain, because the other chain is missed during sequencing. While these are still valid cells, we cannot utilize them for downstream analysis, when full AIR sequence information is required.\n",
     "- **Multiple AIRs**: It is also possible that a cell gets assigned multiple AIRs. While it has been observed that T- / B-cells can express dual AIR {cite}`schuldt2019dual`, cells with more than two IRs are indicative as doublets, which should not be used for downstream analysis.\n",
@@ -2971,6 +3011,7 @@
    "id": "6831ca70",
    "metadata": {},
    "source": [
+    "(air-repertoire-ir-profiling-key-takeaway-3)=\n",
     "### Filtering"
    ]
   },
@@ -3206,18 +3247,6 @@
     "sc.write(adata=adata_bcr, filename=path_bcr_out)"
    ]
   },
-  {
-   "cell_type": "markdown",
-   "id": "d604b650",
-   "metadata": {},
-   "source": [
-    "## Key Takeaways\n",
-    "\n",
-    "- VDJ-sequencing measures the sequence information of AIRs, which provides us insights into the function of B- and T-cells.\n",
-    "- To detect doublets, cells with multiple AIRs should be identified or filtered.\n",
-    "- Depending on the analysis, we additional filter cells with incomplete AIR information."
-   ]
-  },
   {
    "cell_type": "markdown",
    "id": "e7b77012",

diff --git a/jupyter-book/air_repertoire/multimodal_integration.ipynb b/jupyter-book/air_repertoire/multimodal_integration.ipynb
@@ -8,6 +8,54 @@
     "# Integrating AIR and transcriptomics"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "827c6211",
+   "metadata": {},
+   "source": [
+    "```{dropdown} <i class=\"fas fa-brain\"></i>&nbsp;&nbsp;&nbsp;Key takeaways\n",
+    "\n",
+    ":::{card}\n",
+    ":link: air-repertoire-multimodal-integration-key-takeaway-1\n",
+    ":link-type: ref\n",
+    "For multimodal datasets of AIR and GEX, typically, one modality is used for grouping the cells to perform standard uni-modal analysis on the other modality (e.g. Sequence analysis on leiden clusters).\n",
+    ":::\n",
+    "\n",
+    ":::{card}\n",
+    ":link: air-repertoire-multimodal-integration-key-takeaway-2\n",
+    ":link-type: ref\n",
+    "Cell functionality (determined by AIR) and cell state (observed via GEX) are interlinked.\n",
+    "It has been shown, that cells with alike AIR sequences can share similar phenotypes.\n",
+    ":::\n",
+    "\n",
+    ":::{card}\n",
+    ":link: air-repertoire-multimodal-integration-key-takeaway-3\n",
+    ":link-type: ref\n",
+    "Due to the inherent structural difference between count matrices (GEX) and amino acid sequences (IR), it is difficult to directly fuse both modalities.\n",
+    "Therefore, several methods were developed recently, to utilize paired GEX-AIR data for to derive clusters, or an embedding.\n",
+    "However, these approaches are still novel and not part of a standard analysis pipeline.\n",
+    ":::\n",
+    "\n",
+    "```\n",
+    "\n",
+    "``````{dropdown} <i class=\"fa-solid fa-gear\"></i>&nbsp;&nbsp;&nbsp;Environment setup\n",
+    "`````{tab-set}\n",
+    "   \n",
+    "````{tab-item} Steps\n",
+    "```{include} ../_static/default_text_env_setup.md\n",
+    "```\n",
+    "````\n",
+    "\n",
+    "````{tab-item} yml\n",
+    "```{literalinclude} compositional.yml\n",
+    ":language: yaml\n",
+    "```\n",
+    "````\n",
+    "\n",
+    "`````\n",
+    "``````"
+   ]
+  },
   {
    "cell_type": "markdown",
    "id": "c6b657ac",
@@ -232,11 +280,18 @@
     "In this visualization, we see a clear separation between Plasmablasts and B cells."
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "ff5fbc79",
+   "metadata": {},
+   "source": []
+  },
   {
    "cell_type": "markdown",
    "id": "b52dc6b3",
    "metadata": {},
    "source": [
+    "(air-repertoire-multimodal-integration-key-takeaway-1)=\n",
     "## Uni-modal Analysis with multimodal conditions\n",
     "\n",
     "While studies often provide paired measurements for both modalities, these are often analyzed individually utilizing only limited shared information. Often one modality (AIRR or transcriptome) is used to provide conditions, on which the other modality is then analyzed. E.g., we can observe how cells from the same clonal lineage adapt to perturbation by DEG analysis of these cells in different points in time. \n",
@@ -1087,6 +1142,7 @@
    "id": "939c796e",
    "metadata": {},
    "source": [
+    "(air-repertoire-multimodal-integration-key-takeaway-2)=\n",
     "##### Output\n",
     "\n",
     "We now recieve three output files that we can further use for downstream tasks:\n",
@@ -1386,6 +1442,7 @@
    "id": "3888057f",
    "metadata": {},
    "source": [
+    "(air-repertoire-multimodal-integration-key-takeaway-3)=\n",
     "#### mvTCR\n",
     "\n",
     "mvTCR by An et al. is a multiview Variational autoencoder that compresses TCR sequence and gene expression into a lower-dimensional representation {cite}`an2021jointly`. Two deep learning architectures - Transformer and Multi-layer perceptron - extract information from both TCR and GEX, respectively, before they are fused to derive the joint space. Following, the trained models can be used to embed similar data. \n",
@@ -2367,18 +2424,6 @@
     "Here, we projected the ten largest clusters upon the transcriptome space. While some clusters follow the same phenotype, other clusters separate in the RNA space. The cluster annotation could be used for downstream analysis (see above) on BCR or transcriptomic site or to infer ancestral relationships between cells (see paper)."
    ]
   },
-  {
-   "cell_type": "markdown",
-   "id": "205b4ad6",
-   "metadata": {},
-   "source": [
-    "## Key Takeaways\n",
-    "\n",
-    "- For multimodal datasets of AIR and GEX, typically, one modality is used for grouping the cells to perform standard uni-modal analysis on the other modality (e.g. Sequence analysis on leiden clusters). \n",
-    "- Cell functionality (determined by AIR) and cell state (observed via GEX) are interlinked. It has been shown, that cells with alike AIR sequences can share similar phenotypes.\n",
-    "- Due to the inherent structural difference between count matrices (GEX) and amino acid sequences (IR), it is difficult to directly fuse both modalities. Therefore, several methods were developed recently, to utilize paired GEX-AIR data for to derive clusters, or an embedding. However, these approaches are still novel and not part of a standard analysis pipeline."
-   ]
-  },
   {
    "cell_type": "markdown",
    "id": "54051eba",