Enhancement: Add nuclei-per-cell stacked bar plot to Xenium module

[nmalwinka]

Enhancement: Add nuclei-per-cell stacked bar plot to Xenium module

Summary

Add a new plot to the xenium-extra plugin showing the distribution of nuclei counts per cell, grouped into three categories. This metric is a useful quality indicator for segmentation accuracy and tissue-type characterisation.

Motivation

The number of nuclei per cell is a valuable QC metric that can immediately flag segmentation issues — for example, over-segmentation (cells with 0 nuclei) or unexpected multi-nucleation patterns that may indicate merge errors or genuine biological signal (e.g. skeletal muscle, cardiac tissue). Having this visible in a MultiQC report makes it easy to compare across samples and tissue types at a glance.

This metric requires parsing cells.csv.gz, which involves more data extraction than a basic cell-metrics CSV. It therefore fits naturally in the xenium-extra plugin rather than the core Xenium module.

Data source

The nucleus_count column is already present in cells.csv.gz, found in the root of the Xenium output bundle:

cell_id, x_centroid, y_centroid, ..., nucleus_count, segmentation_method

Example rows:

"aaaagkdm-1", ..., 0, "Segmented by boundary stain (ATP1A1+CD45+E-Cadherin)"
"aaaamcnn-1", ..., 1, "Segmented by boundary stain (ATP1A1+CD45+E-Cadherin)"

Proposed plot

A stacked bar graph with one bar per sample, broken down into three categories:

Category	Definition
0	Cells with no detected nucleus
1	Cells with exactly one nucleus
multiple	Cells with 2+ nuclei

Grouping into these three bins keeps the plot readable while capturing the most diagnostically relevant distinctions.

Expected value

• Flags segmentation issues early (e.g. high proportion of 0-nucleus cells suggests under-segmentation or boundary stain failure)
• Highlights multi-nucleated cell populations relevant to specific tissue types
• Complements existing transcript and area metrics for a more complete per-cell QC picture

Implementation notes

• Read cells.csv.gz (already parsed elsewhere in the plugin)
• Extract nucleus_count column
• Bin values into 0, 1, multiple (≥2)
• Compute per-sample proportions or absolute counts
• Render as a bargraph using the standard MultiQC plotting API

[nmalwinka]

Bug fix bundled into this PR

While preparing the new "Nuclei per Cell" plot, I discovered that the existing "Fraction of Transcripts in Nucleus" plot in xenium-extra has been silently producing incorrect values since v1.0.0. We are fixing it in the same PR.

In multiqc_xenium_extra/xenium_extra.py:933-981 (inside parse_cells_parquet), the plot's source metric was computed as:

nucleus_count / total_counts # both columns from cells.parquet

This is wrong as nucleus_count is not a transcript count. Per the 10x Xenium schema, nucleus_count in cells.parquet is the number of segmented nuclei per cell — small integers, typically 0, 1, or 2+. Dividing it by total_counts produces 1 / total_counts (≈ 0.005–1.0) on samples where every cell has exactly one nucleus, which has no biological meaning.

On the verification sample (6,542 cells, all with nucleus_count == 1), the broken metric produced a mean "nucleus RNA fraction" of ~0.08. The corrected metric on the same data produces a mean of ~0.50.

Planned fix

Replace the broken computation with a derivation from transcripts.parquet's per-transcript overlaps_nucleus: uint8 flag, grouped by cell_id (with UNASSIGNED sentinel filtered):

fraction_in_nucleus = sum(overlaps_nucleus) / count(*) per cell_id

Both numerator and denominator come from the same file, guaranteeing values in [0, 1]. The plot function itself (xenium_nucleus_rna_fraction_plot, lines 1906–2031) is untouched — only its data source moves from parse_cells_parquet to parse_transcripts_parquet. I will update CHANGELOG about the value shift.

Other bugs/issues discovered (out of scope for this PR)

During verification we found that on single-sample Xenium reports, the plugin silently skips four cell-related density sections. This is pre-existing and unrelated to the nuclei-per-cell feature — flagging it here for a follow-up issue.

Observed behavior (terminal log from a single-sample run of unmodified v1.0.2):

xenium_extra | Skipping cell area density plot - using pre-calculated statistics. Density plots require raw data.
xenium_extra | Skipping nucleus RNA fraction density plot - using pre-calculated statistics. Density plots require raw data.
xenium_extra | Skipping nucleus-to-cell area ratio density plot - using pre-calculated statistics. Density plots require raw data.
xenium_extra | Skipping density plot for transcripts per cell - using pre-calculated statistics. Density plots require raw data.

Root cause:

All four follow the same single-vs-multi-sample router pattern. The single-sample branch (create_single_sample*_density) requires raw per-cell *_values lists to compute a KDE density curve. But parse_cells_parquet deliberately stores only summary *_box_stats dictionaries (memory-saving design).

With only summary stats available and no raw values, the helper returns None and the section disappears.

Single-sample run: you lose 4 cell-related density sections (Cell Area Distribution, Fraction of Transcripts in Nucleus, Nucleus to Cell Area, Transcripts per Cell). The report effectively shows transcript-side QC only, plus segmentation from the core MultiQC Xenium module.

Multi-sample run: all 4 sections render — but as per-sample box plots, not density curves. So the visualization style differs from what the helptext (which describes "density plots for single sample, box plots for multiple") implies.