fix(qc): address review feedback on PR #205

- GPU: wire --num-gpus into image_qc.py + set CUDA_VISIBLE_DEVICES in the
  module so num_gpus actually caps device use; add process_gpu_qc to the aws
  profile GPU-queue routing; add schema minimum:0.
- publishDir: stop double-nesting (qc/image_qc/image_qc -> qc/image_qc) for
  both QC analysis steps.
- Finish molecule->transcript rename in outputs (metrics JSON keys + figure
  filenames) and the report's reads; fix an exposed figure-name collision.
- Wire ch_qc_reports from the QC reports so the MultiQC collection isn't dead.
- Schema: move QC params into a dedicated qc_options group.
- Make ROI tile size configurable via params.image_qc_roi_size.
- Commit the previously-missing pytest unit tests for the transcript QC maths.
- Docs: CHANGELOG entry + usage.md QC-mode section.

Co-authored-by: Malwina Prater <mprater@altoslabs.com>
Co-authored-by: Nell Nie <nnie@altoslabs.com>
Co-authored-by: Christel Krueger <ckrueger@altoslabs.com>

Author: 4 people

CHANGELOG.md

@@ -3,6 +3,14 @@
 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).
 
+## dev
+
+### `Added`
+
+- Image QC and transcript QC subworkflow (`QC`): runs `IMAGE_QC_ANALYSIS` (focus / SNR / morphology metrics) and `TRANSCRIPT_QC_PROCESSING` (per-transcript and per-cell metrics), each rendering a Quarto HTML report via the shared `QUARTO` module. New `image_qc`, `transcript_qc`, and `quarto` local modules with pinned `environment.yml` and Dockerfiles.
+- GPU-optional image QC via `params.num_gpus` (`null` = CPU; `N` = request and cap to N GPUs via the accelerator directive + `CUDA_VISIBLE_DEVICES`).
+- New QC parameters: `num_gpus`, `stain_names`, `neg_control_prefix`, `roi_image_qc_thresholds_yaml`, and the `image_qc_*` analysis flags (with `nextflow_schema.json` entries).
+
 ## 1.0.1 - [06.08.2026]
 
 Hotfix to tackle some bugs

assets/notebooks/transcript_qc.qmd

@@ -67,12 +67,12 @@ with open(metrics_file, 'r') as f:
     qc_metrics = json.load(f)
 
 print("=== TRANSCRIPT QC SUMMARY ===")
-print(f"Total molecules: {qc_metrics['total_molecules']:,}")
-print(f"Selected molecules: {qc_metrics['selected_molecules']:,}")
+print(f"Total molecules: {qc_metrics['total_transcripts']:,}")
+print(f"Selected molecules: {qc_metrics['selected_transcripts']:,}")
 print(f"Total features: {qc_metrics['total_features']:,}")
 print(f"Total cells: {qc_metrics['total_cells']:,}")
 print(f"Analyzed genes: {qc_metrics['analyzed_genes']:,}")
-print(f"Min molecules per cell: {qc_metrics['min_molecules_per_cell']:,}")
+print(f"Min molecules per cell: {qc_metrics['min_transcripts_per_cell']:,}")
 print(f"Min genes per cell: {qc_metrics['min_genes_per_cell']:,}")
 ```
 
@@ -167,7 +167,7 @@ Next, we examine the distribution of molecules assigned to each feature across t
 
 ```{python display-molecules-per-feature}
 #| echo: false
-display_figure("num_molecules_per_feature.png")
+display_figure("num_transcripts_per_feature.png")
 ```
 
 **Molecule count distribution interpretation:**
@@ -211,7 +211,7 @@ This plot shows the fraction of detected RNA molecules that are located within t
 
 ```{python display-nucleus-rna-fraction}
 #| echo: false
-display_figure("nucleus_molecule_fraction_per_cell_distribution.png")
+display_figure("nucleus_transcript_fraction_per_cell_distribution.png")
 ```
 
 **Nucleus RNA fraction interpretation:**
@@ -249,7 +249,7 @@ We first show a histogram of molecules per cell. The distribution pattern is cru
 
 ```{python display-molecules-per-cell}
 #| echo: false
-display_figure("num_molecules_per_cell.png")
+display_figure("num_transcripts_per_cell.png")
 ```
 
 **Distribution patterns and their meanings:**
@@ -278,7 +278,7 @@ Similarly, we examine the number of unique genes detected per cell, which is ano
 
 ```{python display-genes-per-cell}
 #| echo: false
-display_figure("num_transcripts_per_cell.png")
+display_figure("num_genes_per_cell.png")
 ```
 
 **Gene detection patterns:**

bin/image_qc.py

@@ -8780,6 +8780,15 @@ def _check_cell_data_exists(xenium_bundle_dir):
     show_default=True,
     help="Gaussian sigma for Laplacian of Gaussian (LoG) pre-smoothing.",
 )
+@click.option(
+    "--num-gpus",
+    default=None,
+    type=int,
+    help=(
+        "Maximum number of GPUs to use. If not set, all visible GPUs are used. "
+        "Set to 0 to force the CPU backend."
+    ),
+)
 def main(
     xenium_bundle_dir,
     outdir,
@@ -8795,6 +8804,7 @@ def main(
     save_dapi_maps_tiff,
     roi_thresholds_yaml,
     lap_sigma,
+    num_gpus,
 ):
     """
     Combined Xenium Image QC pipeline.
@@ -8960,8 +8970,19 @@ def main(
     else:
         logging.info(f"Using tile size: {roi_size}px")
 
-    # Auto-detect available GPUs
+    # Auto-detect available GPUs, then cap to --num-gpus when requested
     available_gpus = detect_gpu_ids()
+    if num_gpus is not None:
+        if num_gpus <= 0:
+            logging.info("--num-gpus=%s requested, forcing CPU backend", num_gpus)
+            available_gpus = []
+        elif len(available_gpus) > num_gpus:
+            logging.info(
+                "Capping GPU usage to %d of %d visible device(s) (--num-gpus)",
+                num_gpus,
+                len(available_gpus),
+            )
+            available_gpus = available_gpus[:num_gpus]
     if available_gpus:
         logging.info(f"Detected {len(available_gpus)} GPU(s): {available_gpus}")
     else:

bin/transcript_qc_processing.py

@@ -399,18 +399,22 @@ def main():
     plt.title("Distribution of molecules per feature", fontsize=14, pad=20)
     plt.tight_layout()
     plt.savefig(
-        f"{output_fig_dir}/num_molecules_per_feature.pdf", dpi=300, bbox_inches="tight"
+        f"{output_fig_dir}/num_transcripts_per_feature.pdf",
+        dpi=300,
+        bbox_inches="tight",
     )
     plt.savefig(
-        f"{output_fig_dir}/num_molecules_per_feature.png", dpi=300, bbox_inches="tight"
+        f"{output_fig_dir}/num_transcripts_per_feature.png",
+        dpi=300,
+        bbox_inches="tight",
     )
     plt.close(fig)
 
     # Save data for molecules per feature
     df_molecules_per_feature = n_mols_per_gene_df.copy()
     df_molecules_per_feature["n_mols_threshold"] = n_mols_threshold
     df_molecules_per_feature.to_csv(
-        figures_source_dir / "num_molecules_per_feature.csv", index=True
+        figures_source_dir / "num_transcripts_per_feature.csv", index=True
     )
 
     retained_genes = n_mols_per_gene_df.query(
@@ -501,14 +505,14 @@ def main():
     # Save the plot
     plt.savefig(
         os.path.join(
-            outdir, "figures", "nucleus_molecule_fraction_per_cell_distribution.pdf"
+            outdir, "figures", "nucleus_transcript_fraction_per_cell_distribution.pdf"
         ),
         dpi=300,
         bbox_inches="tight",
     )
     plt.savefig(
         os.path.join(
-            outdir, "figures", "nucleus_molecule_fraction_per_cell_distribution.png"
+            outdir, "figures", "nucleus_transcript_fraction_per_cell_distribution.png"
         ),
         dpi=300,
         bbox_inches="tight",
@@ -524,7 +528,7 @@ def main():
         }
     )
     df_nucleus_fraction.to_csv(
-        figures_source_dir / "nucleus_molecule_fraction_per_cell_distribution.csv",
+        figures_source_dir / "nucleus_transcript_fraction_per_cell_distribution.csv",
         index=False,
     )
     del cells_parquet
@@ -597,10 +601,10 @@ def main():
     plt.title("Distribution of molecules per Cell", fontsize=14, pad=20)
     plt.tight_layout()
     plt.savefig(
-        f"{output_fig_dir}/num_molecules_per_cell.pdf", dpi=300, bbox_inches="tight"
+        f"{output_fig_dir}/num_transcripts_per_cell.pdf", dpi=300, bbox_inches="tight"
     )
     plt.savefig(
-        f"{output_fig_dir}/num_molecules_per_cell.png", dpi=300, bbox_inches="tight"
+        f"{output_fig_dir}/num_transcripts_per_cell.png", dpi=300, bbox_inches="tight"
     )
     plt.close(fig)
     print(f"Threshold for molecules per cell: {n_mols_threshold_cell}")
@@ -613,7 +617,7 @@ def main():
         }
     )
     df_molecules_per_cell.to_csv(
-        figures_source_dir / "num_molecules_per_cell.csv", index=False
+        figures_source_dir / "num_transcripts_per_cell.csv", index=False
     )
 
     # Convert numpy array to pandas DataFrame
@@ -635,20 +639,18 @@ def main():
     plt.title("Distribution of number of detected genes per Cell", fontsize=14, pad=20)
     plt.tight_layout()
     plt.savefig(
-        f"{output_fig_dir}/num_transcripts_per_cell.pdf", dpi=300, bbox_inches="tight"
+        f"{output_fig_dir}/num_genes_per_cell.pdf", dpi=300, bbox_inches="tight"
     )
     plt.savefig(
-        f"{output_fig_dir}/num_transcripts_per_cell.png", dpi=300, bbox_inches="tight"
+        f"{output_fig_dir}/num_genes_per_cell.png", dpi=300, bbox_inches="tight"
     )
     plt.close(fig)
 
     # Save data for genes per cell
     df_genes_per_cell = pd.DataFrame(
         {"n_genes_per_cell": n_genes_per_cell, "n_genes_threshold": n_genes_threshold}
     )
-    df_genes_per_cell.to_csv(
-        figures_source_dir / "num_transcripts_per_cell.csv", index=False
-    )
+    df_genes_per_cell.to_csv(figures_source_dir / "num_genes_per_cell.csv", index=False)
 
     # Convert numpy array to pandas DataFrame
     n_genes_per_cell_df = pd.DataFrame(n_genes_per_cell, columns=["num_of_genes"])
@@ -659,14 +661,14 @@ def main():
 
     # EXACT CODE FROM ORIGINAL NOTEBOOK - Save metrics
     metrics = {
-        "total_molecules": int(num_molecules),
-        "selected_molecules": int(num_selected_molecules),
+        "total_transcripts": int(num_molecules),
+        "selected_transcripts": int(num_selected_molecules),
         "total_features": int(df_spatial.feature_name.nunique()),
         "codeword_category_counts": {
             str(k): int(v) for k, v in codeword_category_counts.items()
         },
         "neg_control_quantile": int(n_mols_threshold),
-        "min_molecules_per_cell": int(n_mols_threshold_cell),
+        "min_transcripts_per_cell": int(n_mols_threshold_cell),
         "min_genes_per_cell": int(n_genes_threshold),
         "retained_genes_count": len(retained_genes),
         "total_cells": int(ad.shape[0]),

conf/modules.config

@@ -385,6 +385,7 @@ process {
         ext.prefix = 'image_qc'
         ext.args = {
             [
+                params.image_qc_roi_size != null ? "--roi-size ${params.image_qc_roi_size}" : '',
                 params.legacy_focus ? '--legacy-focus' : '',
                 params.image_qc_no_snr ? '--no-snr' : '',
                 params.image_qc_snr_no_roi_tx_table ? '--snr-no-roi-tx-table' : '',
@@ -394,8 +395,9 @@ process {
                 params.image_qc_lap_sigma != null ? "--lap-sigma ${params.image_qc_lap_sigma}" : '',
             ].findAll { it }.join(' ')
         }
+        // output dir is already named 'image_qc' (ext.prefix), so publish into qc/ (not qc/image_qc) to avoid qc/image_qc/image_qc
         publishDir = [
-            path: { "${params.outdir}/${params.mode}/qc/image_qc" },
+            path: { "${params.outdir}/${params.mode}/qc" },
             mode: params.publish_dir_mode,
         ]
     }
@@ -413,8 +415,9 @@ process {
 
     withName: '.*TRANSCRIPT_QC:ANALYSIS' {
         ext.prefix = 'transcript_qc'
+        // output dir is already named 'transcript_qc' (ext.prefix), so publish into qc/ (not qc/transcript_qc)
         publishDir = [
-            path: { "${params.outdir}/${params.mode}/qc/transcript_qc" },
+            path: { "${params.outdir}/${params.mode}/qc" },
             mode: params.publish_dir_mode,
         ]
     }

docs/usage.md

@@ -71,6 +71,22 @@ nextflow run nf-core/spatialaxe \
    --mode segfree
 ```
 
+### QC mode
+
+`IMAGE_QC ➔ TRANSCRIPT_QC`
+
+Runs the quality-control layer only — image QC (focus / SNR / morphology) and transcript QC (per-transcript and per-cell metrics), each producing an HTML report. The QC layer also runs as part of the other modes (`run_qc = true` by default).
+
+```bash
+nextflow run nf-core/spatialaxe \
+   -profile <docker/singularity/.../institute> \
+   --input samplesheet.csv \
+   --outdir <OUTDIR> \
+   --mode qc
+```
+
+Image QC is GPU-optional: leave `--num_gpus` unset for CPU, or set `--num_gpus N` to request and use N GPUs (requires a GPU-enabled profile/queue).
+
 ### Preview mode <br>
 
 `BAYSOR_PREVIEW`

modules/local/image_qc/main.nf

@@ -56,12 +56,20 @@ process IMAGE_QC_ANALYSIS {
         args << "--stain-names 'DAPI;Boundary (ATP1A1/E-Cadherin/CD45);Interior - RNA (18S);Protein (alphaSMA/Vimentin)'"
     }
 
-    // ROI size parameter
-    if (param_map.containsKey('ROI_SIZE') && param_map['ROI_SIZE']) {
-        args << "--roi-size ${param_map['ROI_SIZE']}"
-    }
-    else {
-        args << "--roi-size 35"
+    // --roi-size comes from conf/modules.config ext.args (params.image_qc_roi_size),
+    // keeping this module parameter-agnostic.
+
+    // GPU cap: pass --num-gpus to the script only when the user set params.num_gpus.
+    // Mirror modules/local/segger/train pattern -- constrain CUDA_VISIBLE_DEVICES so
+    // the process never grabs more GPUs than requested (accelerator directive from
+    // conf/base.config process_gpu_qc already requests this many devices).
+    def num_gpus = params.num_gpus
+    def cuda_visible = ''
+    if (num_gpus != null) {
+        args << "--num-gpus ${num_gpus}"
+        cuda_visible = (num_gpus as int) > 0
+            ? "export CUDA_VISIBLE_DEVICES=" + (0..<(num_gpus as int)).join(',')
+            : "export CUDA_VISIBLE_DEVICES="
     }
 
     // Analysis-tuning flags (--legacy-focus, --no-snr, --snr-*, --save-dapi-maps-tiff,
@@ -72,6 +80,7 @@ process IMAGE_QC_ANALYSIS {
     export OPENBLAS_NUM_THREADS="${task.cpus}"
     export OMP_NUM_THREADS="${task.cpus}"
     export NUMBA_NUM_THREADS="${task.cpus}"
+    ${cuda_visible}
 
     image_qc.py \\
         ${args.join(' \\\n        ')} \\

nextflow.config

@@ -118,6 +118,7 @@ params {
     stain_names                = null       // semicolon-separated stain/channel names for the morphology image (null = image QC defaults)
     neg_control_prefix         = 'NegControl' // prefix for Xenium negative controls (matches both NegControlProbe_* and NegControlCodeword_*); passed to transcript QC as --non-gene-prefix
     roi_image_qc_thresholds_yaml = null     // path to ROI threshold config for image QC (null = bundled conf/roi_image_qc_thresholds.yaml)
+    image_qc_roi_size          = 35         // image QC: ROI tile size in pixels for the grid focus/SNR analysis
     legacy_focus               = false      // image QC: use the CPU for-loop focus score instead of GPU convolution
     image_qc_no_snr            = false      // image QC: skip signal-to-noise (SNR) metrics
     image_qc_snr_no_roi_tx_table = false    // image QC: do not write the per-ROI transcript SNR table
@@ -296,6 +297,16 @@ profiles {
                 containerOptions = { "--shm-size ${task.memory.toGiga()}g" }
                 queue = { params.cellpose_queue ?: params.gpu_queue ?: null }
             }
+            withLabel:process_gpu_qc {
+                // Must repeat base.config label properties — profile withLabel replaces, not merges.
+                // Route image QC to the GPU queue whenever an accelerator is requested (params.num_gpus).
+                accelerator = { params.num_gpus ? (params.num_gpus as int) : null }
+                cpus   = { 30 * task.attempt }
+                memory = { 180.GB * task.attempt }
+                time   = { 8.h * task.attempt }
+                containerOptions = { "--shm-size ${task.memory.toGiga()}g" }
+                queue = { params.gpu_queue ?: null }
+            }
         }
     }
     test      { includeConfig 'conf/test.config'      }