Skip to content

BiasField

Bases: IntensityTransform

Corrupt an image with a smooth multiplicative bias field.

The bias field is generated by:

  1. Sampling a small 3D tensor from \(\mathcal{N}(0, \sigma)\).
  2. Trilinearly upsampling it to the image spatial shape.
  3. Taking the voxel-wise exponential to make it strictly positive.
  4. Multiplying the image by the resulting field.

This follows the approach used in SynthSeg: Segmentation of brain MRI scans of any contrast and resolution without retraining.

Parameters:

Name Type Description Default
std float | tuple[float, float] | Distribution

Standard deviation \(\sigma\) of the normal distribution used to sample the coarse bias field. Larger values produce stronger inhomogeneity. If two values \((a, b)\) are provided, \(\sigma \sim \mathcal{U}(a, b)\). A torch.distributions.Distribution may also be passed.

 0.5
scale float

Ratio between the coarse field size and the image spatial shape. Smaller values produce smoother fields.

 0.025
**kwargs Any

See Transform.

 {}

Examples:

>>> import torchio as tio
>>> transform = tio.BiasField()
>>> transform = tio.BiasField(std=0.8)
>>> transform = tio.BiasField(std=(0.0, 1.0))
Source code in src/torchio/transforms/intensity/bias_field.py 
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
class BiasField(IntensityTransform):
    r"""Corrupt an image with a smooth multiplicative bias field.

    The bias field is generated by:

    1. Sampling a small 3D tensor from $\mathcal{N}(0, \sigma)$.
    2. Trilinearly upsampling it to the image spatial shape.
    3. Taking the voxel-wise exponential to make it strictly positive.
    4. Multiplying the image by the resulting field.

    This follows the approach used in [SynthSeg: Segmentation of brain MRI
    scans of any contrast and resolution without
    retraining](https://www.sciencedirect.com/science/article/pii/S1361841523000506).

    Args:
        std: Standard deviation $\sigma$ of the normal distribution
            used to sample the coarse bias field. Larger values produce
            stronger inhomogeneity. If two values $(a, b)$ are provided,
            $\sigma \sim \mathcal{U}(a, b)$. A
            `torch.distributions.Distribution` may also be passed.
        scale: Ratio between the coarse field size and the image spatial
            shape. Smaller values produce smoother fields.
        **kwargs: See [`Transform`][torchio.Transform].

    Examples:
        >>> import torchio as tio
        >>> transform = tio.BiasField()
        >>> transform = tio.BiasField(std=0.8)
        >>> transform = tio.BiasField(std=(0.0, 1.0))
    """

    def __init__(
        self,
        *,
        std: float | tuple[float, float] | torch.distributions.Distribution = 0.5,
        scale: float = 0.025,
        **kwargs: Any,
    ) -> None:
        super().__init__(**kwargs)
        self.std = to_nonneg_range(std)
        if scale <= 0 or scale > 1:
            msg = f"scale must be in (0, 1], got {scale}"
            raise ValueError(msg)
        self.scale = scale

    def make_params(self, batch: SubjectsBatch) -> dict[str, Any]:
        """Sample the bias field standard deviation and a random seed."""
        return {
            "std": self.std.sample_1d(),
            "seed": int(torch.randint(0, 2**31, (1,)).item()),
            "scale": self.scale,
        }

    def apply_transform(
        self,
        batch: SubjectsBatch,
        params: dict[str, Any],
    ) -> SubjectsBatch:
        """Multiply each selected image by a smooth random bias field."""
        std = params["std"]
        seed = params["seed"]
        scale = params["scale"]

        if std == 0:
            return batch

        for _name, img_batch in self._get_images(batch).items():
            field = _generate_bias_field(
                img_batch.data.shape,
                std=std,
                scale=scale,
                seed=seed,
                device=img_batch.data.device,
            )
            img_batch.data = img_batch.data * field

        return batch

    @property
    def invertible(self) -> bool:
        """Whether this transform can be inverted."""
        return True

    def inverse(self, params: dict[str, Any]) -> _BiasFieldInverse:
        """Build the inverse by dividing by the same bias field."""
        return _BiasFieldInverse(
            std=params["std"],
            seed=params["seed"],
            scale=params["scale"],
            copy=False,
        )

invertible property

Whether this transform can be inverted.

forward(data) 

forward(data: Subject) -> Subject

forward(data: Image) -> Image

forward(data: Tensor) -> Tensor

forward(data: np.ndarray) -> np.ndarray

forward(data: sitk.Image) -> sitk.Image

forward(data: nib.Nifti1Image) -> nib.Nifti1Image

forward(data: dict) -> dict

forward(data: ImagesBatch) -> ImagesBatch

forward(data: SubjectsBatch) -> SubjectsBatch

Apply the transform.

The output type always matches the input type.

Parameters:

Name Type Description Default
data Any

Input data to transform.

 required
Source code in src/torchio/transforms/transform.py 
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
def forward(self, data: Any) -> Any:
    """Apply the transform.

    The output type always matches the input type.

    Args:
        data: Input data to transform.
    """
    if self.copy:
        data = _copy.deepcopy(data)
    batch, unwrap = self._wrap(data)
    if torch.rand(1).item() > self.p:
        return unwrap(batch)
    params = self.make_params(batch)
    batch = self.apply_transform(batch, params)
    # Record history on the batch
    trace = AppliedTransform(name=type(self).__name__, params=params)
    if not hasattr(batch, "applied_transforms"):
        batch.applied_transforms = []
    batch.applied_transforms.append(trace)
    result = unwrap(batch)
    # Propagate history to outputs that can carry it
    if (
        hasattr(batch, "applied_transforms")
        and not isinstance(result, (SubjectsBatch, Tensor, np.ndarray))
        and not isinstance(result, dict)
    ):
        with contextlib.suppress(AttributeError):
            result.applied_transforms = list(batch.applied_transforms)
    return result

to_hydra()

Export as a Hydra-compatible config dict.

Returns a dict with _target_ set to the fully qualified class name and only non-default field values included.

Returns:

Type Description
dict[str, Any]

Dict suitable for hydra.utils.instantiate().
Source code in src/torchio/transforms/transform.py 
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
def to_hydra(self) -> dict[str, Any]:
    """Export as a Hydra-compatible config dict.

    Returns a dict with `_target_` set to the fully qualified
    class name and only non-default field values included.

    Returns:
        Dict suitable for `hydra.utils.instantiate()`.
    """
    from .parameter_range import _ParameterRange

    cls = type(self)
    target = f"torchio.{cls.__qualname__}"
    cfg: dict[str, Any] = {"_target_": target}

    for name, default in _collect_init_params(cls).items():
        value = getattr(self, name, default)
        if isinstance(value, _ParameterRange):
            if value._original == default:
                continue
            value = _hydra_value(value._original)
        elif value == default:
            continue
        else:
            value = _hydra_value(value)
        cfg[name] = value
    return cfg

make_params(batch)

Sample the bias field standard deviation and a random seed.

Source code in src/torchio/transforms/intensity/bias_field.py 
66
67
68
69
70
71
72
def make_params(self, batch: SubjectsBatch) -> dict[str, Any]:
    """Sample the bias field standard deviation and a random seed."""
    return {
        "std": self.std.sample_1d(),
        "seed": int(torch.randint(0, 2**31, (1,)).item()),
        "scale": self.scale,
    }

apply_transform(batch, params)

Multiply each selected image by a smooth random bias field.

Source code in src/torchio/transforms/intensity/bias_field.py 
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
def apply_transform(
    self,
    batch: SubjectsBatch,
    params: dict[str, Any],
) -> SubjectsBatch:
    """Multiply each selected image by a smooth random bias field."""
    std = params["std"]
    seed = params["seed"]
    scale = params["scale"]

    if std == 0:
        return batch

    for _name, img_batch in self._get_images(batch).items():
        field = _generate_bias_field(
            img_batch.data.shape,
            std=std,
            scale=scale,
            seed=seed,
            device=img_batch.data.device,
        )
        img_batch.data = img_batch.data * field

    return batch

inverse(params)

Build the inverse by dividing by the same bias field.

Source code in src/torchio/transforms/intensity/bias_field.py 
104
105
106
107
108
109
110
111
def inverse(self, params: dict[str, Any]) -> _BiasFieldInverse:
    """Build the inverse by dividing by the same bias field."""
    return _BiasFieldInverse(
        std=params["std"],
        seed=params["seed"],
        scale=params["scale"],
        copy=False,
    )