From 42e28232cb4b8cbcb941965b12d8fa2df0fd43cf Mon Sep 17 00:00:00 2001 From: iback Date: Fri, 13 Nov 2026 14:25:49 +0000 Subject: [PATCH] feat: z-score the SynthSeg synthesis on request with zscore_output With SynthSeg's default `normalise=True` the synthesis is min-max scaled to [0, 1]. The real training patches it is mixed with are z-scored, so the synthetic samples reach every later transform at about a fifth of the spread of a real one: measured 0.16-0.20 against 0.86-0.91 on two Dixon datasets. Transforms that work in absolute units then act on them at several times their strength on real samples. RandomGaussianNoiseGPU draws its std from U(0, std), and with the paper config's std 1.0 the synthesis was buried under noise in 16 of 20 firings in a measured sample (label boundaries no longer stood out from the background gradient). `zscore_output=True` standardises each synthesised sample over its patch before it replaces the image. It draws no random numbers, so the same seed gives the same synthesis up to that rescale. Default False keeps the [0, 1] output and every shipped config's seeded result. Co-Authored-By: Claude Opus 5.5 --- smauglab/configs/all_augmentations.json | 3 +- smauglab/transforms/synthseg/transforms.py | 12 ++++ unit_tests/test_synthseg_zscore_output.py | 64 ++++++++++++++++++++++ 3 files changed, 78 insertions(+), 1 deletion(-) create mode 100644 unit_tests/test_synthseg_zscore_output.py diff --git a/smauglab/configs/all_augmentations.json b/smauglab/configs/all_augmentations.json index 8be9b9b..7a68c82 100644 --- a/smauglab/configs/all_augmentations.json +++ b/smauglab/configs/all_augmentations.json @@ -82,7 +82,8 @@ "shearing_bounds": 0.012, "svf_integration_steps": 7, "thickness": null, - "translation_bounds": false + "translation_bounds": false, + "zscore_output": false }, "RandomPaletteGPU": { "alpha_magnitude_range": [ diff --git a/smauglab/transforms/synthseg/transforms.py b/smauglab/transforms/synthseg/transforms.py index aa14f5e..1486f01 100644 --- a/smauglab/transforms/synthseg/transforms.py +++ b/smauglab/transforms/synthseg/transforms.py @@ -102,6 +102,13 @@ class RandomSynthSegGPU(ImageOnlyTransform): Args: apply_to_channel: image channels to overwrite with the synthesis. + zscore_output: z-score each synthesised sample over its whole patch before it + replaces the image. With ``normalise=True`` (SynthSeg's default) the synthesis + is min-max scaled to ``[0, 1]``, about a fifth of the spread of a z-scored + training patch, and every later transform that works in absolute units -- + ``RandomGaussianNoiseGPU`` draws its std from ``U(0, std)`` -- then acts on the + synthetic samples at five times the strength it has on the real ones. + Default False, which keeps the ``[0, 1]`` output. p: application probability (Kornia convention). Remaining kwargs are forwarded to :class:`SynthSegGenerator` (e.g. ``n_channels``, ``prior_means``, ``bias_field_std``, ``gamma_std``, @@ -112,6 +119,7 @@ def __init__( self, apply_to_channel: list[int] | None = None, same_on_batch: bool = False, + zscore_output: bool = False, p: float = 0.5, p_batch: float = 1.0, keepdim: bool = True, @@ -119,6 +127,7 @@ def __init__( ) -> None: super().__init__(p=p, p_batch=p_batch, same_on_batch=same_on_batch, keepdim=keepdim) self.apply_to_channel = apply_to_channel if apply_to_channel is not None else [0] + self.zscore_output = zscore_output gen_kwargs = _filter_generator_kwargs(kwargs) # Intensity-only: never deform/flip internally (geometry comes from the # surrounding sequential, which also transports the mask). @@ -143,6 +152,9 @@ def apply_transform(self, input: Tensor, params: dict[str, Tensor], flags: dict[ if torch.isnan(x).any() or torch.isinf(x).any(): print(f"Warning nan: {self.__class__.__name__}", flush=True) continue + if self.zscore_output: + dims = tuple(range(1, x.dim())) + x = (x - x.mean(dim=dims, keepdim=True)) / x.std(dim=dims, keepdim=True).clamp_min(1e-8) input[:, c] = x return input diff --git a/unit_tests/test_synthseg_zscore_output.py b/unit_tests/test_synthseg_zscore_output.py new file mode 100644 index 0000000..28dfc79 --- /dev/null +++ b/unit_tests/test_synthseg_zscore_output.py @@ -0,0 +1,64 @@ +"""`RandomSynthSegGPU(zscore_output=True)` hands on a z-scored synthesis. + +With SynthSeg's default `normalise=True` the synthesis is min-max scaled to `[0, 1]`, +while the real patches it is mixed with are z-scored. Every later transform that works +in absolute units then acts on the synthetic samples at several times its strength on +the real ones; `RandomGaussianNoiseGPU`, whose std is drawn from `U(0, std)`, buries a +`[0, 1]` image under noise in most of its firings. `zscore_output` rescales the synthesis +per sample, and does nothing else: it draws no random numbers, so the same seed gives +the same synthesis up to that rescale. +""" + +from __future__ import annotations + +import torch + +from smauglab.registry import Backend, accepted_params, get +from smauglab.transforms.synthseg.transforms import RandomSynthSegGPU +from unit_tests.helpers import SmaugLabTestCase + +SHAPE = (3, 1, 16, 16, 16) + + +def inputs() -> tuple[torch.Tensor, torch.Tensor]: + labels = torch.zeros(*SHAPE) + labels[:, :, 4:12, 4:12, 4:12] = 1 + labels[:, :, 6:10, 6:10, 6:10] = 2 + return torch.randn(*SHAPE), labels + + +def synthesise(zscore_output: bool, seed: int = 0) -> torch.Tensor: + transform = RandomSynthSegGPU(p=1.0, n_channels=1, zscore_output=zscore_output) + image, labels = inputs() + torch.manual_seed(seed) + return transform(image.clone(), params={"seg": labels}) + + +def per_sample(x: torch.Tensor, reduce) -> torch.Tensor: + return reduce(x.reshape(x.shape[0], -1), dim=1) + + +class TestSynthSegZscoreOutput(SmaugLabTestCase): + def test_the_default_still_returns_the_unit_interval(self): + out = synthesise(zscore_output=False) + self.assertGreaterEqual(float(out.min()), 0.0) + self.assertLessEqual(float(out.max()), 1.0) + + def test_each_sample_is_zscored(self): + out = synthesise(zscore_output=True) + torch.testing.assert_close(per_sample(out, torch.mean), torch.zeros(SHAPE[0]), atol=1e-5, rtol=0) + torch.testing.assert_close(per_sample(out, torch.std), torch.ones(SHAPE[0]), atol=1e-5, rtol=0) + + def test_it_is_only_a_rescale_of_the_same_synthesis(self): + """No extra random draw: the same seed gives the same image, standardised.""" + for seed in range(3): + with self.subTest(seed=seed): + plain = synthesise(zscore_output=False, seed=seed) + scored = synthesise(zscore_output=True, seed=seed) + flat = plain.reshape(SHAPE[0], -1) + expected = (flat - flat.mean(1, keepdim=True)) / flat.std(1, keepdim=True) + torch.testing.assert_close(scored.reshape(SHAPE[0], -1), expected, atol=1e-5, rtol=1e-5) + + def test_the_config_surface_accepts_it(self): + entry = get("RandomSynthSegGPU", Backend.GPU) + self.assertIn("zscore_output", accepted_params(entry))