Source code for cellarium.ml.transforms.base
# Copyright Contributors to the Cellarium project.
# SPDX-License-Identifier: BSD-3-Clause
from collections.abc import Sequence
from typing import ClassVar, Literal, get_args
from torch import nn
Stage = Literal["train", "validate", "test", "predict"]
"""The stages of a :class:`~cellarium.ml.core.CellariumPipeline` that a transform can be active in."""
STAGES: tuple[Stage, ...] = get_args(Stage)
[docs]
class CellariumTransform(nn.Module):
"""
Base class for transforms that are active only in some stages of a
:class:`~cellarium.ml.core.CellariumPipeline`.
The stages are ``"train"`` (:meth:`CellariumPipeline.forward`), ``"validate"``, ``"test"`` and ``"predict"``.
Each transform declares the stages in which it is active by default with :attr:`default_stages`,
and the user can replace that set at instantiation with the ``stages`` argument.
The pipeline skips a transform in the stages it is not active in. Transforms that are not
:class:`CellariumTransform` instances (plain :class:`torch.nn.Module`) are active in every stage.
The stage is chosen by the pipeline method that is called (and by the dataloader that applies
the CPU transforms), not by :attr:`torch.nn.Module.training`, so it does not depend on whether
a module was put in ``eval`` mode, nor on a :class:`lightning.pytorch.Trainer` being used.
Calling a transform directly (outside of a pipeline) always applies it.
Args:
stages:
The stages in which the transform is active. If ``None`` (default), the transform is
active in the stages of :attr:`default_stages`. Otherwise this replaces :attr:`default_stages`.
"""
default_stages: ClassVar[frozenset[Stage]] = frozenset(STAGES)
# only set on the instance when overridden, so that instances created before this attribute existed
# (such as unpickled ones) fall back to ``default_stages``
_stages: frozenset[Stage] | None = None
def __init__(self, stages: Sequence[Stage] | None = None) -> None:
super().__init__()
if stages is not None:
if isinstance(stages, str):
raise TypeError(f"`stages` must be a sequence of stage names, not a string. Got {stages!r}")
unknown = set(stages) - set(STAGES)
if unknown:
raise ValueError(f"Unknown stages {sorted(unknown)}. Valid stages are {list(STAGES)}.")
self._stages = frozenset(stages)
@property
def stages(self) -> frozenset[Stage]:
"""The stages in which the transform is active."""
return self.default_stages if self._stages is None else self._stages
[docs]
def is_active(self, stage: Stage) -> bool:
"""Whether the transform is active in ``stage``."""
return stage in self.stages