SequentialLabels

Bases: Transform

Renumber labels in label maps to consecutive integers starting from 0.

For example, if a label map has values {0, 5, 10}, this transform remaps them to {0, 1, 2}.

Only LabelMap images are affected.

Note

The background (label 0) is always mapped to 0. Even if there are no zeros in the input, zero will appear in the output.

Parameters:

Name	Type	Description	Default
`**kwargs`	`Any`	See `Transform`.	`{}`

Examples:

>>> import torchio as tio
>>> transform = tio.SequentialLabels()

Source code in src/torchio/transforms/label/sequential_labels.py

class SequentialLabels(Transform):
    r"""Renumber labels in label maps to consecutive integers starting from 0.

    For example, if a label map has values `{0, 5, 10}`, this
    transform remaps them to `{0, 1, 2}`.

    Only [`LabelMap`][torchio.LabelMap] images are affected.

    Note:
        The background (label 0) is always mapped to 0. Even if there
        are no zeros in the input, zero will appear in the output.

    Args:
        **kwargs: See [`Transform`][torchio.Transform].

    Examples:
        >>> import torchio as tio
        >>> transform = tio.SequentialLabels()
    """

    def __init__(self, **kwargs: Any) -> None:
        super().__init__(**kwargs)

    def make_params(self, batch: SubjectsBatch) -> dict[str, Any]:
        """Compute the remapping from the first sample's labels."""
        remappings: dict[str, dict[int, int]] = {}
        for name, img_batch in batch.images.items():
            if not issubclass(img_batch._image_class, LabelMap):
                continue
            unique = sorted(int(v) for v in img_batch.data[0].unique().tolist())
            remappings[name] = {old: new for new, old in enumerate(unique)}
        return {"remappings": remappings}

    def apply_transform(
        self,
        batch: SubjectsBatch,
        params: dict[str, Any],
    ) -> SubjectsBatch:
        """Apply sequential renumbering."""
        remappings = params["remappings"]
        for name, img_batch in batch.images.items():
            if name not in remappings:
                continue
            remapping = remappings[name]
            data = torch.zeros_like(img_batch.data)
            for old, new in remapping.items():
                data[img_batch.data == old] = new
            img_batch.data = data
        return batch

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

    def inverse(self, params: dict[str, Any]) -> _SequentialLabelsInverse:
        """Invert by restoring original label values."""
        return _SequentialLabelsInverse(
            remappings=params["remappings"],
            copy=False,
        )

`supports_per_instance_params` `property`

Whether this transform can sample parameters per batch element.

Defaults to False. Transforms that implement per-instance parameter sampling override this to return True. When False, the transform always uses batch-shared parameters regardless of the per_instance flag, preserving the legacy behavior.

`supports_per_instance_p` `property`

Whether this transform can gate each batch element independently.

Defaults to False. Shape-preserving transforms that implement per-element probability override this to return True. Shape-changing transforms must leave it False because masked and unmasked elements would have incompatible shapes.

`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

def forward(self, data: Any) -> Any:
    """Apply the transform.

    The output type always matches the input type.

    Args:
        data: Input data to transform.
    """
    return self._execute(data, params=None, sample_params=True)

`apply_with_params(data, params)`

apply_with_params(data: Subject, params: dict[str, Any]) -> Subject

apply_with_params(data: Image, params: dict[str, Any]) -> Image

apply_with_params(data: Tensor, params: dict[str, Any]) -> Tensor

apply_with_params(data: np.ndarray, params: dict[str, Any]) -> np.ndarray

apply_with_params(data: sitk.Image, params: dict[str, Any]) -> sitk.Image

apply_with_params(data: nib.Nifti1Image, params: dict[str, Any]) -> nib.Nifti1Image

apply_with_params(data: dict, params: dict[str, Any]) -> dict

apply_with_params(data: ImagesBatch, params: dict[str, Any]) -> ImagesBatch

apply_with_params(data: SubjectsBatch, params: dict[str, Any]) -> SubjectsBatch

Apply an exact parameter set without sampling.

This method bypasses the transform probability and make_params(), but otherwise follows the normal transform lifecycle: copy handling, input wrapping, output-type restoration, and history recording.

Parameters:

Name	Type	Description	Default
`data`	`Any`	Input data to transform.	required
`params`	`dict[str, Any]`	Exact parameters accepted by `apply_transform`.	required

Returns:

Type	Description
`Any`	Transformed data with the same type as the input.

Raises:

Type	Description
`TypeError`	If `params` is not a dictionary.
`NotImplementedError`	If the transform does not expose one exact-parameter kernel.
`ValueError`	If per-instance parameter dimensions do not match the input batch.

Source code in src/torchio/transforms/transform.py

def apply_with_params(
    self,
    data: Any,
    params: dict[str, Any],
) -> Any:
    """Apply an exact parameter set without sampling.

    This method bypasses the transform probability and
    [`make_params()`][torchio.Transform.make_params], but otherwise
    follows the normal transform lifecycle: copy handling, input
    wrapping, output-type restoration, and history recording.

    Args:
        data: Input data to transform.
        params: Exact parameters accepted by `apply_transform`.

    Returns:
        Transformed data with the same type as the input.

    Raises:
        TypeError: If `params` is not a dictionary.
        NotImplementedError: If the transform does not expose one
            exact-parameter kernel.
        ValueError: If per-instance parameter dimensions do not
            match the input batch.
    """
    if not self._supports_apply_with_params:
        msg = (
            f"{type(self).__name__}.apply_with_params() is not supported"
            " because this transform does not expose a single"
            " make_params/apply_transform parameter kernel."
        )
        raise NotImplementedError(msg)
    if not isinstance(params, dict):
        msg = f"Expected params to be a dict, got {type(params).__name__}"
        raise TypeError(msg)
    return self._execute(
        data,
        params=_copy.deepcopy(params),
        sample_params=False,
    )

`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

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

Compute the remapping from the first sample's labels.

Source code in src/torchio/transforms/label/sequential_labels.py

def make_params(self, batch: SubjectsBatch) -> dict[str, Any]:
    """Compute the remapping from the first sample's labels."""
    remappings: dict[str, dict[int, int]] = {}
    for name, img_batch in batch.images.items():
        if not issubclass(img_batch._image_class, LabelMap):
            continue
        unique = sorted(int(v) for v in img_batch.data[0].unique().tolist())
        remappings[name] = {old: new for new, old in enumerate(unique)}
    return {"remappings": remappings}

`apply_transform(batch, params)`

Apply sequential renumbering.

Source code in src/torchio/transforms/label/sequential_labels.py

def apply_transform(
    self,
    batch: SubjectsBatch,
    params: dict[str, Any],
) -> SubjectsBatch:
    """Apply sequential renumbering."""
    remappings = params["remappings"]
    for name, img_batch in batch.images.items():
        if name not in remappings:
            continue
        remapping = remappings[name]
        data = torch.zeros_like(img_batch.data)
        for old, new in remapping.items():
            data[img_batch.data == old] = new
        img_batch.data = data
    return batch

`inverse(params)`

Invert by restoring original label values.

Source code in src/torchio/transforms/label/sequential_labels.py

def inverse(self, params: dict[str, Any]) -> _SequentialLabelsInverse:
    """Invert by restoring original label values."""
    return _SequentialLabelsInverse(
        remappings=params["remappings"],
        copy=False,
    )

SequentialLabels

supports_per_instance_params property

supports_per_instance_p property

invertible property

forward(data)

apply_with_params(data, params)

to_hydra()

make_params(batch)

apply_transform(batch, params)

inverse(params)

`supports_per_instance_params` `property`

`supports_per_instance_p` `property`

`invertible` `property`

`forward(data)`

`apply_with_params(data, params)`

`to_hydra()`

`make_params(batch)`

`apply_transform(batch, params)`

`inverse(params)`