From 140e48d1905b0dac88f9f99112b2530c8e740ef8 Mon Sep 17 00:00:00 2001
From: ch99l <chinhaolee10@gmail.com>
Date: Thu, 30 Jul 2026 20:13:49 +0800
Subject: [PATCH 1/2] visium-hd-clean-docker

---
 .github/workflows/build_container.yml         | 158 +++++++++++-------
 bin/create_seurat_object.R                    |  14 ++
 conf/base.config                              |   2 +-
 conf/containers.config                        |   3 +-
 containers/{r => bambu}/Dockerfile            |  14 +-
 containers/seurat/Dockerfile                  |  11 ++
 main.nf                                       |   9 +-
 .../shared/cluster_level_quantification.nf    |   2 +-
 modules/bambu/shared/construct_read_class.nf  |   2 +-
 modules/bambu/shared/prepare_annotation.nf    |   2 +-
 .../standard/single_cell_quantification.nf    |   2 +-
 .../bambu/standard/transcript_discovery.nf    |  10 +-
 modules/bambu/visium_hd/aggregate_bins.nf     |   8 +-
 .../visium_hd/spot_level_quantification.nf    |   2 +-
 .../bambu/visium_hd/transcript_discovery.nf   |   2 +-
 .../standard/multi_sample_clustering.nf       |  29 ++--
 .../standard/single_sample_clustering.nf      |  22 +--
 modules/seurat/visium_hd/clustering.nf        |  15 +-
 subworkflows/clustering_standard.nf           |  12 +-
 19 files changed, 192 insertions(+), 127 deletions(-)
 create mode 100755 bin/create_seurat_object.R
 rename containers/{r => bambu}/Dockerfile (71%)
 create mode 100644 containers/seurat/Dockerfile

diff --git a/.github/workflows/build_container.yml b/.github/workflows/build_container.yml
index 1b97a6a..6907417 100644
--- a/.github/workflows/build_container.yml
+++ b/.github/workflows/build_container.yml
@@ -1,13 +1,16 @@
-name: Build R container
+name: Build R containers
 
-# The image tag is read from conf/containers.config, so that single line is both what the
-# pipeline pulls and what this workflow publishes -- the two cannot drift.
-# Runs on pushes to a feature branch, whenever the container changes.
+# The image tag of the container is read from conf/containers.config, so that the tag is
+# what the pipeline pulls and what this workflow publishes. Each container is built independently,
+# so updating one tag in conf/containers.config rebuilds only that image:
+#   feature branch - rebuilds its tag on every push, unless main or devel is pinned to that tag
+#   main or devel  - builds only a tag that has never been published, so most merges are a no-op
+#   manual run     - 'force' rebuilds and overwrites the tag on any branch
 
 on:
   push:
     paths:
-      - 'containers/r/**'
+      - 'containers/**'
       - 'conf/containers.config'
       - '.github/workflows/build_container.yml'
   workflow_dispatch:
@@ -22,81 +25,116 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
-  build:
-    name: Build and publish
+  discover:
+    name: Select containers to build
     runs-on: ubuntu-latest
     permissions:
       contents: read
-      packages: write
+      packages: read
+    outputs:
+      containers: ${{ steps.select.outputs.containers }}
 
     steps:
       - uses: actions/checkout@v4
 
-      - name: Resolve image from conf/containers.config
-        id: image
-        run: |
-          IMAGE=$(sed -n "s|.*withLabel: *'r'.*container *= *\"\([^\"]*\)\".*|\1|p" conf/containers.config)
-          if [ -z "$IMAGE" ]; then
-            echo "::error::could not parse the 'r' container from conf/containers.config"
-            exit 1
-          fi
-          case "$IMAGE" in
-            ghcr.io/goekelab/*) ;;
-            *) echo "::error::refusing to push outside ghcr.io/goekelab: $IMAGE"; exit 1 ;;
-          esac
-          echo "image=$IMAGE" >> "$GITHUB_OUTPUT"
-          echo "Resolved container: $IMAGE"
-
-      - name: Refuse to overwrite a tag main or devel is pinned to
-        if: github.ref_name != 'main' && github.ref_name != 'devel'
+      - uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Select containers to build
+        id: select
         run: |
-          IMAGE="${{ steps.image.outputs.image }}"
-          for BASE in main devel; do
-            git fetch --no-tags --depth=1 origin "$BASE" 2>/dev/null || continue
-            PINNED=$(git show "FETCH_HEAD:conf/containers.config" 2>/dev/null \
-              | sed -n "s|.*withLabel: *'r'.*container *= *\"\([^\"]*\)\".*|\1|p")
-            if [ "$IMAGE" = "$PINNED" ]; then
-              echo "::error::$BASE is pinned to $IMAGE -- bump the tag in conf/containers.config before rebuilding it"
+          RELEASED=false
+          case "${{ github.ref_name }}" in main|devel) RELEASED=true ;; esac
+
+          # Each base branch is fetched into its own ref so both stay readable in the loop
+          BASES=""
+          for BASE in devel main; do
+            if git fetch --no-tags --depth=1 origin "$BASE:refs/base/$BASE" 2>/dev/null; then
+              BASES="$BASES refs/base/$BASE"
+            fi
+          done
+
+          # devel is at or ahead of main, so it is the baseline for "did this container change"
+          DIFF_BASE=refs/base/devel
+
+          # Every containers/<label>/Dockerfile is an image whose <label> is its process label
+          : > selected.txt
+          for DOCKERFILE in containers/*/Dockerfile; do
+            LABEL=$(basename "$(dirname "$DOCKERFILE")")
+            IMAGE=$(sed -n "s|.*withLabel: *'$LABEL'.*container *= *\"\([^\"]*\)\".*|\1|p" conf/containers.config)
+
+            if [ -z "$IMAGE" ]; then
+              echo "::error::could not parse the '$LABEL' container from conf/containers.config"
               exit 1
             fi
+            case "$IMAGE" in
+              ghcr.io/goekelab/*) ;;
+              *) echo "::error::refusing to push outside ghcr.io/goekelab: $IMAGE"; exit 1 ;;
+            esac
+
+            CHANGED=false
+            if ! git diff --quiet "$DIFF_BASE" HEAD -- "containers/$LABEL"; then
+              CHANGED=true
+            fi
+
+            # A tag main or devel is pinned to is immutable, so an edit needs a tag bump first
+            if [ "$RELEASED" = false ] && [ "$CHANGED" = true ]; then
+              for REF in $BASES; do
+                PINNED=$(git show "$REF:conf/containers.config" 2>/dev/null \
+                  | sed -n "s|.*withLabel: *'$LABEL'.*container *= *\"\([^\"]*\)\".*|\1|p")
+                if [ "$IMAGE" = "$PINNED" ]; then
+                  echo "::error::${REF#refs/base/} is pinned to $IMAGE -- bump the tag in conf/containers.config before rebuilding it"
+                  exit 1
+                fi
+              done
+            fi
+
+            # An unpublished tag is always built, since the pipeline cannot pull what is not there
+            if [ "${{ inputs.force }}" != "true" ] && docker manifest inspect "$IMAGE" >/dev/null 2>&1; then
+              if [ "$RELEASED" = true ] || [ "$CHANGED" = false ]; then
+                echo "::notice::$IMAGE is already published and unchanged -- skipping $LABEL"
+                continue
+              fi
+            fi
+
+            echo "$LABEL $IMAGE" >> selected.txt
           done
 
+          CONTAINERS=$(jq -R -s -c 'split("\n") | map(select(length > 0) | split(" ")) | map({label: .[0], image: .[1]})' < selected.txt)
+          echo "containers=$CONTAINERS" >> "$GITHUB_OUTPUT"
+          echo "Building: $CONTAINERS"
+
+  build:
+    name: Build and publish (${{ matrix.container.label }})
+    needs: discover
+    if: needs.discover.outputs.containers != '[]'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+    strategy:
+      fail-fast: false
+      matrix:
+        container: ${{ fromJson(needs.discover.outputs.containers) }}
+
+    steps:
+      - uses: actions/checkout@v4
+
       - uses: docker/login-action@v3
         with:
           registry: ghcr.io
           username: ${{ github.actor }}
           password: ${{ secrets.GITHUB_TOKEN }}
 
-      - name: Decide whether to build
-        id: decide
-        run: |
-          IMAGE="${{ steps.image.outputs.image }}"
-          if docker manifest inspect "$IMAGE" >/dev/null 2>&1; then EXISTS=true; else EXISTS=false; fi
-
-          if [ "${{ inputs.force }}" = "true" ]; then
-            BUILD=true
-          elif [ "${{ github.ref_name }}" = "main" ] || [ "${{ github.ref_name }}" = "devel" ]; then
-            # Released tags are immutable: the merge that brought the bump in has already
-            # published it from the feature branch, so there is nothing left to do
-            [ "$EXISTS" = "false" ] && BUILD=true || BUILD=false
-          else
-            # Feature branch: the tag is unreleased (guarded above), so rebuild freely
-            BUILD=true
-          fi
-
-          echo "build=$BUILD" >> "$GITHUB_OUTPUT"
-          if [ "$BUILD" = "false" ]; then
-            echo "::notice::$IMAGE is already published -- skipping build"
-          fi
-
       - uses: docker/setup-buildx-action@v3
-        if: steps.decide.outputs.build == 'true'
 
       - uses: docker/build-push-action@v6
-        if: steps.decide.outputs.build == 'true'
         with:
-          context: containers/r
+          context: containers/${{ matrix.container.label }}
           push: true
-          tags: ${{ steps.image.outputs.image }}
-          cache-from: type=gha
-          cache-to: type=gha,mode=max
+          tags: ${{ matrix.container.image }}
+          cache-from: type=gha,scope=${{ matrix.container.label }}
+          cache-to: type=gha,mode=max,scope=${{ matrix.container.label }}
diff --git a/bin/create_seurat_object.R b/bin/create_seurat_object.R
new file mode 100755
index 0000000..7fe3361
--- /dev/null
+++ b/bin/create_seurat_object.R
@@ -0,0 +1,14 @@
+# createSeuratObject() - build a Seurat object from a bambu count directory, so the
+# clustering never has to read a SummarizedExperiment.
+#   countsDir - path to a count directory written by saveCounts()
+#   metadata  - data.frame of cell metadata, one row per barcode with matching row names
+#   assay, minCells, project - passed through to CreateSeuratObject()
+# Assumes Seurat is loaded by the caller
+
+createSeuratObject <- function(countsDir, assay = "RNA", metadata = NULL, minCells = 0, project = "SeuratProject") {
+    counts <- ReadMtx(mtx      = file.path(countsDir, "counts.mtx.gz"),
+                      cells    = file.path(countsDir, "barcodes.tsv.gz"),
+                      features = file.path(countsDir, "features.tsv.gz"))
+
+    CreateSeuratObject(counts, assay = assay, meta.data = metadata, min.cells = minCells, project = project)
+}
diff --git a/conf/base.config b/conf/base.config
index ae2574c..76247ad 100644
--- a/conf/base.config
+++ b/conf/base.config
@@ -19,5 +19,5 @@ process {
     withLabel: 'long'           { time = { 12.h * task.attempt } }
 
     // R processes exit with code 1 on BiocParallel/OOM failures (not signal-based codes)
-    withLabel: 'r'              { errorStrategy = { task.exitStatus in [1, 130, 137, 139, 143] ? 'retry' : 'finish' } }
+    withLabel: 'bambu|seurat'   { errorStrategy = { task.exitStatus in [1, 130, 137, 139, 143] ? 'retry' : 'finish' } }
 }
\ No newline at end of file
diff --git a/conf/containers.config b/conf/containers.config
index 83db49c..f5fd818 100644
--- a/conf/containers.config
+++ b/conf/containers.config
@@ -1,5 +1,6 @@
 process {
-    withLabel: 'r'                  { container = "ghcr.io/goekelab/bambu-pipe-r:1.1.0" }
+    withLabel: 'bambu'              { container = "ghcr.io/goekelab/bambu-pipe-bambu:1.0.0" }
+    withLabel: 'seurat'             { container = "ghcr.io/goekelab/bambu-pipe-seurat:1.0.0" }
     withLabel: 'spaceranger'        { container = "quay.io/nf-core/spaceranger:9c5e7dc93c32448e" }
     withLabel: 'minimap2_samtools'  { container = "community.wave.seqera.io/library/minimap2_samtools:b09096fc890429ce" }
     withLabel: 'preprocess'         { container = "community.wave.seqera.io/library/chopper_cutadapt_flexiplex_pigz:077c3bc67452482c" }
diff --git a/containers/r/Dockerfile b/containers/bambu/Dockerfile
similarity index 71%
rename from containers/r/Dockerfile
rename to containers/bambu/Dockerfile
index ddbd039..c98b8b1 100644
--- a/containers/r/Dockerfile
+++ b/containers/bambu/Dockerfile
@@ -7,28 +7,20 @@ RUN apt-get update && apt-get install -y libcurl4-openssl-dev procps git \
 ARG MAMBA_DOCKERFILE_ACTIVATE=1
 
 # Install bioconductor version of bambu for its dependencies
-# TODO: data.table 1.17.8 installation is a temp fix for clustered_EM 
+# TODO: data.table 1.17.8 installation is a temp fix for clustered_EM
 RUN micromamba install -y -n base -c conda-forge -c bioconda \
     r-base=4.5.3 \
     r-devtools=2.5.2 \
-    r-remotes=2.5.0 \
     r-biocmanager=1.30.27 \
     bioconductor-bambu=3.12.1 \
     bioconductor-dropletutils=1.30.0 \
-    r-seurat=5.4.0 \
-    r-harmony=2.0.2 \
     r-data.table=1.17.8 \
-    r-magick \
-    r-leidenalg \
     gxx=15.2.0 \
     && micromamba clean --all --yes
 
-# Install Seurat Wrappers 
-RUN R -e 'remotes::install_github("satijalab/seurat-wrappers", upgrade = "never")'
-
-# Clone bambu single cell feature branch 
+# Clone bambu single cell feature branch
 RUN git clone --branch devel_pre_v4 \
     https://github.com/GoekeLab/bambu.git /opt/bambu \
     && R -e 'devtools::install("/opt/bambu")'
 
-ENV PATH="$MAMBA_ROOT_PREFIX/bin:$PATH"
\ No newline at end of file
+ENV PATH="$MAMBA_ROOT_PREFIX/bin:$PATH"
diff --git a/containers/seurat/Dockerfile b/containers/seurat/Dockerfile
new file mode 100644
index 0000000..6ad4048
--- /dev/null
+++ b/containers/seurat/Dockerfile
@@ -0,0 +1,11 @@
+# Seurat 5.4.0 and harmony are already installed in the base image
+FROM satijalab/seurat:5.4.0
+
+# procps supplies the ps that Nextflow uses to collect task metrics
+RUN apt-get update && apt-get install -y --no-install-recommends procps \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install Seurat Wrappers, plus Banksy for spatially aware clustering (Banksy is only a
+# suggested dependency of Seurat Wrappers, so it is not installed alongside it)
+RUN R -e 'remotes::install_github("satijalab/seurat-wrappers", upgrade = "never")' \
+    && R -e 'library(SeuratWrappers); library(Banksy); library(harmony)'
diff --git a/main.nf b/main.nf
index 48ce15d..9ae50d6 100644
--- a/main.nf
+++ b/main.nf
@@ -92,7 +92,7 @@ workflow STANDARD {
 
         // cluster the cells first, then pool each cluster's cells for the EM
         if (params.quantification_mode == 'EM_clusters') {
-            CLUSTERING(BAMBU_TRANSCRIPT_DISCOVERY.out.se_gene_counts, ch_n_samples)
+            CLUSTERING(BAMBU_TRANSCRIPT_DISCOVERY.out.gene_counts, BAMBU_TRANSCRIPT_DISCOVERY.out.col_data, ch_n_samples)
             BAMBU_CLUSTER_LEVEL_QUANTIFICATION(CLUSTERING.out.clusters, BAMBU_TRANSCRIPT_DISCOVERY.out.quant_data, BAMBU_TRANSCRIPT_DISCOVERY.out.extended_annotations, ch_genome)
         } else if (params.quantification_mode == 'EM') {
             BAMBU_SINGLE_CELL_QUANTIFICATION(BAMBU_TRANSCRIPT_DISCOVERY.out.quant_data, BAMBU_TRANSCRIPT_DISCOVERY.out.extended_annotations, ch_genome)
@@ -133,9 +133,10 @@ workflow VISIUM_HD {
     if (params.quantification_mode == 'EM_clusters') {
         def requested_bin = String.format('%03dum', params.clustering_bin) // convert clustering_bin specified as an integer into Spaceranger format
         // perform clustering at the requested resolution only
-        ch_clustering = AGGREGATE_BINS_VISIUM_HD.out.se_gene_counts
-            .filter { resolution, _se_gene_counts -> resolution == requested_bin }
-            .join(SPOT_BIN_MAPPINGS.out.csv) // [resolution, se_gene_counts, spot_mappings]
+        ch_clustering = AGGREGATE_BINS_VISIUM_HD.out.gene_counts
+            .join(AGGREGATE_BINS_VISIUM_HD.out.col_data)
+            .filter { resolution, _gene_counts, _col_data -> resolution == requested_bin }
+            .join(SPOT_BIN_MAPPINGS.out.csv) // [resolution, gene_counts, col_data, spot_mappings]
         SEURAT_VISIUM_HD(ch_clustering)
         BAMBU_CLUSTER_LEVEL_QUANTIFICATION(SEURAT_VISIUM_HD.out.clusters, ch_quant_data, ch_extended_anno, ch_genome)
 
diff --git a/modules/bambu/shared/cluster_level_quantification.nf b/modules/bambu/shared/cluster_level_quantification.nf
index a77c65f..5284a5d 100644
--- a/modules/bambu/shared/cluster_level_quantification.nf
+++ b/modules/bambu/shared/cluster_level_quantification.nf
@@ -1,7 +1,7 @@
 process BAMBU_CLUSTER_LEVEL_QUANTIFICATION {
     publishDir "$params.output_dir", mode: 'copy', pattern: 'transcript_counts_clusters'
     publishDir "$params.output_dir", mode: 'copy', pattern: 'gene_counts_clusters'
-    label "r"
+    label "bambu"
     label "low_cpu"
     label "high_mem"
     label "long"
diff --git a/modules/bambu/shared/construct_read_class.nf b/modules/bambu/shared/construct_read_class.nf
index 8a7270c..28a3aac 100644
--- a/modules/bambu/shared/construct_read_class.nf
+++ b/modules/bambu/shared/construct_read_class.nf
@@ -1,6 +1,6 @@
 process BAMBU_CONSTRUCT_READ_CLASS{
     publishDir "$params.output_dir/intermediate_R/read_class", mode: 'copy', pattern: '*_read_class.rds', enabled: params.save_intermediates
-    label "r"
+    label "bambu"
     label "low_cpu"
     label "high_mem"
     label "medium"
diff --git a/modules/bambu/shared/prepare_annotation.nf b/modules/bambu/shared/prepare_annotation.nf
index 942fe88..ee6fbc3 100644
--- a/modules/bambu/shared/prepare_annotation.nf
+++ b/modules/bambu/shared/prepare_annotation.nf
@@ -1,5 +1,5 @@
 process BAMBU_PREPARE_ANNOTATION{
-    label "r"
+    label "bambu"
     label "low_cpu"
     label "low_mem"
     label "short"
diff --git a/modules/bambu/standard/single_cell_quantification.nf b/modules/bambu/standard/single_cell_quantification.nf
index 7a713f0..d5d212f 100644
--- a/modules/bambu/standard/single_cell_quantification.nf
+++ b/modules/bambu/standard/single_cell_quantification.nf
@@ -1,6 +1,6 @@
 process BAMBU_SINGLE_CELL_QUANTIFICATION {
     publishDir "$params.output_dir", mode: 'copy', pattern: 'transcript_counts_singlecell'
-    label "r"
+    label "bambu"
     label "low_cpu"
     label "high_mem"
     label "long"
diff --git a/modules/bambu/standard/transcript_discovery.nf b/modules/bambu/standard/transcript_discovery.nf
index e89d0d4..5365c7b 100644
--- a/modules/bambu/standard/transcript_discovery.nf
+++ b/modules/bambu/standard/transcript_discovery.nf
@@ -3,7 +3,7 @@ process BAMBU_TRANSCRIPT_DISCOVERY{
     publishDir "$params.output_dir", mode: 'copy', pattern: 'unique_counts'
     publishDir "$params.output_dir", mode: 'copy', pattern: 'gene_counts'
     publishDir "$params.output_dir/intermediate_R", mode: 'copy', pattern: '*.rds', enabled: params.save_intermediates
-    label "r"
+    label "bambu"
     label "medium_cpu"
     label "high_mem"
     label "medium"
@@ -17,11 +17,11 @@ process BAMBU_TRANSCRIPT_DISCOVERY{
 	output:
     path ('quant_data.rds'), emit: quant_data
     path ('unique_counts/se_unique_counts.rds')
-    path ('gene_counts/se_gene_counts.rds'), emit: se_gene_counts
 	path ('extended_annotations.rds'), emit: extended_annotations
     path ('extended_annotations.gtf')
     path ('unique_counts')
-    path ('gene_counts')
+    path ('gene_counts'), emit: gene_counts
+    path ('col_data.rds'), emit: col_data
     path "versions.yml", topic: 'versions'
 
 	script:
@@ -55,6 +55,10 @@ process BAMBU_TRANSCRIPT_DISCOVERY{
     seDiscoveryGene <- transcriptToGeneExpression(seDiscovery)
     saveCounts(seDiscoveryGene, "gene_counts")
 
+    # colData is saved to create the Seurat object's metadata
+    geneColData <- as.data.frame(colData(seDiscoveryGene))
+    saveRDS(geneColData, "col_data.rds")
+
     writeLines(c('"${task.process}":', paste0('    R: ', R.Version()\$version.string), paste0('    bambu: ', as.character(packageVersion("bambu")))), "versions.yml")
 	"""
 }
\ No newline at end of file
diff --git a/modules/bambu/visium_hd/aggregate_bins.nf b/modules/bambu/visium_hd/aggregate_bins.nf
index 6042d62..e65c1ff 100644
--- a/modules/bambu/visium_hd/aggregate_bins.nf
+++ b/modules/bambu/visium_hd/aggregate_bins.nf
@@ -1,7 +1,7 @@
 process AGGREGATE_BINS_VISIUM_HD {
     publishDir "$params.output_dir/unique_counts", mode: 'copy', pattern: 'unique_counts_*'
     publishDir "$params.output_dir/gene_counts", mode: 'copy', pattern: 'gene_counts_*'
-    label "r"
+    label "bambu"
     label "low_cpu"
     label "medium_mem"
     label "short"
@@ -13,7 +13,7 @@ process AGGREGATE_BINS_VISIUM_HD {
     output:
     tuple val(resolution), path("unique_counts_${resolution}"), emit: unique_counts
     tuple val(resolution), path("gene_counts_${resolution}"),   emit: gene_counts
-    tuple val(resolution), path("gene_counts_${resolution}/se_gene_counts_${resolution}.rds"), emit: se_gene_counts
+    tuple val(resolution), path("col_data_${resolution}.rds"),  emit: col_data
     path "versions.yml", topic: 'versions'
 
     script:
@@ -37,6 +37,10 @@ process AGGREGATE_BINS_VISIUM_HD {
     saveCounts(uniqueAgg, "unique_counts_$resolution", "Transcript Expression")
     saveCounts(geneAgg,   "gene_counts_$resolution")
 
+    # colData is saved to create the Seurat object's metadata
+    binColData <- as.data.frame(colData(geneAgg))
+    saveRDS(binColData, "col_data_${resolution}.rds")
+
     writeLines(c('"${task.process}":', paste0('    R: ', R.Version()\$version.string), paste0('    bambu: ', as.character(packageVersion("bambu")))), "versions.yml")
     """
 }
diff --git a/modules/bambu/visium_hd/spot_level_quantification.nf b/modules/bambu/visium_hd/spot_level_quantification.nf
index 6050c1b..af19419 100644
--- a/modules/bambu/visium_hd/spot_level_quantification.nf
+++ b/modules/bambu/visium_hd/spot_level_quantification.nf
@@ -1,6 +1,6 @@
 process BAMBU_SPOT_LEVEL_QUANTIFICATION {
     publishDir "$params.output_dir/transcript_counts", mode: 'copy', pattern: 'transcript_counts_*'
-    label "r"
+    label "bambu"
     label "low_cpu"
     label "high_mem"
     label "long"
diff --git a/modules/bambu/visium_hd/transcript_discovery.nf b/modules/bambu/visium_hd/transcript_discovery.nf
index b3b596e..b5a7058 100644
--- a/modules/bambu/visium_hd/transcript_discovery.nf
+++ b/modules/bambu/visium_hd/transcript_discovery.nf
@@ -3,7 +3,7 @@ process BAMBU_TRANSCRIPT_DISCOVERY_VISIUM_HD {
     publishDir "$params.output_dir/unique_counts", mode: 'copy', pattern: 'unique_counts_002um'
     publishDir "$params.output_dir/gene_counts", mode: 'copy', pattern: 'gene_counts_002um'
     publishDir "$params.output_dir/intermediate_R", mode: 'copy', pattern: '*.rds', enabled: params.save_intermediates
-    label "r"
+    label "bambu"
     label "medium_cpu"
     label "high_mem"
     label "medium"
diff --git a/modules/seurat/standard/multi_sample_clustering.nf b/modules/seurat/standard/multi_sample_clustering.nf
index b377b95..915a16f 100644
--- a/modules/seurat/standard/multi_sample_clustering.nf
+++ b/modules/seurat/standard/multi_sample_clustering.nf
@@ -1,13 +1,13 @@
 process SEURAT_MULTI_SAMPLE {
     publishDir "$params.output_dir", mode: 'copy', pattern: 'seurat_obj.rds'
     publishDir "$params.output_dir/intermediate_R", mode: 'copy', pattern: 'clusters.rds', enabled: params.save_intermediates
-    label "r"
+    label "seurat"
     label "medium_cpu"
     label "high_mem"
     label "medium"
 
     input:
-    path(se)
+    tuple path(gene_counts), path(col_data)
 
     output:
     path ('clusters.rds'), emit: clusters
@@ -17,23 +17,18 @@ process SEURAT_MULTI_SAMPLE {
     script:
     """
     #!/usr/bin/env Rscript
-    library(SummarizedExperiment)
     library(Seurat)
+    source(Sys.which("create_seurat_object.R"))
 
-    # Extract gene count matrix and colData metadata
-    se     <- readRDS("$se")
-    counts <- assays(se)\$counts
-    dim    <- $params.seurat_dim_multi
+    metadata <- readRDS("$col_data")
+    dim      <- $params.seurat_dim_multi
 
-    # Create Seurat object and append metadata
-    cellMix <- CreateSeuratObject(counts = counts, project = "cellMix", min.cells = 1)
-    cellMix\$sample     <- setNames(colData(se)\$sampleName,  colnames(se))
-    cellMix\$chemistry  <- setNames(colData(se)\$chemistry,   colnames(se))
-    cellMix\$technology <- setNames(colData(se)\$technology,  colnames(se))
-    cellMix\$orig.ident <- cellMix\$sample
+    # Create Seurat object with bambu's colData as its metadata
+    cellMix <- createSeuratObject("$gene_counts", metadata = metadata, minCells = 1, project = "cellMix")
+    cellMix\$orig.ident <- cellMix\$sampleName
 
     # scRNA-seq multi-sample integration using Harmony adapted from https://satijalab.org/seurat/articles/seurat5_integration
-    cellMix[["RNA"]] <- split(cellMix[["RNA"]], f = cellMix\$sample)
+    cellMix[["RNA"]] <- split(cellMix[["RNA"]], f = cellMix\$sampleName)
     cellMix <- NormalizeData(cellMix)
     cellMix <- FindVariableFeatures(cellMix)
     cellMix <- ScaleData(cellMix)
@@ -58,9 +53,9 @@ process SEURAT_MULTI_SAMPLE {
 
     writeLines(c(
         '"${task.process}":',
-        paste0('    R: ',                   R.Version()\$version.string),
-        paste0('    seurat: ',              as.character(packageVersion("Seurat"))),
-        paste0('    SummarizedExperiment: ', as.character(packageVersion("SummarizedExperiment")))
+        paste0('    R: ',       R.Version()\$version.string),
+        paste0('    seurat: ',  as.character(packageVersion("Seurat"))),
+        paste0('    harmony: ', as.character(packageVersion("harmony")))
     ), "versions.yml")
     """
 }
diff --git a/modules/seurat/standard/single_sample_clustering.nf b/modules/seurat/standard/single_sample_clustering.nf
index 4730ba8..3731564 100644
--- a/modules/seurat/standard/single_sample_clustering.nf
+++ b/modules/seurat/standard/single_sample_clustering.nf
@@ -1,13 +1,13 @@
 process SEURAT_SINGLE_SAMPLE {
     publishDir "$params.output_dir", mode: 'copy', pattern: 'seurat_obj.rds'
     publishDir "$params.output_dir/intermediate_R", mode: 'copy', pattern: 'clusters.rds', enabled: params.save_intermediates
-    label "r"
+    label "seurat"
     label "medium_cpu"
     label "medium_mem"
     label "medium"
 
     input:
-    path(se)
+    tuple path(gene_counts), path(col_data)
 
     output:
     path ('clusters.rds'), emit: clusters
@@ -17,19 +17,20 @@ process SEURAT_SINGLE_SAMPLE {
     script:
     """
     #!/usr/bin/env Rscript
-    library(SummarizedExperiment)
     library(Seurat)
+    source(Sys.which("create_seurat_object.R"))
 
-    se     <- readRDS("$se")
-    counts <- assays(se)\$counts
-    dim    <- $params.seurat_dim_single
+    metadata <- readRDS("$col_data")
+    dim      <- $params.seurat_dim_single
+
+    # Create Seurat object with bambu's colData as its metadata
+    cellMix <- createSeuratObject("$gene_counts", metadata = metadata, minCells = 1, project = "cellMix")
 
     # Single sample scRNA-seq clustering adapted from https://satijalab.org/seurat/articles/pbmc3k_tutorial.html
-    cellMix <- CreateSeuratObject(counts = counts, project = "cellMix", min.cells = 1)
     cellMix <- NormalizeData(cellMix, normalization.method = "LogNormalize", scale.factor = 10000)
     cellMix <- FindVariableFeatures(cellMix, selection.method = "vst", nfeatures = 2500)
     cellMix <- ScaleData(cellMix)
-    npcs    <- ifelse(ncol(counts) > 50, 50, ncol(counts) - 1)
+    npcs    <- ifelse(ncol(cellMix) > 50, 50, ncol(cellMix) - 1)
     cellMix <- RunPCA(cellMix, features = VariableFeatures(object = cellMix), npcs = npcs)
     dim     <- ifelse(dim >= dim(cellMix@reductions\$pca)[2], dim(cellMix@reductions\$pca)[2], dim)
     cellMix <- FindNeighbors(cellMix, dims = 1:dim)
@@ -42,9 +43,8 @@ process SEURAT_SINGLE_SAMPLE {
     
     writeLines(c(
         '"${task.process}":',
-        paste0('    R: ',                   R.Version()\$version.string),
-        paste0('    seurat: ',              as.character(packageVersion("Seurat"))),
-        paste0('    SummarizedExperiment: ', as.character(packageVersion("SummarizedExperiment")))
+        paste0('    R: ',      R.Version()\$version.string),
+        paste0('    seurat: ', as.character(packageVersion("Seurat")))
     ), "versions.yml")
     """
 }
diff --git a/modules/seurat/visium_hd/clustering.nf b/modules/seurat/visium_hd/clustering.nf
index 1c6f4a2..3b6e31b 100644
--- a/modules/seurat/visium_hd/clustering.nf
+++ b/modules/seurat/visium_hd/clustering.nf
@@ -1,12 +1,12 @@
 process SEURAT_VISIUM_HD {
     publishDir "$params.output_dir", mode: 'copy', pattern: 'seurat_obj.rds'
-    label "r"
+    label "seurat"
     label "medium_cpu"
     label "high_mem"
     label "long"
 
     input:
-    tuple val(resolution), path(se_gene_counts), path(spot_mappings)
+    tuple val(resolution), path(gene_counts), path(col_data), path(spot_mappings)
 
     output:
     path ("clusters.rds"), emit: clusters
@@ -17,16 +17,19 @@ process SEURAT_VISIUM_HD {
     """
     #!/usr/bin/env Rscript
     library(Seurat)
-    library(SummarizedExperiment)
+    source(Sys.which("create_seurat_object.R"))
     source(Sys.which("visium_hd_cluster.R"))
 
     banksy <- as.logical("$params.banksy")
     assay  <- "Spatial.$resolution"
 
-    # the aggregated SE already carries each bin's tissue position in colData
-    se           <- readRDS("$se_gene_counts")
+    # Load spotMappings containing 2um barcode to bin (e.g., 8um/16um) mapping information 
     spotMappings <- read.csv("$spot_mappings", stringsAsFactors = FALSE)
-    object       <- CreateSeuratObject(assays(se)\$counts, assay = assay, meta.data = as.data.frame(colData(se)))
+
+    # Create Seurat object with bambu's colData as its metadata
+    colData      <- readRDS("$col_data")
+    binMetadata  <- colData[, colnames(colData) != "barcodes"] # drop barcodes column (list) to prevent downstream issues with Seurat
+    object       <- createSeuratObject("$gene_counts", assay = assay, metadata = binMetadata)
 
     DefaultAssay(object) <- assay
     object <- NormalizeData(object, verbose = FALSE)
diff --git a/subworkflows/clustering_standard.nf b/subworkflows/clustering_standard.nf
index 8436ed8..4d9168f 100644
--- a/subworkflows/clustering_standard.nf
+++ b/subworkflows/clustering_standard.nf
@@ -3,19 +3,21 @@ include { SEURAT_MULTI_SAMPLE  } from '../modules/seurat/standard/multi_sample_c
 
 workflow CLUSTERING {
     take:
-    ch_se_gene_counts
+    ch_gene_counts
+    ch_col_data
     ch_n_samples
 
     main:
-    ch_se_branched = ch_se_gene_counts
+    ch_branched = ch_gene_counts
+        .combine(ch_col_data)
         .combine(ch_n_samples)
-        .branch { _se, n ->
+        .branch { _gene_counts, _col_data, n ->
             single: n == 1
             multi:  n > 1
         }
 
-    SEURAT_SINGLE_SAMPLE(ch_se_branched.single.map { se, _n -> se })
-    SEURAT_MULTI_SAMPLE(ch_se_branched.multi.map { se, _n -> se })
+    SEURAT_SINGLE_SAMPLE(ch_branched.single.map { gene_counts, col_data, _n -> [gene_counts, col_data] })
+    SEURAT_MULTI_SAMPLE(ch_branched.multi.map { gene_counts, col_data, _n -> [gene_counts, col_data] })
 
     emit:
     clusters = SEURAT_SINGLE_SAMPLE.out.clusters.mix(SEURAT_MULTI_SAMPLE.out.clusters)

From d8da7e321a475e8021b4eed42734e44e28c90729 Mon Sep 17 00:00:00 2001
From: ch99l <chinhaolee10@gmail.com>
Date: Thu, 30 Jul 2026 20:24:53 +0800
Subject: [PATCH 2/2] update seurat Dockerfile

---
 containers/seurat/Dockerfile | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/containers/seurat/Dockerfile b/containers/seurat/Dockerfile
index 6ad4048..acd99bf 100644
--- a/containers/seurat/Dockerfile
+++ b/containers/seurat/Dockerfile
@@ -2,7 +2,9 @@
 FROM satijalab/seurat:5.4.0
 
 # procps supplies the ps that Nextflow uses to collect task metrics
-RUN apt-get update && apt-get install -y --no-install-recommends procps \
+# libmagick++-dev is needed by magick, an import of SpatialExperiment (a Banksy dependency)
+RUN apt-get update && apt-get install -y --no-install-recommends \
+        procps libmagick++-dev \
     && rm -rf /var/lib/apt/lists/*
 
 # Install Seurat Wrappers, plus Banksy for spatially aware clustering (Banksy is only a