Add subject-level visual QC outputs (histogram, segmentation, z-profile, object stats, ROI summaries, vessel overlays)

[Copilot]

Adds a new qc.smk rules module that generates per-subject, per-channel PNG quality-control figures covering the major QC categories described in the issue. All outputs land in the qc BIDS datatype directory.

New rules (spimquant/workflow/rules/qc.smk)

Rule	Inputs	Output
qc_intensity_histogram	Raw OME-Zarr (per stain, at registration level)	Linear + log histogram, CDF, saturation fraction; linear panel uses percentile-based axis bounds
qc_segmentation_overview	OME-Zarr SPIM + seg mask.ozx at segmentation level	3-orientation slice montage (5 slices) + MIP with overlay; near-isotropic downsampling and aspect ratio via ZarrNii.get_zooms()
qc_vessels_overview	OME-Zarr SPIM + vessel mask.ozx at segmentation level	Same whole-brain slice montage + MIP for vessel masks (vesselslices.png)
qc_segmentation_roi_zoom	OME-Zarr SPIM + seg mask.ozx + atlas dseg NIfTI (subject space) + label TSV	Per-atlas-region full-resolution crops via ZarrNii/ZarrNiiAtlas: best axial slice with overlay (roimontage.png)
qc_vessels_roi_zoom	OME-Zarr SPIM + vessel mask.ozx + atlas dseg NIfTI (subject space) + label TSV	Same full-resolution ROI zoom montage for vessel masks (vesselroimontage.png)
qc_zprofile	SPIM NIfTI + field-fraction NIfTI	Per-Z-slice mean intensity (±1 SD) and field-fraction profile
qc_objectstats	Aggregated regionprops parquet	Volume distribution, log-volume, equivalent-radius, summary stats
qc_roi_summary	Merged segstats TSV + atlas label TSV	Top-20 region bar charts for field fraction, count, and density; background (atlas label 0) excluded

Workflow integration (Snakefile)

• New all_qc target rule — intensity histograms always; segmentation-dependent outputs gated on do_seg; vessel outputs gated on do_vessels
• rules.all_qc.input added to all_participant so QC runs by default
• include: "rules/qc.smk" appended alongside existing rule includes

Scripts (spimquant/workflow/scripts/)

Six new scripts following the established snakemake-script pattern — access inputs/outputs/wildcards/params via the snakemake object, use matplotlib with the agg backend, and leverage zarrnii/pandas as appropriate:

• qc_intensity_histogram.py — linear-scale histogram panel uses percentile-based axis bounds: x-axis capped at the 99th-percentile intensity (+ 5 % headroom) and y-axis capped at the tallest bar within that visible range, preventing long empty tails and background spikes from obscuring the distribution body; log-scale and CDF panels retain full-range bounds
• qc_segmentation_overview.py — loads SPIM and mask via ZarrNii.from_ome_zarr() with downsample_near_isotropic=True; uses get_zooms() for physically correct imshow aspect ratios; also used by qc_vessels_overview
• qc_segmentation_roi_zoom.py — uses ZarrNii and ZarrNiiAtlas to load full-resolution data; crops to each atlas ROI's bounding box via atlas.get_region_bounding_box() and crop_centered(); renders a 5-column grid montage; also used by qc_vessels_roi_zoom
• qc_zprofile.py
• qc_objectstats.py
• qc_roi_summary.py — drops atlas label 0 (background) immediately after loading the segstats TSV so out-of-brain regions never appear in the summary bar charts

[akhanf]

@copilot: the segslice overlay needs to have the aspect ratio scaled accordingly by voxel dimensions, or use the downsample_near_isotropic arg with from_ome_zarr..

also, need to have another output png similar to this, but zoomed in and cropped, so full detail can be seen, ideally montage across multiple ROIs.

this visualization can be done identically for the vessels mask as well, i.e. not just the stains_for_seg

[Copilot]

@copilot: the segslice overlay needs to have the aspect ratio scaled accordingly by voxel dimensions, or use the downsample_near_isotropic arg with from_ome_zarr..

also, need to have another outpu...

Addressed in commit 1cd0826:

1. Aspect ratio: Added _slice_aspect(zooms, step_axis) in qc_segmentation_overview.py that reads voxel dimensions from the NIfTI header (header.get_zooms()) and computes the physically correct imshow aspect ratio for each orientation (axial: dy/dx, coronal: dz/dx, sagittal: dz/dy). Applied to both slice panels and MIP columns.

2. Zoomed ROI montage: New qc_segmentation_roi_zoom.py + qc_segmentation_roi_zoom rule (output: roimontage.png). Crops SPIM and field-fraction to each atlas region's bounding box (from the parcellation in subject space), picks the Z-slice with the most field-fraction signal, and lays out all ROIs in a 5-column grid with correct aspect ratio.

3. Vessel support: New qc_vessels_overview rule (same qc_segmentation_overview.py script, reads datatype="vessels" fieldfrac → vesselslices.png) and qc_vessels_roi_zoom rule (same qc_segmentation_roi_zoom.py script → vesselroimontage.png). Both are added to all_qc, gated on do_vessels.

[akhanf]

@copilot I have modified the qc_segmentaton_roi_zoom to make use of ZarrNii and ZarrNiiAtlas so that full-res images can be generated. update the rest of the high-res plotting functions to also use ZarrNii and ZarrNii atlas, including the vessel segmentaiton plotting.

[Copilot]

@copilot I have modified the qc_segmentaton_roi_zoom to make use of ZarrNii and ZarrNiiAtlas so that full-res images can be generated. update the rest of the high-res plotting functions to also use Za...

Done in commit d489341.

• qc_segmentation_overview.py: Replaced nibabel NIfTI loading with ZarrNii.from_ome_zarr() using downsample_near_isotropic=True for the SPIM and the same for the mask. Voxel spacings come from get_zooms() instead of the NIfTI header.

• qc_segmentation_overview + qc_vessels_overview rules: Inputs changed from SPIM NIfTI + fieldfrac NIfTI to inputs["spim"].path (OME-Zarr) + mask.ozx at segmentation_level. Added level, mask_level (registration_level - segmentation_level, same arithmetic as fieldfrac.py), and zarrnii_kwargs params.

• qc_vessels_roi_zoom rule: Updated to the same ZarrNii pattern as qc_segmentation_roi_zoom — uses inputs["spim"].path (OME-Zarr) + datatype="vessels" mask.ozx + dseg_nii NIfTI + label_tsv. Both rules now share qc_segmentation_roi_zoom.py.

[akhanf]

@copilot: one final edit, the intensity histograms that are linearly scaled in y have the max x and max y set too high perhaps use a percentile to set the bounds instead.

[Copilot]

@copilot: one final edit, the intensity histograms that are linearly scaled in y have the max x and max y set too high perhaps use a percentile to set the bounds instead.

Done in commit 544b60e.

For the linear histogram panel:

• X-axis: now capped at p99_val * 1.05 (99th percentile intensity + 5% headroom) instead of the last non-zero bin, eliminating the long empty tail
• Y-axis: now capped at the tallest bar within that visible x range * 1.05, so the body of the distribution fills the panel rather than being flattened by a background spike

The log-scale and CDF panels keep the existing disp_max (last non-zero bin) so the full distribution is still visible there.

[akhanf]

@copilot: final fix, for any instance-level analyses (e.g. roisummary etc) always start by dropping all the instances with atlas label 0 (background), as these are outside the brain and shouldn't be used

[Copilot]

@copilot: final fix, for any instance-level analyses (e.g. roisummary etc) always start by dropping all the instances with atlas label 0 (background), as these are outside the brain and shouldn't be u...

Done in commit 9aa06df. In qc_roi_summary.py, rows with index == 0 (background) are now dropped immediately after loading the segstats TSV, before the label-name merge and any plotting, so background regions never appear in the bar charts.