From 86ea1503b6503570fefa072e535dfb6214d3f622 Mon Sep 17 00:00:00 2001 From: iback Date: Fri, 13 Nov 2026 14:25:50 +0000 Subject: [PATCH 1/2] feat: strength ranges for the five elementwise TAs, and bounds for the unsharp mask Log1p, Sqrt, Sin, Exp and Sigmoid min-max scale each sample to [0, 1], apply a fixed function and, with retain_stats, restore mean and std. Only the function's curvature on [0, 1] survives that, and it is small: the share of output variance a linear map of the input cannot explain is 0.8%, 4.0%, 0.5%, 1.6% and 0.1% on a uniform input, and 0.5%, 1.9-3.0%, 0.2%, 1.0% and 0.04% measured on real spine MR and CT patches. A gamma of 0.7 or 1.5 is already 1.2-2.0%. At the paper config's p=0.1 each, 41% of samples get at least one of the five and are effectively unchanged by it. Each now takes an optional range that draws a stronger member of its family per sample (once with same_on_batch): * RandomLog1pGPU(scale_range) log(1 + k*x) * RandomSqrtGPU(exponent_range) x**g * RandomSinGPU(frequency_range) sin(2*pi*f*x + phi), phi ~ U(0, 2*pi) * RandomExpGPU(rate_range) exp(k*x) * RandomSigmoidGPU(slope_range, center_quantile_range) sigmoid(k*(x - c)), c the sample's q-quantile The sigmoid centre is a quantile because the min-max scaling is set by the extremes: with a bright tail the bulk of the tissue sits in the bottom fifth of [0, 1], where a fixed centre would saturate it. RandomUnsharpMaskGPU drew its per-axis sigma from U(0, sigma) onto a fixed 3-wide kernel and its amount from U(0, unsharp_amount), which measured at 0.01-0.9% nonlinear share and a gradient-magnitude correlation of 0.996 with the input. It now takes `sigma_min`, `amount_min` and `kernel_size` (None sizes the kernel 2*ceil(3*sigma)+1). Every default is the old transform: the leaves fall through to the fixed function and draw nothing, and the unsharp draws reduce to `rand * x` exactly. Co-Authored-By: Claude Opus 5.5 --- smauglab/configs/all_augmentations.json | 16 +- smauglab/transforms/gpu/contrast.py | 303 +++++++++++++++++++++++- unit_tests/test_function_strength.py | 183 ++++++++++++++ 3 files changed, 488 insertions(+), 14 deletions(-) create mode 100644 unit_tests/test_function_strength.py diff --git a/smauglab/configs/all_augmentations.json b/smauglab/configs/all_augmentations.json index 8be9b9b..c370f34 100644 --- a/smauglab/configs/all_augmentations.json +++ b/smauglab/configs/all_augmentations.json @@ -258,11 +258,13 @@ "same_on_batch": false }, "RandomUnsharpMaskGPU": { + "amount_min": 0.0, "apply_to_channel": [ 0 ], "in_seg": 0.0, "keepdim": true, + "kernel_size": 3, "mix_in_out": false, "mix_prob": 0.0, "out_seg": 0.0, @@ -271,6 +273,7 @@ "retain_stats": false, "same_on_batch": false, "sigma": 1.0, + "sigma_min": 0.0, "unsharp_amount": 1.5 }, "RandomRandConvGPU": { @@ -414,12 +417,14 @@ "p": 1.0, "p_batch": 1.0, "retain_stats": false, - "same_on_batch": false + "same_on_batch": false, + "scale_range": null }, "RandomSqrtGPU": { "apply_to_channel": [ 0 ], + "exponent_range": null, "in_seg": 0.0, "keepdim": true, "mix_in_out": false, @@ -433,6 +438,7 @@ "apply_to_channel": [ 0 ], + "frequency_range": null, "in_seg": 0.0, "keepdim": true, "mix_in_out": false, @@ -452,6 +458,7 @@ "out_seg": 0.0, "p": 1.0, "p_batch": 1.0, + "rate_range": null, "retain_stats": false, "same_on_batch": false }, @@ -459,6 +466,10 @@ "apply_to_channel": [ 0 ], + "center_quantile_range": [ + 0.1, + 0.9 + ], "in_seg": 0.0, "keepdim": true, "mix_in_out": false, @@ -466,7 +477,8 @@ "p": 1.0, "p_batch": 1.0, "retain_stats": false, - "same_on_batch": false + "same_on_batch": false, + "slope_range": null }, "RandomLowResTransformGPU": { "keepdim": true, diff --git a/smauglab/transforms/gpu/contrast.py b/smauglab/transforms/gpu/contrast.py index ef6c3c8..70f5ec9 100644 --- a/smauglab/transforms/gpu/contrast.py +++ b/smauglab/transforms/gpu/contrast.py @@ -257,6 +257,12 @@ class _RandomConvBaseGPU(ImageOnlyTransform): absolute (bool): If True, take the absolute value of the result. Scharr only. sigma (float): Gaussian width. GaussianBlur and UnsharpMask only. unsharp_amount (float): Strength of the unsharp mask. UnsharpMask only. + sigma_min (float): Lower bound of the per-axis blur sigma, drawn from + `U(sigma_min, sigma)`. UnsharpMask only. + amount_min (float): Lower bound of the unsharp amount, drawn from + `U(amount_min, unsharp_amount)`. UnsharpMask only. + kernel_size (int | None): Width of the blur kernel; None sizes it for the largest + sigma the range allows, `2 * ceil(3 * sigma) + 1`. UnsharpMask only. kernel_sizes (list of int): Multi-scale kernel sizes to draw from. RandConv only. mix_prob (float): Probability of blending the result back with the original. retain_stats (bool): If True, restore the original mean and std afterwards. @@ -282,6 +288,9 @@ def __init__( sigma: float = 1.0, unsharp_amount: float = 1.0, kernel_sizes: Sequence[int] = (1, 3, 5, 7), + sigma_min: float = 0.0, + amount_min: float = 0.0, + kernel_size: int | None = 3, mix_prob: float = 0.0, p: float = 1.0, p_batch: float = 1.0, @@ -301,6 +310,9 @@ def __init__( self.mix_in_out = mix_in_out self.unsharp_amount = unsharp_amount self.kernel_sizes = kernel_sizes + self.sigma_min = sigma_min + self.amount_min = amount_min + self.kernel_size = kernel_size if kernel_size is not None else 2 * math.ceil(3 * sigma) + 1 self.mix_prob = mix_prob def get_kernel(self, device: torch.device) -> Union[Tensor, list[Tensor]]: @@ -318,9 +330,10 @@ def get_kernel(self, device: torch.device) -> Union[Tensor, list[Tensor]]: kernel = gaussian_kernel3d(kernel_size, sigma, torch.float32, device) elif self.kernel_type == "UnsharpMask": # For unsharp masking we use a Gaussian blur kernel; amount is applied in apply_transform. - sigma = torch.rand(3, device=device) * self.sigma - kernel_size = 3 - kernel = gaussian_kernel3d(kernel_size, sigma, torch.float32, device) + # With the defaults (sigma_min 0, kernel_size 3) this is the old `rand * sigma` + # on a 3-wide kernel exactly: `* (sigma - 0.0) + 0.0` is exact in IEEE-754. + sigma = torch.rand(3, device=device) * (self.sigma - self.sigma_min) + self.sigma_min + kernel = gaussian_kernel3d(self.kernel_size, sigma, torch.float32, device) elif self.kernel_type == "RandConv": # choose random odd kernel size e.g. [1,3,5,7] k = int(shared_choice(self.kernel_sizes)) # define kernel_sizes in __init__ @@ -384,11 +397,14 @@ def apply_transform(self, input: Tensor, params: dict[str, Tensor], flags: dict[ if self.same_on_batch: assert isinstance(kernel, Tensor) blurred = apply_convolution(channel_data, kernel, dim=3) - unsharp_amount = torch.rand(1, device=input.device) * self.unsharp_amount + unsharp_amount = torch.rand(1, device=input.device) * (self.unsharp_amount - self.amount_min) + self.amount_min else: blurred = apply_convolution_per_sample(channel_data, self._per_sample_kernels(channel_data.shape[0], input.device)) amount_shape = [channel_data.shape[0]] + [1] * (channel_data.dim() - 1) - unsharp_amount = torch.rand(channel_data.shape[0], device=input.device).view(amount_shape) * self.unsharp_amount + unsharp_amount = ( + torch.rand(channel_data.shape[0], device=input.device).view(amount_shape) * (self.unsharp_amount - self.amount_min) + + self.amount_min + ) mask = channel_data - blurred x = channel_data + unsharp_amount * mask elif self.kernel_type == "Scharr": @@ -557,12 +573,22 @@ def __init__( group=AugType.TA, ) class RandomUnsharpMaskGPU(_RandomConvBaseGPU): - """Unsharp masking: sharpen by subtracting a blurred copy.""" + """Unsharp masking: sharpen by subtracting a blurred copy. + + The blur sigma is drawn per axis from `U(sigma_min, sigma)` and the amount from + `U(amount_min, unsharp_amount)`. The defaults (`sigma_min=0`, `amount_min=0`, + `kernel_size=3`) are the historical draws, and they make a weak transform: a 3-wide + kernel truncates any sigma above about 0.5, and a sigma near 0 blurs nothing, so the + unsharp mask is close to zero. `kernel_size=None` sizes the kernel for `sigma`. + """ def __init__( self, sigma: float = 1.0, unsharp_amount: float = 1.5, + sigma_min: float = 0.0, + amount_min: float = 0.0, + kernel_size: int | None = 3, mix_prob: float = 0.0, apply_to_channel: Sequence[int] = (0,), same_on_batch: bool = False, @@ -574,10 +600,19 @@ def __init__( p_batch: float = 1.0, keepdim: bool = True, ) -> None: + if not 0.0 <= sigma_min <= sigma: + raise ValueError(f"need 0 <= sigma_min <= sigma, got sigma_min={sigma_min}, sigma={sigma}") + if not 0.0 <= amount_min <= unsharp_amount: + raise ValueError(f"need 0 <= amount_min <= unsharp_amount, got {amount_min} and {unsharp_amount}") + if kernel_size is not None and (kernel_size < 1 or kernel_size % 2 == 0): + raise ValueError(f"kernel_size must be a positive odd integer or None, got {kernel_size}") super().__init__( kernel_type="UnsharpMask", sigma=sigma, unsharp_amount=unsharp_amount, + sigma_min=sigma_min, + amount_min=amount_min, + kernel_size=kernel_size, mix_prob=mix_prob, apply_to_channel=apply_to_channel, same_on_batch=same_on_batch, @@ -1161,7 +1196,7 @@ def apply_transform(self, input: Tensor, params: dict[str, Tensor], flags: dict[ x = (x - x_min) / (x_max - x_min + 0.00001) # Apply function - x = self.func(x) + x = self._apply_function(x) if self.retain_stats: x = _restore_stats(x, stats) @@ -1172,6 +1207,27 @@ def apply_transform(self, input: Tensor, params: dict[str, Tensor], flags: dict[ return input + def _apply_function(self, x: Tensor) -> Tensor: + """`func` on the `[0, 1]`-normalised `[N, ...spatial]` channel. Leaves with a strength range override this.""" + return self.func(x) + + +def _uniform_like(bounds: Sequence[float], x: Tensor, same_on_batch: bool) -> Tensor: + """`U(lo, hi)`, one draw per sample (one for the batch with `same_on_batch`), shaped to broadcast over `x`.""" + lo, hi = float(bounds[0]), float(bounds[1]) + n = 1 if same_on_batch else x.shape[0] + u = torch.rand(n, device=x.device, dtype=x.dtype) * (hi - lo) + lo + return u.view(-1, *([1] * (x.dim() - 1))) + + +def _check_range(name: str, bounds: Sequence[float] | None, lowest: float | None = None) -> None: + if bounds is None: + return + if len(bounds) != 2 or float(bounds[0]) > float(bounds[1]): + raise ValueError(f"{name} must be [lo, hi] with lo <= hi, got {bounds}") + if lowest is not None and float(bounds[0]) < lowest: + raise ValueError(f"{name} must start at >= {lowest}, got {bounds}") + # One class per elementwise function. `func` was a callable parameter, which no JSON # config can express; the old ladder worked around that by expanding a single @@ -1228,10 +1284,50 @@ def __init__( group=AugType.TA, ) class RandomLog1pGPU(_RandomNamedFunctionGPU): - """Apply log(1 + x).""" + """Apply log(1 + x), or log(1 + k*x) with k drawn from `scale_range`. + + The transform min-max scales each sample to `[0, 1]`, applies the function and, with + `retain_stats`, restores mean and std, so only the function's curvature on `[0, 1]` + survives. For the fixed function that is small: the share of the output variance a + linear map of the input cannot explain is 0.8% on a uniform input. Setting the + range draws a stronger member of the same family per sample; None keeps the fixed + function and draws nothing. `[1, 100]` reaches 15%. + """ function = staticmethod(_log1p) + def __init__( + self, + scale_range: Sequence[float] | None = None, + apply_to_channel: Sequence[int] = (0,), + retain_stats: bool = False, + same_on_batch: bool = False, + in_seg: float = 0.0, + out_seg: float = 0.0, + mix_in_out: bool = False, + p: float = 1.0, + p_batch: float = 1.0, + keepdim: bool = True, + ) -> None: + _check_range("scale_range", scale_range, lowest=0.0) + super().__init__( + apply_to_channel=apply_to_channel, + retain_stats=retain_stats, + same_on_batch=same_on_batch, + in_seg=in_seg, + out_seg=out_seg, + mix_in_out=mix_in_out, + p=p, + p_batch=p_batch, + keepdim=keepdim, + ) + self.scale_range = scale_range + + def _apply_function(self, x: Tensor) -> Tensor: + if self.scale_range is None: + return self.func(x) + return torch.log(1 + _uniform_like(self.scale_range, x, self.same_on_batch) * x) + @register( aug_id=AugId.FUNC_SQRT, @@ -1239,10 +1335,50 @@ class RandomLog1pGPU(_RandomNamedFunctionGPU): group=AugType.TA, ) class RandomSqrtGPU(_RandomNamedFunctionGPU): - """Apply sqrt(x).""" + """Apply sqrt(x), or x**g with the exponent g drawn from `exponent_range`. + + The transform min-max scales each sample to `[0, 1]`, applies the function and, with + `retain_stats`, restores mean and std, so only the function's curvature on `[0, 1]` + survives. For the fixed function that is small: the share of the output variance a + linear map of the input cannot explain is 4.0% on a uniform input. Setting the + range draws a stronger member of the same family per sample; None keeps the fixed + function and draws nothing. Smaller exponents are stronger. + """ function = staticmethod(torch.sqrt) + def __init__( + self, + exponent_range: Sequence[float] | None = None, + apply_to_channel: Sequence[int] = (0,), + retain_stats: bool = False, + same_on_batch: bool = False, + in_seg: float = 0.0, + out_seg: float = 0.0, + mix_in_out: bool = False, + p: float = 1.0, + p_batch: float = 1.0, + keepdim: bool = True, + ) -> None: + _check_range("exponent_range", exponent_range, lowest=0.0) + super().__init__( + apply_to_channel=apply_to_channel, + retain_stats=retain_stats, + same_on_batch=same_on_batch, + in_seg=in_seg, + out_seg=out_seg, + mix_in_out=mix_in_out, + p=p, + p_batch=p_batch, + keepdim=keepdim, + ) + self.exponent_range = exponent_range + + def _apply_function(self, x: Tensor) -> Tensor: + if self.exponent_range is None: + return self.func(x) + return torch.pow(x, _uniform_like(self.exponent_range, x, self.same_on_batch)) + @register( aug_id=AugId.FUNC_SIN, @@ -1250,10 +1386,55 @@ class RandomSqrtGPU(_RandomNamedFunctionGPU): group=AugType.TA, ) class RandomSinGPU(_RandomNamedFunctionGPU): - """Apply sin(x).""" + """Apply sin(x), or sin(2*pi*f*x + phi) with f drawn from `frequency_range`. + + The transform min-max scales each sample to `[0, 1]`, applies the function and, with + `retain_stats`, restores mean and std, so only the function's curvature on `[0, 1]` + survives. For the fixed function that is small: the share of the output variance a + linear map of the input cannot explain is 0.5% on a uniform input. Setting the + range draws a stronger member of the same family per sample; None keeps the fixed + function and draws nothing. + `f` counts cycles over the normalised range and the phase `phi` is drawn from + `U(0, 2*pi)`, so the map can rise, fall or fold: from about a quarter cycle up it is + non-monotonic, which swaps the order of some tissue intensities. + """ function = staticmethod(torch.sin) + def __init__( + self, + frequency_range: Sequence[float] | None = None, + apply_to_channel: Sequence[int] = (0,), + retain_stats: bool = False, + same_on_batch: bool = False, + in_seg: float = 0.0, + out_seg: float = 0.0, + mix_in_out: bool = False, + p: float = 1.0, + p_batch: float = 1.0, + keepdim: bool = True, + ) -> None: + _check_range("frequency_range", frequency_range, lowest=0.0) + super().__init__( + apply_to_channel=apply_to_channel, + retain_stats=retain_stats, + same_on_batch=same_on_batch, + in_seg=in_seg, + out_seg=out_seg, + mix_in_out=mix_in_out, + p=p, + p_batch=p_batch, + keepdim=keepdim, + ) + self.frequency_range = frequency_range + + def _apply_function(self, x: Tensor) -> Tensor: + if self.frequency_range is None: + return self.func(x) + frequency = _uniform_like(self.frequency_range, x, self.same_on_batch) + phase = _uniform_like((0.0, 2 * math.pi), x, self.same_on_batch) + return torch.sin(2 * math.pi * frequency * x + phase) + @register( aug_id=AugId.FUNC_EXP, @@ -1261,10 +1442,50 @@ class RandomSinGPU(_RandomNamedFunctionGPU): group=AugType.TA, ) class RandomExpGPU(_RandomNamedFunctionGPU): - """Apply exp(x).""" + """Apply exp(x), or exp(k*x) with the rate k drawn from `rate_range`. + + The transform min-max scales each sample to `[0, 1]`, applies the function and, with + `retain_stats`, restores mean and std, so only the function's curvature on `[0, 1]` + survives. For the fixed function that is small: the share of the output variance a + linear map of the input cannot explain is 1.6% on a uniform input. Setting the + range draws a stronger member of the same family per sample; None keeps the fixed + function and draws nothing. `[1, 5]` reaches 19% at k=4. + """ function = staticmethod(torch.exp) + def __init__( + self, + rate_range: Sequence[float] | None = None, + apply_to_channel: Sequence[int] = (0,), + retain_stats: bool = False, + same_on_batch: bool = False, + in_seg: float = 0.0, + out_seg: float = 0.0, + mix_in_out: bool = False, + p: float = 1.0, + p_batch: float = 1.0, + keepdim: bool = True, + ) -> None: + _check_range("rate_range", rate_range, lowest=0.0) + super().__init__( + apply_to_channel=apply_to_channel, + retain_stats=retain_stats, + same_on_batch=same_on_batch, + in_seg=in_seg, + out_seg=out_seg, + mix_in_out=mix_in_out, + p=p, + p_batch=p_batch, + keepdim=keepdim, + ) + self.rate_range = rate_range + + def _apply_function(self, x: Tensor) -> Tensor: + if self.rate_range is None: + return self.func(x) + return torch.exp(_uniform_like(self.rate_range, x, self.same_on_batch) * x) + @register( aug_id=AugId.FUNC_SIGMOID, @@ -1272,10 +1493,68 @@ class RandomExpGPU(_RandomNamedFunctionGPU): group=AugType.TA, ) class RandomSigmoidGPU(_RandomNamedFunctionGPU): - """Apply the logistic sigmoid 1 / (1 + exp(-x)).""" + """Apply the logistic sigmoid 1 / (1 + exp(-x)), or a windowing sigmoid. + + With `slope_range` set, applies 1 / (1 + exp(-k * (x - c))) with the slope k drawn + from `slope_range` and the centre c at the sample's own q-quantile, q drawn from + `center_quantile_range` (default `[0.1, 0.9]`). A quantile rather than a fixed point + in `[0, 1]` because the min-max scaling is set by the extremes: on a patch with a + bright tail (CSF on water-weighted Dixon) the bulk of the tissue sits in the bottom + fifth of the range, and a fixed centre would saturate it. + + The transform min-max scales each sample to `[0, 1]`, applies the function and, with + `retain_stats`, restores mean and std, so only the function's curvature on `[0, 1]` + survives. For the fixed function that is small: the share of the output variance a + linear map of the input cannot explain is 0.1% on a uniform input. Setting the + range draws a stronger member of the same family per sample; None keeps the fixed + function and draws nothing. + """ function = staticmethod(_sigmoid) + def __init__( + self, + slope_range: Sequence[float] | None = None, + center_quantile_range: Sequence[float] = (0.1, 0.9), + apply_to_channel: Sequence[int] = (0,), + retain_stats: bool = False, + same_on_batch: bool = False, + in_seg: float = 0.0, + out_seg: float = 0.0, + mix_in_out: bool = False, + p: float = 1.0, + p_batch: float = 1.0, + keepdim: bool = True, + ) -> None: + _check_range("slope_range", slope_range, lowest=0.0) + _check_range("center_quantile_range", center_quantile_range, lowest=0.0) + if float(center_quantile_range[1]) > 1.0: + raise ValueError(f"center_quantile_range must lie in [0, 1], got {center_quantile_range}") + super().__init__( + apply_to_channel=apply_to_channel, + retain_stats=retain_stats, + same_on_batch=same_on_batch, + in_seg=in_seg, + out_seg=out_seg, + mix_in_out=mix_in_out, + p=p, + p_batch=p_batch, + keepdim=keepdim, + ) + self.slope_range = slope_range + self.center_quantile_range = center_quantile_range + + def _apply_function(self, x: Tensor) -> Tensor: + if self.slope_range is None: + return self.func(x) + slope = _uniform_like(self.slope_range, x, self.same_on_batch) + q = _uniform_like(self.center_quantile_range, x, self.same_on_batch).flatten().expand(x.shape[0]) + flat = x.reshape(x.shape[0], -1) + n = flat.shape[1] + # `kthvalue`, not `torch.quantile`, which refuses inputs above 2**24 elements. + center = torch.stack([flat[b].kthvalue(int(float(q[b]) * (n - 1)) + 1).values for b in range(x.shape[0])]) + return _sigmoid(slope * (x - center.view(-1, *([1] * (x.dim() - 1))))) + ## Inverse transform @register( diff --git a/unit_tests/test_function_strength.py b/unit_tests/test_function_strength.py new file mode 100644 index 0000000..e8c4f04 --- /dev/null +++ b/unit_tests/test_function_strength.py @@ -0,0 +1,183 @@ +"""Strength ranges for the five elementwise TAs and the unsharp mask. + +Each elementwise TA min-max scales a sample to `[0, 1]`, applies a fixed function and, +with `retain_stats`, restores mean and std. Only the function's curvature on `[0, 1]` +survives that, and for log1p, sqrt, sin, exp and the sigmoid it is small: the share of +the output variance that a linear map of the input cannot explain is 0.8%, 4.0%, 0.5%, +1.6% and 0.1% on a uniform input. Each now takes an optional range that draws a +stronger member of its family. The unsharp mask truncated its blur to a 3-wide kernel +and drew sigma and amount from zero up; it now takes lower bounds and a kernel size. + +The defaults must stay the old transforms exactly, including drawing no extra random +numbers, so every shipped config keeps its seeded output. +""" + +from __future__ import annotations + +import math + +import torch + +from smauglab.registry import Backend, accepted_params, get +from smauglab.transforms.gpu.contrast import ( + RandomExpGPU, + RandomLog1pGPU, + RandomSigmoidGPU, + RandomSinGPU, + RandomSqrtGPU, + RandomUnsharpMaskGPU, + _RandomFunctionBaseGPU, + _restore_stats, +) +from unit_tests.helpers import SmaugLabTestCase + +SHAPE = (3, 1, 16, 16, 16) + +#: leaf -> (fixed function, range parameter, a strong range) +LEAVES = { + RandomLog1pGPU: (lambda x: torch.log(1 + x), "scale_range", [50.0, 100.0]), + RandomSqrtGPU: (torch.sqrt, "exponent_range", [0.2, 0.25]), + RandomSinGPU: (torch.sin, "frequency_range", [1.0, 1.5]), + RandomExpGPU: (torch.exp, "rate_range", [4.0, 5.0]), + RandomSigmoidGPU: (lambda x: 1 / (1 + torch.exp(-x)), "slope_range", [15.0, 20.0]), +} + + +def image() -> torch.Tensor: + torch.manual_seed(7) + return torch.rand(*SHAPE) * 3.0 - 1.0 + + +def nonlinear_share(out: torch.Tensor, inp: torch.Tensor) -> torch.Tensor: + """1 - r^2 between output and input, per sample.""" + o = out.reshape(out.shape[0], -1) + i = inp.reshape(inp.shape[0], -1) + o = o - o.mean(1, keepdim=True) + i = i - i.mean(1, keepdim=True) + r = (o * i).sum(1) / (o.norm(dim=1) * i.norm(dim=1)) + return 1 - r**2 + + +class TestDefaultsAreTheOldFunctions(SmaugLabTestCase): + def test_default_output_is_the_fixed_function_with_stats_restored(self): + x = image() + flat = x[:, 0] + lo = flat.amin(dim=(1, 2, 3), keepdim=True) + hi = flat.amax(dim=(1, 2, 3), keepdim=True) + normalised = (flat - lo) / (hi - lo + 0.00001) + stats = (flat.mean(dim=(1, 2, 3)), flat.std(dim=(1, 2, 3))) + for cls, (fixed, _, _) in LEAVES.items(): + with self.subTest(transform=cls.__name__): + out = cls(retain_stats=True, p=1.0)(x.clone()) + expected = _restore_stats(fixed(normalised), stats) + self.assertTrue(torch.equal(out[:, 0], expected)) + + def test_defaults_draw_what_the_generic_base_draws(self): + """Same RNG stream as `_RandomFunctionBaseGPU(func=...)`, the unchanged generic path.""" + x = image() + for cls, (fixed, _, _) in LEAVES.items(): + with self.subTest(transform=cls.__name__): + torch.manual_seed(0) + leaf_out = cls(retain_stats=True, p=0.5)(x.clone()) + after_leaf = torch.rand(4) + torch.manual_seed(0) + base_out = _RandomFunctionBaseGPU(func=fixed, retain_stats=True, p=0.5)(x.clone()) + after_base = torch.rand(4) + self.assertTrue(torch.equal(leaf_out, base_out)) + self.assertTrue(torch.equal(after_leaf, after_base)) + + +class TestRangesStrengthenTheMap(SmaugLabTestCase): + def test_a_strong_range_is_more_nonlinear_than_the_fixed_function(self): + x = image() + for cls, (_, key, strong) in LEAVES.items(): + with self.subTest(transform=cls.__name__): + torch.manual_seed(0) + fixed = nonlinear_share(cls(retain_stats=True, p=1.0)(x.clone()), x) + torch.manual_seed(0) + ranged = nonlinear_share(cls(retain_stats=True, p=1.0, **{key: strong})(x.clone()), x) + self.assertTrue(bool((ranged > fixed).all()), f"{cls.__name__}: {fixed} -> {ranged}") + self.assertTrue(bool(torch.isfinite(ranged).all())) + + def test_draws_are_per_sample_unless_same_on_batch(self): + one = image()[:1] + x = one.repeat(SHAPE[0], 1, 1, 1, 1) # three copies of one sample + for cls, (_, key, strong) in LEAVES.items(): + for same_on_batch in (False, True): + with self.subTest(transform=cls.__name__, same_on_batch=same_on_batch): + torch.manual_seed(0) + out = cls(p=1.0, same_on_batch=same_on_batch, **{key: strong})(x.clone()) + identical = torch.equal(out[0], out[1]) and torch.equal(out[1], out[2]) + self.assertEqual(identical, same_on_batch) + + def test_the_sigmoid_centre_is_the_drawn_quantile(self): + x = image() + sigmoid = RandomSigmoidGPU(p=1.0, slope_range=[1000.0, 1000.0], center_quantile_range=[0.3, 0.3]) + out = sigmoid(x.clone()) + above = (out[:, 0] > 0.5).reshape(SHAPE[0], -1).float().mean(1) + torch.testing.assert_close(above, torch.full((SHAPE[0],), 0.7), atol=0.01, rtol=0) + + def test_sin_is_non_monotonic_above_half_a_cycle(self): + ramp = torch.linspace(0, 1, 4096).view(1, 1, 16, 16, 16) + out = RandomSinGPU(p=1.0, frequency_range=[1.5, 1.5])(ramp.clone()).flatten() + steps = out[1:] - out[:-1] + self.assertTrue(bool((steps > 0).any() and (steps < 0).any())) + + def test_bad_ranges_are_refused(self): + with self.assertRaises(ValueError): + RandomExpGPU(rate_range=[5.0, 1.0]) + with self.assertRaises(ValueError): + RandomSqrtGPU(exponent_range=[-0.5, 0.5]) + with self.assertRaises(ValueError): + RandomSigmoidGPU(slope_range=[4.0, 20.0], center_quantile_range=[0.5, 1.5]) + + +class TestUnsharpMaskKnobs(SmaugLabTestCase): + def test_default_kernel_is_three_wide(self): + self.assertEqual(RandomUnsharpMaskGPU().get_kernel(torch.device("cpu")).shape, (3, 3, 3)) + + def test_none_sizes_the_kernel_for_the_largest_sigma(self): + transform = RandomUnsharpMaskGPU(sigma=1.5, kernel_size=None) + k = 2 * math.ceil(3 * 1.5) + 1 + self.assertEqual(transform.get_kernel(torch.device("cpu")).shape, (k, k, k)) + + def test_sigma_is_drawn_from_the_lower_bound_up(self): + transform = RandomUnsharpMaskGPU(sigma=1.5, sigma_min=1.5, kernel_size=None) + # sigma_min == sigma pins the draw, so the kernel is the fixed Gaussian. + from smauglab.transforms.kernels import gaussian_kernel3d + + expected = gaussian_kernel3d(11, torch.tensor([1.5, 1.5, 1.5]), torch.float32, torch.device("cpu")) + torch.testing.assert_close(transform.get_kernel(torch.device("cpu")), expected) + + def test_a_wider_blur_sharpens_more(self): + x = image() + torch.manual_seed(0) + weak = RandomUnsharpMaskGPU(p=1.0, same_on_batch=True)(x.clone()) + torch.manual_seed(0) + strong = RandomUnsharpMaskGPU( + p=1.0, same_on_batch=True, sigma=1.5, sigma_min=0.5, unsharp_amount=2.0, amount_min=0.5, kernel_size=None + )(x.clone()) + self.assertGreater(float((strong - x).abs().mean()), float((weak - x).abs().mean())) + + def test_bad_bounds_are_refused(self): + with self.assertRaises(ValueError): + RandomUnsharpMaskGPU(sigma=1.0, sigma_min=2.0) + with self.assertRaises(ValueError): + RandomUnsharpMaskGPU(unsharp_amount=1.0, amount_min=2.0) + with self.assertRaises(ValueError): + RandomUnsharpMaskGPU(kernel_size=4) + + +class TestConfigSurface(SmaugLabTestCase): + def test_the_new_parameters_are_accepted(self): + expected = { + "RandomLog1pGPU": {"scale_range"}, + "RandomSqrtGPU": {"exponent_range"}, + "RandomSinGPU": {"frequency_range"}, + "RandomExpGPU": {"rate_range"}, + "RandomSigmoidGPU": {"slope_range", "center_quantile_range"}, + "RandomUnsharpMaskGPU": {"sigma_min", "amount_min", "kernel_size"}, + } + for name, keys in expected.items(): + with self.subTest(transform=name): + self.assertLessEqual(keys, set(accepted_params(get(name, Backend.GPU)))) From 29f6136bfb83a40a6fd5bead30f40fd5ffa9c4e0 Mon Sep 17 00:00:00 2001 From: iback Date: Fri, 13 Nov 2026 14:37:14 +0000 Subject: [PATCH 2/2] docs: note how far RandomExpGPU's rate pushes the bright tail exp(k*x) is convex at the bright end, so once retain_stats restores mean and std the brightest voxels land far out. Measured on 128^3 spine patches (Dixon in-phase / CT): largest |z| 5.6 / 8.4 at k=1, 9.3 / 11.8 at k=2.5, 21 / 19 at k=5. Co-Authored-By: Claude Opus 5.5 --- smauglab/transforms/gpu/contrast.py | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/smauglab/transforms/gpu/contrast.py b/smauglab/transforms/gpu/contrast.py index 70f5ec9..8f2bf3c 100644 --- a/smauglab/transforms/gpu/contrast.py +++ b/smauglab/transforms/gpu/contrast.py @@ -1450,6 +1450,11 @@ class RandomExpGPU(_RandomNamedFunctionGPU): linear map of the input cannot explain is 1.6% on a uniform input. Setting the range draws a stronger member of the same family per sample; None keeps the fixed function and draws nothing. `[1, 5]` reaches 19% at k=4. + + Exp is convex at the bright end, so a large rate pushes the brightest voxels far out + once the stats are restored: measured on 128^3 spine patches (Dixon in-phase / CT), + the largest |z| is 5.6 / 8.4 at k=1, 9.3 / 11.8 at k=2.5 and 21 / 19 at k=5. Keep the + upper rate near 2.5 unless the outliers are wanted. """ function = staticmethod(torch.exp)