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))