Fix bug with probeset and index mismatch when using cellranger multi with a probeset and without a pre-built index

CHANGELOG.md

@@ -3,6 +3,12 @@
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Features
+
+- Fix [#375](https://github.com/nf-core/scrnaseq/issues/375): mismatch between index and probeset when cellranger multi is used without a prebuilt index and an FFPE probeset is passed ([#502](https://github.com/nf-core/scrnaseq/pull/502))
+
 ## v4.1.0 - 2025-08-01
 
 ### Features

assets/frna_probeset_subset.csv

@@ -1,7 +1,7 @@
 #probe_set_file_format=2.0
 #panel_name=Chromium Human Transcriptome Probe Set v1.0.1
 #panel_type=predesigned
-#reference_genome=gex_reference
+#reference_genome=GRCh38
 #reference_version=2020-A
 gene_id,probe_seq,probe_id,included,region
 ENSG00000000003,GGTGACACCACAACAATGCAACGTATTTTGGATCTTGTCTACTGCATGGC,ENSG00000000003|TSPAN6|8eab823,TRUE,spliced

conf/test_cellranger_multi.config

@@ -46,6 +46,7 @@ profiles {
             cellranger_multi_barcodes = "${projectDir}/assets/cellranger_barcodes_samplesheet.csv"
             gex_frna_probe_set        = "${projectDir}/assets/frna_probeset_subset.csv"
             fb_reference              = "${projectDir}/assets/fb_reference.csv"
+            gex_reference_version     = "GRCh38"
 
             // Genome references
             fasta           = 'https://ftp.ensembl.org/pub/release-110/fasta/homo_sapiens/dna/Homo_sapiens.GRCh38.dna.chromosome.14.fa.gz'

docs/usage.md

@@ -282,8 +282,10 @@ If you are using cellranger-multi you have to add the column _feature_type_ to i
 
   > When running cellranger multi, without any VDJ data, users can also skip VDJ automated ref building with: `--skip_cellrangermulti_vdjref`.
 
-- When working with **FFPE data**, a prob set needs to be specified via `--gex_frna_probe_set`. This file is typically
-  [provided by 10x](https://www.10xgenomics.com/support/software/cell-ranger/downloads#probe-set-downloads). E.g. [testing ffpe probe set](../assets/frna_probeset_subset.csv).
+- When working with **FFPE data**:
+  - a probe set needs to be specified via `--gex_frna_probe_set`. This file is typically
+    [provided by 10x](https://www.10xgenomics.com/support/software/cell-ranger/downloads#probe-set-downloads). E.g. [testing ffpe probe set](../assets/frna_probeset_subset.csv).
+  - a GEX reference genome version (e.g. GRCh38, GRCm39) via `--gex_reference_version` must be specified unless a pre-built index is provided via `--cellranger_index`. This **must** match the reference in the probe set, which can be found in the header.
 
 - When working with **Cell Multiplexing Oligos (CMOs)**, a reference file can to be provided via `--gex_cmo_set`. The
   default reference file, as well as a description how to write a custom one, are [available from the 10x documentation](https://www.10xgenomics.com/support/software/cell-ranger/latest/analysis/running-pipelines/cr-3p-multi#cmo-ref). By default, the Cell Ranger's default CMO-set.

nextflow.config

@@ -59,6 +59,7 @@ params {
     vdj_inner_enrichment_primers = null
     gex_barcode_sample_assignment = null
     cellranger_multi_barcodes = null
+    gex_reference_version = null
 
 
     // Template Boilerplate options

nextflow_schema.json

@@ -330,6 +330,10 @@
                     "exists": true,
                     "description": "Provide a probe set for fixed RNA-seq profiling (used with FFPE samples). Please refer to the [10x documentation about probesets](https://www.10xgenomics.com/support/single-cell-gene-expression-flex/documentation/steps/probe-sets/chromium-frp-probe-set-files) for more details."
                 },
+                "gex_reference_version": {
+                    "type": "string",
+                    "description": "Reference version (e.g. GRCh38, GRCm39). Required if `gex_frna_probe_set` is used and `cellranger_index` is not set. Must match the genome version in the `gex_frna_probe_set` file."
+                },
                 "gex_target_panel": {
                     "type": "string",
                     "description": "Provide a panel description for targeted sequencing.",

subworkflows/local/align_cellrangermulti.nf

@@ -136,11 +136,38 @@ workflow CELLRANGER_MULTI_ALIGN {
         //
         if ( !cellranger_gex_index ) {
 
+            // Validate that gex_reference_version is provided when required
+            if ( params.gex_frna_probe_set && !params.gex_reference_version ) {
+                error "Parameter 'gex_reference_version' is required when 'gex_frna_probe_set' is provided and 'cellranger_index' is not provided. The reference genome version must match the probeset reference."
+            }
+
+            // Validate that gex_reference_version matches the probeset reference genome
+            if ( params.gex_frna_probe_set && params.gex_reference_version ) {
+                def probeset_file = file(params.gex_frna_probe_set)
+                def probeset_reference = null
+                probeset_file.withReader { reader ->
+                    String line
+                    while ((line = reader.readLine()) != null) {
+                        if (line.startsWith("#reference_genome=")) {
+                            ref_split = line.split("=")
+                            if (ref_split.size() > 1) {
+                                probeset_reference = ref_split[1].trim()
+                            }
+                            break
+                        }
+                    }
+                }
+                if ( probeset_reference != params.gex_reference_version ) {
+                    error "Parameter 'gex_reference_version' (${params.gex_reference_version}) does not match the probeset reference genome (${probeset_reference}). Please ensure the reference genome version matches the probeset file."
+                }
+            }
+
             // Make reference genome
+            def reference_name = params.gex_reference_version ?: "gex_reference_version"
             CELLRANGER_MKREF(
                 ch_fasta,
                 CELLRANGER_MKGTF.out.gtf,
-                "gex_reference"
+                reference_name
             )
             ch_versions = ch_versions.mix(CELLRANGER_MKREF.out.versions)
             ch_cellranger_gex_index = CELLRANGER_MKREF.out.reference.ifEmpty { [] }

tests/main_pipeline_cellrangermulti.nf.test

@@ -15,6 +15,7 @@ nextflow_pipeline {
                 input                     = "${baseDir}/assets/cellrangermulti_samplesheet.csv"
                 cellranger_multi_barcodes = "${baseDir}/assets/cellranger_barcodes_samplesheet.csv"
                 gex_frna_probe_set        = "${baseDir}/assets/frna_probeset_subset.csv"
+                gex_reference_version     = "GRCh38"
                 fb_reference              = "${baseDir}/assets/fb_reference.csv"
                 fasta                     = 'https://ftp.ensembl.org/pub/release-110/fasta/homo_sapiens/dna/Homo_sapiens.GRCh38.dna.chromosome.14.fa.gz'
                 gtf                       = 'https://ftp.ensembl.org/pub/release-110/gtf/homo_sapiens/Homo_sapiens.GRCh38.110.gtf.gz'
@@ -83,5 +84,61 @@ nextflow_pipeline {
         }
     }
 
+    test("test-dataset_cellrangermulti_missing_gex_reference") {
+
+        when {
+            params {
+                aligner                   = 'cellrangermulti'
+                outdir                    = "${outputDir}/results_cellrangermulti_missing_ref"
+                input                     = "${baseDir}/assets/cellrangermulti_samplesheet.csv"
+                cellranger_multi_barcodes = "${baseDir}/assets/cellranger_barcodes_samplesheet.csv"
+                gex_frna_probe_set        = "${baseDir}/assets/frna_probeset_subset.csv"
+                fb_reference              = "${baseDir}/assets/fb_reference.csv"
+                fasta                     = 'https://ftp.ensembl.org/pub/release-110/fasta/homo_sapiens/dna/Homo_sapiens.GRCh38.dna.chromosome.14.fa.gz'
+                gtf                       = 'https://ftp.ensembl.org/pub/release-110/gtf/homo_sapiens/Homo_sapiens.GRCh38.110.gtf.gz'
+                protocol                  = 'auto'
+                skip_cellbender           = true
+                // Note: gex_reference_version is intentionally NOT provided to test validation
+            }
+        }
+
+        then {
+            // Should fail with validation error
+            assertAll(
+                {assert !workflow.success},
+                {assert workflow.failed},
+                {assert workflow.stdout.any { it.contains("Parameter 'gex_reference_version' is required when 'gex_frna_probe_set' is provided and 'cellranger_index' is not provided") } }
+            )
+        }
+    }
+
+    test("test-dataset_cellrangermulti_mismatched_gex_reference") {
+
+        when {
+            params {
+                aligner                   = 'cellrangermulti'
+                outdir                    = "${outputDir}/results_cellrangermulti_mismatch"
+                input                     = "${baseDir}/assets/cellrangermulti_samplesheet.csv"
+                cellranger_multi_barcodes = "${baseDir}/assets/cellranger_barcodes_samplesheet.csv"
+                gex_frna_probe_set        = "${baseDir}/assets/frna_probeset_subset.csv"
+                gex_reference_version     = "GRCm39" // Intentionally wrong - probeset is GRCh38
+                fb_reference              = "${baseDir}/assets/fb_reference.csv"
+                fasta                     = 'https://ftp.ensembl.org/pub/release-110/fasta/homo_sapiens/dna/Homo_sapiens.GRCh38.dna.chromosome.14.fa.gz'
+                gtf                       = 'https://ftp.ensembl.org/pub/release-110/gtf/homo_sapiens/Homo_sapiens.GRCh38.110.gtf.gz'
+                protocol                  = 'auto'
+                skip_cellbender           = true
+            }
+        }
+
+        then {
+            // Should fail with validation error
+            assertAll(
+                {assert !workflow.success},
+                {assert workflow.failed},
+                {assert workflow.stdout.any { it.contains("Parameter 'gex_reference_version' (GRCm39) does not match the probeset reference genome (GRCh38)") } }
+            )
+        }
+    }
+
 
 }