Liver digestion protocol v2.0 — merge with AG Surace SOP #001

protocols_src/_buffer_registry.csv

@@ -2,9 +2,7 @@ buffer_id,buffer_name,filename
 BUF-FACS-MACS,FACS/MACS Buffer,buf_facs_macs_buffer.qmd
 BUF-RBC-HYB,RBC Lysis Buffer (HybriMax),buf_rbc_lysis_hybrimax.qmd
 BUF-ACK-LYSIS,ACK RBC Lysis Buffer,buf_ack_lysis.qmd
-BUF-PERC-37,Isotonic Percoll (37%),buf_percoll_37pct.qmd
-BUF-LIV-DIG-COL-D,Liver Digestion Buffer (Collagenase D),buf_mus_liver_digestion_col_D.qmd
-BUF-LIV-DIG-COL-IV,Liver Digestion Buffer (Collagenase IV),buf_mus_liver_digestion_col_IV.qmd
+BUF-PERC-37,Percoll Solution (37% of isotonic stock = 33% final),buf_percoll_37pct.qmd
 BUF-R0-MED,R0 Medium (Serum-free RPMI),buf_R0_med.qmd
 BUF-R10-MED,R10 Medium (RPMI + 10% FCS),buf_R10_med.qmd
 BUF-TCELL-MED,T Cell Medium,buf_Tcell_med.qmd
@@ -14,3 +12,4 @@ BUF-VERO-PROP,Vero Cell Propagation Medium,buf_vero_propagation_medium.qmd
 BUF-BHK-PROP,BHK Cell Propagation Medium,buf_bhk_propagation_medium.qmd
 BUF-LCMV-PLA,LCMV Plaque Assay Medium,buf_lcmv_plaque_assay_medium.qmd
 BUF-L929-PROP,L929 Cell Propagation Medium,buf_l929_propagation_medium.qmd
+BUF-LIV-DIG,Liver Digestion Buffer,buf_mus_liver_digestion.qmd

protocols_src/_dependencies.csv

@@ -2,8 +2,6 @@ protocol_id,buffer_id
 MUS-SPL-DIS,BUF-FACS-MACS
 MUS-SPL-DIS,BUF-RBC-HYB
 MUS-LIV-DIG,BUF-FACS-MACS
-MUS-LIV-DIG,BUF-PERC-37
-MUS-LIV-DIG,BUF-LIV-DIG-COL-D
 MUS-LNG-DIG,BUF-FACS-MACS
 MUS-LNG-DIG,BUF-RBC-HYB
 MUS-BM-ISO,BUF-FACS-MACS
@@ -34,5 +32,7 @@ MUS-LNG-DIG,BUF-ACK-LYSIS
 MUS-BM-ISO,BUF-ACK-LYSIS
 MUS-BLD-PRC,BUF-ACK-LYSIS
 MUS-TMR-DIG,BUF-ACK-LYSIS
-MUS-LIV-DIG,BUF-LIV-DIG-COL-IV
 NLC-PLATE-STIM,BUF-TCELL-MED
+MUS-LIV-DIG,BUF-LIV-DIG
+MUS-LIV-DIG,BUF-PERC-37
+MUS-LIV-DIG,BUF-ACK-LYSIS

protocols_src/buffers/buf_mus_liver_digestion.qmd

@@ -0,0 +1,164 @@
+---
+title: "Mouse Liver Digestion Buffer"
+subtitle: "Abdullah Lab, IMMEI, University Hospital Bonn"
+protocol_id: "BUF-LIV-DIG"
+version: "v1.0"
+date: "2026-08-05"
+description: "Collagenase and DNase I digestion buffer for enzymatic dissociation of mouse liver tissue. Supports Collagenase D or Collagenase IV in a DMEM, PBS, or HBSS base."
+---
+
+**Protocol ID:** {{< meta protocol_id >}}
+**Version:** {{< meta version >}}
+**Author:** Dillon Corvino
+
+# Purpose
+
+This buffer is used for enzymatic digestion of mouse liver tissue to generate viable single-cell suspensions. It contains a collagenase and DNase I at working concentrations suitable for dissociating liver parenchyma while preserving lymphocyte viability.
+
+This single buffer replaces the former separate Collagenase D and Collagenase IV documents (`BUF-LIV-DIG-COL-D`, `BUF-LIV-DIG-COL-IV`, both retired at v2.0 of `MUS-LIV-DIG`).
+
+\tableofcontents
+
+# Linked protocols
+
+```{r}
+#| echo: false
+#| message: false
+
+library(tidyverse)
+
+this_buffer <- rmarkdown::metadata$protocol_id
+deps <- read_csv(here::here("protocols_src/_dependencies.csv"), show_col_types = FALSE)
+
+linked <- deps |>
+  filter(buffer_id == this_buffer) |>
+  distinct(protocol_id)
+
+if (nrow(linked) == 0) {
+  cat("None\n")
+} else {
+  linked |>
+    mutate(line = glue::glue("- `{protocol_id}`")) |>
+    pull(line) |>
+    cat(sep = "\n")
+}
+```
+
+---
+
+# Choice of collagenase and base medium
+
+Two collagenases are in routine use. They are **not interchangeable at the same concentration** — Collagenase D is used at **twice** the concentration of Collagenase IV.
+
+| Enzyme | Working concentration | Notes |
+|---|---|---|
+| **Collagenase D** | **1 mg/mL** | Roche 11088858001; supplied as lyophilised powder |
+| **Collagenase IV** | **0.5 mg/mL** | Half the concentration used for Collagenase D |
+
+**DNase I is 50 ug/mL for both.**
+
+The base medium may be **DMEM (incomplete)**, **PBS 1x**, or **HBSS 1x** — these are interchangeable for this application. Use whichever is on hand; HBSS and PBS avoid the phenol red background in DMEM if that matters downstream.
+
+::: callout-important
+Do **not** use an EDTA-containing buffer (e.g. MACS Buffer) as the base medium, and do not perfuse the liver with one. Collagenases are Ca2+/Zn2+-dependent metalloproteases and EDTA chelates these cofactors, inhibiting digestion.
+:::
+
+# Working buffer composition
+
+```{r}
+#| echo: false
+#| message: false
+
+library(tidyverse)
+
+# ---- inputs (edit here) ----
+collagenaseStockMgMl <- 100      # mg/mL
+dnaseStockMgMl       <- 10       # mg/mL
+dnaseFinalUgMl       <- 50       # ug/mL, both enzymes
+volumesMl            <- c(1, 5, 10, 25, 50)
+enzymes.df <- tibble::tibble(
+  enzyme      = c("Collagenase D", "Collagenase IV"),
+  finalMgMl   = c(1, 0.5)
+)
+# ----------------------------
+
+recipe.df <- tidyr::expand_grid(enzymes.df, volumeMl = volumesMl) |>
+  dplyr::mutate(
+    collagenaseUl = finalMgMl * volumeMl / collagenaseStockMgMl * 1000,
+    dnaseUl       = (dnaseFinalUgMl / 1000) * volumeMl / dnaseStockMgMl * 1000
+  )
+
+# verify the arithmetic reproduces the target concentrations exactly
+stopifnot(all(abs(recipe.df$collagenaseUl / 1000 * collagenaseStockMgMl /
+                    recipe.df$volumeMl - recipe.df$finalMgMl) < 1e-9))
+stopifnot(all(abs(recipe.df$dnaseUl / 1000 * dnaseStockMgMl /
+                    recipe.df$volumeMl * 1000 - dnaseFinalUgMl) < 1e-9))
+
+recipe.df |>
+  dplyr::mutate(
+    baseMedium    = paste0("to ", scales::comma(volumeMl), " mL"),
+    collagenaseUl = paste0(scales::comma(collagenaseUl), " uL"),
+    dnaseUl       = paste0(scales::comma(dnaseUl), " uL")
+  ) |>
+  dplyr::select(enzyme, volumeMl, baseMedium, collagenaseUl, dnaseUl) |>
+  knitr::kable(
+    align = "l",
+    col.names = c("Enzyme", "Final volume (mL)", "Base medium",
+                  "Collagenase (100 mg/mL stock)", "DNase I (10 mg/mL stock)")
+  )
+```
+
+**5 mL of working buffer is required per liver.**
+
+# Preparation
+
+## Stock solutions
+
+| Reagent | Stock concentration | Storage |
+|---|---|---|
+| Collagenase D or IV | 100 mg/mL in sterile PBS | Aliquot at -20 °C |
+| DNase I | 10 mg/mL | Aliquot at -20 °C; avoid repeated freeze-thaw |
+
+## Reconstitution of Collagenase powder
+
+Collagenase D is supplied as a **lyophilised powder** and must be reconstituted before use.
+
+1. Add **1 mL sterile PBS 1x** directly to a vial containing **100 mg** Collagenase powder.
+2. Swirl gently until fully dissolved; **do not vortex**.
+3. This yields a **100 mg/mL** stock.
+4. Aliquot into single-use volumes and store at **-20 °C**, labelled with enzyme, concentration, date, and initials.
+
+## Preparation of working buffer
+
+1. Thaw collagenase and DNase I aliquots on ice.
+2. Add the base medium (DMEM, PBS, or HBSS) to a sterile tube.
+3. Add collagenase and DNase I per the table above.
+4. Mix gently by inversion; **do not vortex**.
+5. Pre-warm to **37 °C** immediately before use.
+
+::: callout-note
+Collagenase-only buffer (without DNase) may be prepared in advance and frozen in aliquots. Add DNase I fresh on the day of use.
+:::
+
+# Storage and stability
+
+- Keep freshly prepared working buffer **on ice** until pre-warming for use.
+- Do **not** freeze buffer after DNase I has been added.
+- Discard unused working buffer at the end of the day.
+
+# Materials
+
+| Reagent | Supplier | Cat. # |
+|---|---|---|
+| Collagenase D | Roche, Basel, Switzerland | 11088858001 |
+| Collagenase IV | [TBD] | [TBD] |
+| DNase I | Sigma-Aldrich, Merck | DN25-100MG |
+| DMEM (incomplete) | [TBD] | [TBD] |
+| HBSS 1x | PAN-Biotech, Aidenbach, Germany | P04-34500 |
+| DPBS, no Ca / no Mg | Gibco, ThermoFisher | 14190-094 |
+
+# Version history
+
+| Version | Date | Author | Change summary |
+|---|---|---|---|
+| v1.0 | 2026-08-05 | Dillon Corvino | Created by merging `BUF-LIV-DIG-COL-D` and `BUF-LIV-DIG-COL-IV`. DNase I raised to 50 ug/mL for both enzymes (was 10 ug/mL for Col D, 25 ug/mL for Col IV). Base medium stated as DMEM, PBS, or HBSS. |

protocols_src/buffers/buf_percoll_37pct.qmd

@@ -1,19 +1,62 @@
 ---
-title: "37% Percoll Solution"
+title: "37% Percoll Solution (= 33% final Percoll)"
 subtitle: "Abdullah Lab, IMMEI, University Hospital Bonn"
 protocol_id: "BUF-PERC-37"
-version: "v1.2"
-date: "2025-12-29"
-description: "37% Percoll density solution for enrichment of leukocytes from digested liver tissue."
+version: "v2.0"
+date: "2026-08-05"
+description: "Percoll density solution for enrichment of leukocytes from digested liver tissue. 37% of isotonic Percoll stock, equivalent to 33% final Percoll."
 ---
 
-**Protocol ID:** {{< meta protocol_id >}}  
-**Version:** {{< meta version >}}  
-**Author:** Dillon Corvino  
+**Protocol ID:** {{< meta protocol_id >}}
+**Version:** {{< meta version >}}
+**Author:** Dillon Corvino
 
 # Purpose
 
-This buffer is used as a **37% Percoll solution** for density-based enrichment of leukocytes from digested liver tissue. During centrifugation, hepatocytes and debris remain in the supernatant, while leukocyte-enriched pellets form at the bottom of the tube.
+This buffer is used for density-based enrichment of leukocytes from digested liver tissue. During centrifugation, hepatocytes and debris remain in the supernatant, while leukocyte-enriched pellets form at the bottom of the tube.
+
+# "37%" and "33%" are the same solution
+
+This buffer is called **37%** because it is **37% of isotonic Percoll stock**. The identical solution is **33% Percoll** when quoted by final Percoll content. Both numbers are correct — they use different denominators.
+
+**SIP** — *Stock Isotonic Percoll*, also written *Standard Isotonic Percoll* — is the conventional term for neat Percoll pre-adjusted to physiological osmolality with 10x PBS at **9:1**. That mix is **90% Percoll by volume**, so:
+
+$$\text{final Percoll \%} = \text{SIP \%} \times 0.9$$
+
+```{r}
+#| echo: false
+#| message: false
+
+library(tidyverse)
+
+# ---- inputs (edit here) ----
+percollInSip <- 0.9    # SIP = 9 parts neat Percoll : 1 part 10x PBS
+sipPct       <- 37     # this buffer, expressed as % of isotonic stock
+# ----------------------------
+
+naming.df <- tibble::tibble(
+  convention  = c("% of isotonic stock (SIP)", "% final Percoll"),
+  thisBuffer  = c(sipPct, sipPct * percollInSip),
+  denominator = c("Volume of SIP as a fraction of the working solution",
+                  "Volume of neat Percoll as a fraction of the working solution")
+)
+
+stopifnot(abs(naming.df$thisBuffer[2] - 33.3) < 1e-9)
+
+naming.df |>
+  dplyr::mutate(thisBuffer = scales::percent(thisBuffer / 100, accuracy = 0.1)) |>
+  knitr::kable(align = "l",
+               col.names = c("Convention", "This buffer", "What the % is measured against"))
+```
+
+::: callout-important
+When comparing against an external protocol, **check which convention it uses before changing any number**.
+
+-   This buffer and `MUS-LIV-DIG` quote **% of isotonic stock**.
+-   The AG Surace SOP #001 quotes **% final Percoll** — its "33% Percoll" (9 mL Percoll + 1 mL 10x DPBS + 17 mL 1x DPBS) is **the same density as this buffer**.
+
+Relabelling "37%" as "33%" without also changing the recipe would drop the gradient to **29.7% final Percoll** and increase hepatocyte carryover.
+:::
 
 ### Density vs osmolality (important conceptual note)
 
@@ -105,27 +148,74 @@ Therefore:
 
 ---
 
-# Composition (per 10 mL 37% Percoll)
+# Composition
 
 | Component | Stock | Volume for 10 mL | Final composition | Notes |
 |------------------|-------|------------------|-------------------|-------|
-| Percoll (isotonic) | 100% | **3.70 mL** | 37% (v/v) | Pre-adjusted stock |
+| Percoll (isotonic) | 100% | **3.70 mL** | 37% of SIP = **33.3% final Percoll** | Pre-adjusted stock |
 | PBS 1× | — | **6.30 mL** | — | Diluent |
 
----
-
-# Preparation of 37% Percoll working solution
+# Preparation of working solution
 
 1. Equilibrate **isotonic Percoll stock** to **room temperature**.
-2. In a sterile 15 mL or 50 mL tube, add:
-   - **3.70 mL isotonic Percoll**
-   - **6.30 mL sterile PBS 1×**
+2. Combine isotonic Percoll and sterile 1x PBS in the ratio **3.70 : 6.30**, scaled per the table below.
 3. Mix gently by inversion until homogeneous.
-4. Prepare sufficient volume for the experiment (typically **10 mL per liver**).
-5. Aliquot immediately into labelled **15 mL conical tubes**.
+4. Aliquot immediately into labelled tubes — for `MUS-LIV-DIG`, **25 mL per 50 mL conical tube**, one per liver.
+
+Volumes below are the exact requirement per number of livers — see the tip beneath the table on adding margin.
+
+```{r}
+#| echo: false
+#| message: false
+
+library(tidyverse)
+
+# ---- inputs (edit here) ----
+percollInSip   <- 0.9    # SIP is 90% neat Percoll by volume
+sipFraction    <- 0.37   # 37% of isotonic stock
+volPerLiver    <- 25     # mL loaded per sample (MUS-LIV-DIG STEP 6)
+nLivers        <- c(1, 2, 3, 4, 5, 6, 8, 9, 10, 12)
+# ----------------------------
+
+percoll.df <- tibble::tibble(nLivers = nLivers) |>
+  dplyr::mutate(
+    totalMl = nLivers * volPerLiver,
+    sipMl   = totalMl * sipFraction,
+    pbsMl   = totalMl - sipMl
+  )
+
+# components sum to total, and both percentages hold exactly at every scale
+stopifnot(all(abs(percoll.df$sipMl + percoll.df$pbsMl - percoll.df$totalMl) < 1e-9))
+stopifnot(all(abs(percoll.df$sipMl / percoll.df$totalMl - sipFraction) < 1e-9))
+stopifnot(all(abs(percoll.df$sipMl * percollInSip / percoll.df$totalMl -
+                    sipFraction * percollInSip) < 1e-9))
+
+percoll.df |>
+  dplyr::mutate(
+    finalPct = scales::percent(sipMl * percollInSip / totalMl, accuracy = 0.1),
+    dplyr::across(c(totalMl, sipMl, pbsMl), ~ round(.x, 2))
+  ) |>
+  knitr::kable(
+    align = "l",
+    col.names = c("Livers", "Total (mL)", "Isotonic Percoll (mL)",
+                  "PBS 1x (mL)", "Final Percoll")
+  )
+```
+
+Per liver this is **9.25 mL isotonic Percoll + 15.75 mL PBS** = 25 mL.
+
+::: callout-tip
+The table gives the **exact** volume for the number of livers being processed, with no margin built in. When preparing for more than one liver, **add some extra** so the last tube is not short — tube dead volume, pipetting loss, and the meniscus left in the stripette all add up across samples.
+
+How much extra is your call: one additional liver's worth (25 mL) is usually sufficient, and is simplest to work out. For example, for 9 livers read off the 10-liver row.
+:::
+
+::: callout-note
+That 10 : 17 ratio is arithmetically **37.04% SIP / 33.33% final** rather than exactly 37.00% / 33.30% — a difference of 0.03 percentage points, which is not meaningful at the bench. It is also **exactly** the AG Surace SOP recipe (9 mL Percoll + 1 mL 10x DPBS + 17 mL 1x DPBS), confirming the two protocols use the same gradient.
+:::
 
-:::callout-note
-Prepare 37% Percoll fresh on the day of use for optimal separation performance and cell viability.
+::: callout-note
+Prepare the working solution fresh on the day of use for optimal separation performance and cell viability.
 :::
 
 ---
@@ -220,3 +310,4 @@ For every **9 mL of Percoll**, add **1 mL of 10× PBS** to make the solution iso
 | v1.0 | 2025-11-20 | Dillon Corvino | Initial buffer definition (33% Percoll) |
 | v1.1 | 2025-12-29 | Dillon Corvino | Updated to 37% Percoll; clarified isotonic prep |
 | v1.2 | 2025-12-29 | Dillon Corvino | Added stock isotonic prep, math explanation, sterility notes |
+| v2.0 | 2026-08-05 | Dillon Corvino | Density unchanged. Added explicit dual-convention section: 37% of isotonic stock = 33% final Percoll, with the AG Surace SOP #001 equivalence. Volumes for `MUS-LIV-DIG` raised to 25 mL per 50 mL tube (was 10 mL per 15 mL tube); scaling table added. |