BrillouinROI

BrillouinROI is a Python script for region-of-interest based analysis of Brillouin microscopy maps. The tool enables manual or semi-automated ROI definition, pixel-level value extraction, and verification of pixel-to-value mapping from Brillouin images. It was developed to support quantitative analysis of mechanical properties in plant tissues, with particular attention to reproducibility and avoidance of pseudo-replication. The script outputs per-ROI distributions and summary statistics suitable for downstream statistical analysis and figure generation. Although developed for plant samples, the workflow is applicable to other Brillouin microscopy datasets with similar image formats. v3.0 — BrillouinROI Adds an intensity channel, per-pixel export deduplication, independent shift/width normalisation, and Z/depth stack handling. This release contains breaking changes. Read the two items below before upgrading; results from v1 and v2 are not directly comparable in all cases. Breaking changes Co-registration direction reversed. `warp_bf_to_matrix` is replaced by `warp_matrix_to_bf`. v1 warped the brightfield onto the Brillouin grid, leaving spectral values untouched. v2 warps the Brillouin map onto thebrightfield frame, so values sampled through the affine warp are bilinearly interpolated. If you need untouched acquisition pixels, draw on the shift, width, or intensity map, where no warp is applied to the analysed data. Out-of-field pixels are now filled with NaN instead of 0.0 and are excluded by the validity filter, so they no longer contribute a spurious 0 GHz. Line drawing mode removed.`line_to_mask` (Bresenham) is deleted; the mode radio now offers Brush, Pick, Polygon, Ellipse, Ellipse Ring. Sidecars containing Line ROIs will not reproduce those ROIs. Added Brillouin intensity channel. Auto-detected alongside shift and width. Usable as a visual guide for ROI placement, with an independent colour scale and outlier filtering. Intensity is excluded from every exported data file and statistical report. Four draw targets (was two): shift map, width map, intensity, brightfield. A single ROI mask is shared across all layers. One value per Brillouin source pixel. ROIs are collapsed to unique source pixels before any value is read, so a repeated brush path or an upsampled map no longer inflates n. Per-pixel exports gain `row`, `col`, `x_center_px`,`y_center_px`. Independent shift and width normalisation, each with modes `none`, `water`, `internal_roi`. Default: water for shift, none for width. Internal mode uses an ROI named `internal_control`, `normalization_control`,`normalisation_control`, `reference_roi`, or `reference_region`; if the mode is selected and no such ROI exists, the condition is recorded as `internal_control_missing` and values are left un-normalised. Z/depth stacks. Files matching `*_slice-N.csv` load as separate layers sharing the stack brightfield. Exports gain `z_slice` and `z_layer`, carriedinto normality checks, tests, and boxplots. A `Z Link` button (off by default) copies ROIs, water ROI, and metadata to the next slice of the same stack. Unfiltered exports.Every ROI, water, and summary file is written a second time with an `_all_data` suffix and no outlier filtering. Six ROI metadata fields (was two): ROI label, line name, treatment,sample ID, image ID, notes. Labels are free text and sample-agnostic. Pixel-validity audit columns:`n_pixels_selected`, `n_shift_valid_raw`, `n_width_valid_raw`, `n_shift_width_paired`. CLI: `--shift-normalization {none,water,internal_roi}`, `--width-normalization {none,water,internal_roi}`. Changed Alignment moved from an in-figure phase to a separate `Tk` window (`Improve Alignment`). ROI drawing is suspended automatically while the Matplotlib zoom or pan tool is active, and resumes when navigation is switched off. ROI markers are drawn at pixel centres so selections can be verified against the overlay Unchanged Outlier methods and defaults (IQR k=3, Z-score 3, MAD 3.5, percentile 1/1); BNI and its propagated uncertainty; the two-group test decision tree (paired t-test, Wilcoxon signed-rank, Welch t-test, Mann-Whitney U); JSON sidecar persistence and batch reprocessing. Requirements Python ≥ 3.9 · NumPy · SciPy · pandas · Matplotlib · Pillow · openpyxl (optional, for Excel export)