autoden ¶

Auto-Denoise package.

Unsupervised and self-supervised CNN denoising methods.

Modules:

algorithms –

Algorithms sub-package.
cli –

Module that contains the command line application.
debug –

Debugging utilities.
losses –

Data losses definitions.
models –

Models sub-package.
transforms –

Transforms sub-package.

Classes:

DIP –

Deep image prior.
N2N –

Self-supervised denoising from pairs of images.
N2V –

Self-supervised denoising from single images.
Supervised –

Supervised denoising class.

DIP ¶

DIP(
    model: int | str | NetworkParams | Module | Mapping,
    data_scale_bias: DataScaleBias | None = None,
    reg_val: float | LossRegularizer | None = None,
    device: str = "cuda" if is_available() else "cpu",
    batch_size: int | None = None,
    augmentation: (
        str
        | Augmentation
        | Sequence[str | Augmentation]
        | None
    ) = None,
    save_epochs_dir: str | None = None,
    verbose: bool = True,
)

Bases: Denoiser

Deep image prior.

Parameters:

model (str | NetworkParams | Module | Mapping | None) –

Type of neural network to use or a specific network (or state) to use
data_scale_bias (DataScaleBias | None, default: None ) –

Scale and bias of the input data, by default None
reg_val (float | None, default: None ) –

Regularization value, by default 1e-5
device (str, default: 'cuda' if is_available() else 'cpu' ) –

Device to use, by default "cuda" if cuda is available, otherwise "cpu"
save_epochs_dir (str | None, default: None ) –

Directory where to save network states at each epoch. If None disabled, by default None
verbose (bool, default: True ) –

Whether to produce verbose output, by default True

Methods:

infer –

Inference, given an initial stack of images.
prepare_data –

Prepare input data.
train –

Train the model in an unsupervised manner.

Attributes:

n_channels_in (int) –

Returns the number of input channels of the model.
n_channels_out (int) –

Returns the number of output channels of the model.
n_dims (int) –

Returns the expected signal dimensions.

Source code in src/autoden/algorithms/denoiser.py

def __init__(
    self,
    model: int | str | NetworkParams | pt.nn.Module | Mapping,
    data_scale_bias: DataScaleBias | None = None,
    reg_val: float | LossRegularizer | None = None,
    device: str = "cuda" if pt.cuda.is_available() else "cpu",
    batch_size: int | None = None,
    augmentation: str | Augmentation | Sequence[str | Augmentation] | None = None,
    save_epochs_dir: str | None = None,
    verbose: bool = True,
) -> None:
    """Initialize the noise2noise method.

    Parameters
    ----------
    model : str | NetworkParams | pt.nn.Module | Mapping | None
        Type of neural network to use or a specific network (or state) to use
    data_scale_bias : DataScaleBias | None, optional
        Scale and bias of the input data, by default None
    reg_val : float | None, optional
        Regularization value, by default 1e-5
    device : str, optional
        Device to use, by default "cuda" if cuda is available, otherwise "cpu"
    save_epochs_dir : str | None, optional
        Directory where to save network states at each epoch.
        If None disabled, by default None
    verbose : bool, optional
        Whether to produce verbose output, by default True
    """
    if isinstance(model, int):
        if self.save_epochs_dir is None:
            raise ValueError("Directory for saving epochs not specified")

        model = load_model_state(self.save_epochs_dir, epoch_num=model)

    if isinstance(model, (str, NetworkParams, Mapping, pt.nn.Module)):
        self.model = create_network(model, device=device)
    else:
        raise ValueError(f"Invalid model {type(model)}")
    if verbose:
        get_num_parameters(self.model, verbose=True)

    # if augmentation is None:
    #     augmentation = []
    # elif isinstance(augmentation, str):
    #     augmentation = [augmentation.lower()]
    # elif isinstance(augmentation, Sequence):
    #     augmentation = [str(a).lower() for a in augmentation]

    self.data_sb = data_scale_bias

    self.reg_val = reg_val
    self.device = device
    self.batch_size = batch_size
    self.augmentation = augmentation
    self.save_epochs_dir = save_epochs_dir
    self.verbose = verbose

n_channels_in `property` ¶

n_channels_in: int

Returns the number of input channels of the model.

If the model is an instance of SerializableModel and has an init_params attribute containing the key "n_channels_in", this property returns its value. Otherwise, it defaults to 1.

Returns:

int –

The number of input channels.

n_channels_out `property` ¶

n_channels_out: int

Returns the number of output channels of the model.

If the model is an instance of SerializableModel and has an init_params attribute containing the key "n_channels_out", this property returns its value. Otherwise, it defaults to 1.

Returns:

int –

The number of output channels.

n_dims `property` ¶

n_dims: int

Returns the expected signal dimensions.

If the model is an instance of SerializableModel and has an init_params attribute containing the key "n_dims", this property returns its value. Otherwise, it defaults to 2.

Returns:

int –

The expected signal dimensions.

infer ¶

infer(
    inp: NDArray, channel_axis_dst: int | None = None
) -> NDArray

Inference, given an initial stack of images.

Parameters:

inp (NDArray) –

The input stack of images
channel_axis_dst (int | None, default: None ) –

The desired channel axis for the output. If None, the output will have the same channel axis as the input.

Returns:

NDArray –

The denoised stack of images

Source code in src/autoden/algorithms/denoiser.py

def infer(self, inp: NDArray, channel_axis_dst: int | None = None) -> NDArray:
    """Inference, given an initial stack of images.

    Parameters
    ----------
    inp : NDArray
        The input stack of images
    channel_axis_dst : int | None, optional
        The desired channel axis for the output. If None, the output will have the same channel axis as the input.

    Returns
    -------
    NDArray
        The denoised stack of images
    """
    # Rescale input
    if self.data_sb is not None:
        inp = inp * self.data_sb.scale_inp - self.data_sb.bias_inp

    channel_ax_inp = -self.n_dims - 1 if self.n_channels_in > 1 else None
    inp_t = data_to_tensor(inp, device=self.device, n_dims=self.n_dims, channel_axis=channel_ax_inp)

    self.model.eval()
    with pt.inference_mode():
        out_t: pt.Tensor = self.model(inp_t)
        output = out_t.squeeze(dim=(0, 1)).to("cpu").numpy()

    # Rescale output
    if self.data_sb is not None:
        output = (output + self.data_sb.bias_out) / self.data_sb.scale_out

    if channel_axis_dst is not None:
        output = self._move_output_channel_axis(output, channel_axis_dst)

    return output

prepare_data ¶

prepare_data(
    tgt: NDArray,
    inp: NDArray | None = None,
    *,
    num_tst_ratio: float = 0.2,
    average_redundant: bool = False,
    channel_axis: int | None = None
) -> tuple[NDArray, NDArray, NDArray]

Prepare input data.

Parameters:

tgt (NDArray) –

The target image array. The shape of the output noise array will match the spatial dimensions of this array.
inp (NDArray | None, default: None ) –

The input image array. If provided, it will be used as the initial input for the DIP algorithm. If None, a random noise array will be generated. Default is None.
num_tst_ratio (float, default: 0.2 ) –

The ratio of the test set size to the total dataset size. Default is 0.2.
average_redundant (bool, default: False ) –

If True, average redundant realizations in the target array to match the expected number of dimensions. Default is False.
channel_axis (int | None, default: None ) –

The axis of the target array that corresponds to the spectral dimension. If None, the spectral dimension is assumed to not be present. Default is None.

Returns:

tuple[NDArray, NDArray, NDArray] –

A tuple containing: - A random noise array with the same spatial dimensions as the target image. - The target image array. - A mask array indicating the training pixels.

Notes

This function generates a random noise array with the same spatial dimensions as the target image. The noise array is used as the initial input for the DIP algorithm. It also generates a mask array indicating the training pixels based on the provided ratio.

Source code in src/autoden/algorithms/deep_image_prior.py

def prepare_data(
    self,
    tgt: NDArray,
    inp: NDArray | None = None,
    *,
    num_tst_ratio: float = 0.2,
    average_redundant: bool = False,
    channel_axis: int | None = None,
) -> tuple[NDArray, NDArray, NDArray]:
    """
    Prepare input data.

    Parameters
    ----------
    tgt : NDArray
        The target image array. The shape of the output noise array will match
        the spatial dimensions of this array.
    inp : NDArray | None, optional
        The input image array. If provided, it will be used as the initial input
        for the DIP algorithm. If None, a random noise array will be generated.
        Default is None.
    num_tst_ratio : float, optional
        The ratio of the test set size to the total dataset size.
        Default is 0.2.
    average_redundant : bool, optional
        If True, average redundant realizations in the target array to match the
        expected number of dimensions. Default is False.
    channel_axis : int | None, optional
        The axis of the target array that corresponds to the spectral dimension.
        If None, the spectral dimension is assumed to not be present.
        Default is None.

    Returns
    -------
    tuple[NDArray, NDArray, NDArray]
        A tuple containing:
        - A random noise array with the same spatial dimensions as the target
          image.
        - The target image array.
        - A mask array indicating the training pixels.

    Notes
    -----
    This function generates a random noise array with the same spatial dimensions
    as the target image. The noise array is used as the initial input for the DIP
    algorithm. It also generates a mask array indicating the training pixels based
    on the provided ratio.
    """
    tgt, channel_axis_tgt = self._prepare_channel_axis(tgt, channel_axis)
    self._check_channel_axis_size(tgt, channel_axis_tgt, "n_channels_out")

    model_tgt_axes = self.n_dims + (self.n_channels_out > 1)
    if tgt.ndim < model_tgt_axes:
        raise ValueError(f"Target data should at least be of {model_tgt_axes} dimensions, but its shape is {tgt.shape}")

    if average_redundant and tgt.ndim > model_tgt_axes:
        tgt = tgt.mean(axis=tuple(np.arange(-tgt.ndim, -model_tgt_axes)))

    if inp is None:
        inp = np.random.normal(size=tgt.shape[-model_tgt_axes:], scale=0.25).astype(tgt.dtype)
    else:
        inp, channel_axis_inp = self._prepare_channel_axis(inp, channel_axis)
        self._check_channel_axis_size(inp, channel_axis_inp, "n_channels_inp")

        model_inp_axes = self.n_dims + (self.n_channels_in > 1)
        if inp.ndim < model_inp_axes:
            raise ValueError(f"Input data should at least be of {model_inp_axes} dimensions, but its shape is {inp.shape}")

    mask_trn = get_random_pixel_mask(tgt.shape, mask_pixel_ratio=num_tst_ratio)
    return inp, tgt, mask_trn

train ¶

train(
    inp: NDArray,
    tgt: NDArray,
    mask_trn: NDArray,
    *,
    epochs: int,
    learning_rate: float = 0.001,
    optimizer: str = "adam",
    lower_limit: float | NDArray | None = None
) -> dict[str, NDArray]

Train the model in an unsupervised manner.

Parameters:

inp (NDArray) –

The input image.
tgt (NDArray) –

The target image to be denoised.
mask_trn (NDArray) –

The mask array indicating the training pixels.
epochs (int) –

The number of training epochs.
learning_rate (float, default: 0.001 ) –

The learning rate for the optimizer. Default is 1e-3.
optimizer (str, default: 'adam' ) –

The optimization algorithm to use. Default is "adam".
lower_limit (float | NDArray | None, default: None ) –

The lower limit for the input data. If provided, the input data will be clipped to this limit. Default is None.

Returns:

dict[str, NDArray] –

A dictionary containing the training losses.

Notes

This method trains the model using the deep image prior approach in an unsupervised manner. It uses a random initialization for the input image if not provided and applies a scaling and bias transformation to the input and target images. It then trains the model using the specified optimization algorithm and the provided mask array indicating the training pixels.

Source code in src/autoden/algorithms/deep_image_prior.py

def train(
    self,
    inp: NDArray,
    tgt: NDArray,
    mask_trn: NDArray,
    *,
    epochs: int,
    learning_rate: float = 1e-3,
    optimizer: str = "adam",
    lower_limit: float | NDArray | None = None,
) -> dict[str, NDArray]:
    """
    Train the model in an unsupervised manner.

    Parameters
    ----------
    inp : NDArray
        The input image.
    tgt : NDArray
        The target image to be denoised.
    mask_trn : NDArray
        The mask array indicating the training pixels.
    epochs : int
        The number of training epochs.
    learning_rate : float, optional
        The learning rate for the optimizer. Default is 1e-3.
    optimizer : str, optional
        The optimization algorithm to use. Default is "adam".
    lower_limit : float | NDArray | None, optional
        The lower limit for the input data. If provided, the input data will be clipped to this limit.
        Default is None.

    Returns
    -------
    dict[str, NDArray]
        A dictionary containing the training losses.

    Notes
    -----
    This method trains the model using the deep image prior approach in an unsupervised manner.
    It uses a random initialization for the input image if not provided and applies a scaling and bias
    transformation to the input and target images. It then trains the model using the specified optimization
    algorithm and the provided mask array indicating the training pixels.
    """
    if self.data_sb is None:
        self.data_sb = compute_scaling_supervised(inp, tgt)

    # Rescale the datasets
    tmp_inp = inp * self.data_sb.scale_inp - self.data_sb.bias_inp
    tmp_tgt = tgt * self.data_sb.scale_tgt - self.data_sb.bias_tgt

    reg = self._get_regularization()
    losses = self._train_pixelmask_small(
        inp=tmp_inp,
        tgt=tmp_tgt,
        mask_trn=mask_trn,
        epochs=epochs,
        learning_rate=learning_rate,
        optimizer=optimizer,
        regularizer=reg,
        lower_limit=lower_limit,
    )

    if self.verbose:
        self._plot_loss_curves(losses, f"Unsupervised {self.__class__.__name__} {optimizer.upper()}")

    return losses

N2N ¶

N2N(
    model: int | str | NetworkParams | Module | Mapping,
    data_scale_bias: DataScaleBias | None = None,
    reg_val: float | LossRegularizer | None = None,
    device: str = "cuda" if is_available() else "cpu",
    batch_size: int | None = None,
    augmentation: (
        str
        | Augmentation
        | Sequence[str | Augmentation]
        | None
    ) = None,
    save_epochs_dir: str | None = None,
    verbose: bool = True,
)

Bases: Denoiser

Self-supervised denoising from pairs of images.

Parameters:

model (str | NetworkParams | Module | Mapping | None) –

Type of neural network to use or a specific network (or state) to use
data_scale_bias (DataScaleBias | None, default: None ) –

Scale and bias of the input data, by default None
reg_val (float | None, default: None ) –

Regularization value, by default 1e-5
device (str, default: 'cuda' if is_available() else 'cpu' ) –

Device to use, by default "cuda" if cuda is available, otherwise "cpu"
save_epochs_dir (str | None, default: None ) –

Directory where to save network states at each epoch. If None disabled, by default None
verbose (bool, default: True ) –

Whether to produce verbose output, by default True

Methods:

infer –

Perform inference on the input data.
prepare_data –

Prepare input data for training.
train –

Train the denoiser using the Noise2Noise self-supervised approach.

Attributes:

n_channels_in (int) –

Returns the number of input channels of the model.
n_channels_out (int) –

Returns the number of output channels of the model.
n_dims (int) –

Returns the expected signal dimensions.

Source code in src/autoden/algorithms/denoiser.py

def __init__(
    self,
    model: int | str | NetworkParams | pt.nn.Module | Mapping,
    data_scale_bias: DataScaleBias | None = None,
    reg_val: float | LossRegularizer | None = None,
    device: str = "cuda" if pt.cuda.is_available() else "cpu",
    batch_size: int | None = None,
    augmentation: str | Augmentation | Sequence[str | Augmentation] | None = None,
    save_epochs_dir: str | None = None,
    verbose: bool = True,
) -> None:
    """Initialize the noise2noise method.

    Parameters
    ----------
    model : str | NetworkParams | pt.nn.Module | Mapping | None
        Type of neural network to use or a specific network (or state) to use
    data_scale_bias : DataScaleBias | None, optional
        Scale and bias of the input data, by default None
    reg_val : float | None, optional
        Regularization value, by default 1e-5
    device : str, optional
        Device to use, by default "cuda" if cuda is available, otherwise "cpu"
    save_epochs_dir : str | None, optional
        Directory where to save network states at each epoch.
        If None disabled, by default None
    verbose : bool, optional
        Whether to produce verbose output, by default True
    """
    if isinstance(model, int):
        if self.save_epochs_dir is None:
            raise ValueError("Directory for saving epochs not specified")

        model = load_model_state(self.save_epochs_dir, epoch_num=model)

    if isinstance(model, (str, NetworkParams, Mapping, pt.nn.Module)):
        self.model = create_network(model, device=device)
    else:
        raise ValueError(f"Invalid model {type(model)}")
    if verbose:
        get_num_parameters(self.model, verbose=True)

    # if augmentation is None:
    #     augmentation = []
    # elif isinstance(augmentation, str):
    #     augmentation = [augmentation.lower()]
    # elif isinstance(augmentation, Sequence):
    #     augmentation = [str(a).lower() for a in augmentation]

    self.data_sb = data_scale_bias

    self.reg_val = reg_val
    self.device = device
    self.batch_size = batch_size
    self.augmentation = augmentation
    self.save_epochs_dir = save_epochs_dir
    self.verbose = verbose

n_channels_in `property` ¶

n_channels_in: int

Returns the number of input channels of the model.

If the model is an instance of SerializableModel and has an init_params attribute containing the key "n_channels_in", this property returns its value. Otherwise, it defaults to 1.

Returns:

int –

The number of input channels.

n_channels_out `property` ¶

n_channels_out: int

Returns the number of output channels of the model.

If the model is an instance of SerializableModel and has an init_params attribute containing the key "n_channels_out", this property returns its value. Otherwise, it defaults to 1.

Returns:

int –

The number of output channels.

n_dims `property` ¶

n_dims: int

Returns the expected signal dimensions.

If the model is an instance of SerializableModel and has an init_params attribute containing the key "n_dims", this property returns its value. Otherwise, it defaults to 2.

Returns:

int –

The expected signal dimensions.

infer ¶

infer(
    inp: NDArray,
    average_splits: bool = True,
    channel_axis_dst: int | None = None,
) -> NDArray

Perform inference on the input data.

Parameters:

inp (NDArray) –

The input data to perform inference on. It is expected to have an extra dimension including the different splits.
average_splits (bool, default: True ) –

If True, the splits are averaged. Default is True.
channel_axis_dst (int | None, default: None ) –

The desired channel axis for the output. If None, the output will have the same channel axis as the input.

Returns:

NDArray –

The inferred output data. If average_splits is True, the splits are averaged.

Notes

If self.batch_size is set, the input data is processed in batches to avoid memory issues.

Source code in src/autoden/algorithms/noise2noise.py

def infer(self, inp: NDArray, average_splits: bool = True, channel_axis_dst: int | None = None) -> NDArray:
    """
    Perform inference on the input data.

    Parameters
    ----------
    inp : NDArray
        The input data to perform inference on. It is expected to have an extra dimension including the different splits.
    average_splits : bool, optional
        If True, the splits are averaged. Default is True.
    channel_axis_dst : int | None, optional
        The desired channel axis for the output. If None, the output will have the same channel axis as the input.

    Returns
    -------
    NDArray
        The inferred output data. If `average_splits` is True, the splits are averaged.

    Notes
    -----
    If `self.batch_size` is set, the input data is processed in batches to avoid memory issues.
    """
    inp_shape = inp.shape
    dims_to_preserve = self.n_dims + (self.n_channels_in > 1)
    inp = inp.reshape([-1, *inp_shape[-dims_to_preserve:]])

    if self.batch_size is not None:
        out = []
        for b in tqdm(range(0, inp.shape[0], self.batch_size), desc="Inference batch"):
            out.append(super().infer(inp[b : b + self.batch_size]))
        out = np.concatenate(out, axis=0)
    else:
        out = super().infer(inp)
    out = out.reshape(inp_shape)

    if average_splits:
        realization_batch_axis = -dims_to_preserve - 1
        out = out.mean(axis=realization_batch_axis)

    if channel_axis_dst is not None:
        out = self._move_output_channel_axis(out, channel_axis_dst)

    return out

prepare_data ¶

prepare_data(
    inp: NDArray,
    num_tst_ratio: float = 0.2,
    strategy: str = "1:X",
    channel_axis: int | None = None,
    realizations_axis: int = 0,
) -> tuple[NDArray, NDArray, NDArray]

Prepare input data for training.

Parameters:

inp (NDArray) –

The input data to be used for training. This should be a NumPy array of shape (N, H, W), where N is the number of samples, and H and W are the height and width of each sample, respectively.
num_tst_ratio (float, default: 0.2 ) –

The ratio of the input data to be used for testing. The remaining data will be used for training. Default is 0.2.
strategy (str, default: '1:X' ) –

The strategy to be used for creating input-target pairs. The available strategies are: - "1:X": Use the mean of the remaining samples as the target for each sample. - "X:1": Use the mean of the remaining samples as the input for each sample. Default is "1:X".
channel_axis (int | None, default: None ) –

The axis of the input array that corresponds to the spectral dimension. If None, the spectral dimension is assumed to not be present. Default is None.
realizations_axis (int, default: 0 ) –

The axis of the input array that corresponds to the redundant realizations dimension. Default is 0.

Returns:

tuple[NDArray, NDArray, NDArray] –

A tuple containing: - The input data array. - The target data array. - The mask array indicating the training pixels.

Notes

This function generates input-target pairs based on the specified strategy. It also generates a mask array indicating the training pixels based on the provided ratio.

Source code in src/autoden/algorithms/noise2noise.py

def prepare_data(
    self,
    inp: NDArray,
    num_tst_ratio: float = 0.2,
    strategy: str = "1:X",
    channel_axis: int | None = None,
    realizations_axis: int = 0,
) -> tuple[NDArray, NDArray, NDArray]:
    """
    Prepare input data for training.

    Parameters
    ----------
    inp : NDArray
        The input data to be used for training. This should be a NumPy array of shape (N, H, W), where N is the
        number of samples, and H and W are the height and width of each sample, respectively.
    num_tst_ratio : float, optional
        The ratio of the input data to be used for testing. The remaining data will be used for training.
        Default is 0.2.
    strategy : str, optional
        The strategy to be used for creating input-target pairs. The available strategies are:
        - "1:X": Use the mean of the remaining samples as the target for each sample.
        - "X:1": Use the mean of the remaining samples as the input for each sample.
        Default is "1:X".
    channel_axis : int | None, optional
        The axis of the input array that corresponds to the spectral dimension.
        If None, the spectral dimension is assumed to not be present.
        Default is None.
    realizations_axis : int, optional
        The axis of the input array that corresponds to the redundant realizations dimension. Default is 0.

    Returns
    -------
    tuple[NDArray, NDArray, NDArray]
        A tuple containing:
        - The input data array.
        - The target data array.
        - The mask array indicating the training pixels.

    Notes
    -----
    This function generates input-target pairs based on the specified strategy. It also generates a mask array
    indicating the training pixels based on the provided ratio.
    """
    inp, channel_axis = self._prepare_channel_axis(inp, channel_axis)
    self._check_channel_axis_size(inp, channel_axis, "n_channels_in")
    self._check_channel_axis_size(inp, channel_axis, "n_channels_out")

    model_n_axes = self.n_dims + (channel_axis is not None)
    if inp.ndim < model_n_axes:
        raise ValueError(f"Target data should at least be of {model_n_axes + 1} dimensions, but its shape is {inp.shape}")

    # This will be the destination position of the axis
    realizations_dst_axis = inp.ndim - model_n_axes - 1

    inp_x = np.stack(
        [np.delete(inp, obj=ii, axis=realizations_axis).mean(axis=realizations_axis) for ii in range(len(inp))],
        axis=realizations_dst_axis,
    )
    inp = np.moveaxis(inp, source=realizations_axis, destination=realizations_dst_axis)

    if strategy.upper() == "1:X":
        tmp_inp = inp
        tmp_tgt = inp_x
    elif strategy.upper() == "X:1":
        tmp_inp = inp_x
        tmp_tgt = inp
    else:
        raise ValueError(f"Strategy {strategy} not implemented. Please choose one of: ['1:X', 'X:1']")

    mask_trn = get_random_pixel_mask(inp.shape, mask_pixel_ratio=num_tst_ratio)

    return tmp_inp, tmp_tgt, mask_trn

train ¶

train(
    inp: NDArray,
    tgt: NDArray,
    mask_trn: NDArray,
    *,
    epochs: int,
    learning_rate: float = 0.001,
    optimizer: str = "adam",
    lower_limit: float | NDArray | None = None,
    restarts: int | None = None,
    accum_grads: bool = False
) -> dict[str, NDArray]

Train the denoiser using the Noise2Noise self-supervised approach.

Parameters:

inp (NDArray) –

The input data to be used for training. This should be a NumPy array of shape (N, H, W), where N is the number of samples, and H and W are the height and width of each sample, respectively.
tgt (NDArray) –

The target data to be used for training. This should be a NumPy array of shape (N, H, W), where N is the number of samples, and H and W are the height and width of each sample, respectively.
mask_trn (NDArray) –

The mask array indicating the pixels used for training.
epochs (int) –

The number of epochs to train the model.
learning_rate (float, default: 0.001 ) –

The learning rate for the optimizer. Default is 1e-3.
optimizer (str, default: 'adam' ) –

The optimization algorithm to be used for training. Default is "adam".
lower_limit (float | NDArray | None, default: None ) –

The lower limit for the input data. If provided, the input data will be clipped to this limit. Default is None.
restarts (int | None, default: None ) –

The number of times to restart the cosine annealing of the learning rate. If provided, the cosine annealing of the learning rate will be restarted the specified number of times. Default is None.
accum_grads (bool, default: False ) –

Whether to accumulate gradients over multiple batches. If True, gradients will be accumulated over multiple batches before updating the model parameters. Default is False.

Returns:

dict[str, NDArray] –

A dictionary containing the training losses.

Notes

This method uses the Noise2Noise self-supervised approach to train the denoiser. The input data is used to generate target data based on the specified strategy. The training process involves creating pairs of input and target data and then training the model to minimize the difference between the predicted and target data.

Source code in src/autoden/algorithms/noise2noise.py

def train(
    self,
    inp: NDArray,
    tgt: NDArray,
    mask_trn: NDArray,
    *,
    epochs: int,
    learning_rate: float = 1e-3,
    optimizer: str = "adam",
    lower_limit: float | NDArray | None = None,
    restarts: int | None = None,
    accum_grads: bool = False,
) -> dict[str, NDArray]:
    """
    Train the denoiser using the Noise2Noise self-supervised approach.

    Parameters
    ----------
    inp : NDArray
        The input data to be used for training. This should be a NumPy array of shape (N, H, W), where N is the
        number of samples, and H and W are the height and width of each sample, respectively.
    tgt : NDArray
        The target data to be used for training. This should be a NumPy array of shape (N, H, W), where N is the
        number of samples, and H and W are the height and width of each sample, respectively.
    mask_trn : NDArray
        The mask array indicating the pixels used for training.
    epochs : int
        The number of epochs to train the model.
    learning_rate : float, optional
        The learning rate for the optimizer. Default is 1e-3.
    optimizer : str, optional
        The optimization algorithm to be used for training. Default is "adam".
    lower_limit : float | NDArray | None, optional
        The lower limit for the input data. If provided, the input data will be clipped to this limit.
        Default is None.
    restarts : int | None, optional
        The number of times to restart the cosine annealing of the learning rate. If provided, the cosine annealing
        of the learning rate will be restarted the specified number of times. Default is None.
    accum_grads : bool, optional
        Whether to accumulate gradients over multiple batches. If True, gradients will be accumulated over multiple
        batches before updating the model parameters. Default is False.

    Returns
    -------
    dict[str, NDArray]
        A dictionary containing the training losses.

    Notes
    -----
    This method uses the Noise2Noise self-supervised approach to train the denoiser. The input data is used to
    generate target data based on the specified strategy. The training process involves creating pairs of input
    and target data and then training the model to minimize the difference between the predicted and target data.
    """
    if self.data_sb is None:
        self.data_sb = compute_scaling_selfsupervised(inp)

    # Rescale the datasets
    inp = inp * self.data_sb.scale_inp - self.data_sb.bias_inp
    tgt = tgt * self.data_sb.scale_tgt - self.data_sb.bias_tgt

    reg = self._get_regularization()
    losses = self._train_pixelmask_batched(
        inp=inp,
        tgt=tgt,
        mask_tst=mask_trn,
        epochs=epochs,
        learning_rate=learning_rate,
        optimizer=optimizer,
        regularizer=reg,
        lower_limit=lower_limit,
        restarts=restarts,
        accum_grads=accum_grads,
    )

    if self.verbose:
        self._plot_loss_curves(losses, f"Self-supervised {self.__class__.__name__} {optimizer.upper()}")

    return losses

N2V ¶

N2V(
    model: int | str | NetworkParams | Module | Mapping,
    data_scale_bias: DataScaleBias | None = None,
    reg_val: float | LossRegularizer | None = None,
    device: str = "cuda" if is_available() else "cpu",
    batch_size: int | None = None,
    augmentation: (
        str
        | Augmentation
        | Sequence[str | Augmentation]
        | None
    ) = None,
    save_epochs_dir: str | None = None,
    verbose: bool = True,
)

Bases: Denoiser

Self-supervised denoising from single images.

Parameters:

model (str | NetworkParams | Module | Mapping | None) –

Type of neural network to use or a specific network (or state) to use
data_scale_bias (DataScaleBias | None, default: None ) –

Scale and bias of the input data, by default None
reg_val (float | None, default: None ) –

Regularization value, by default 1e-5
device (str, default: 'cuda' if is_available() else 'cpu' ) –

Device to use, by default "cuda" if cuda is available, otherwise "cpu"
save_epochs_dir (str | None, default: None ) –

Directory where to save network states at each epoch. If None disabled, by default None
verbose (bool, default: True ) –

Whether to produce verbose output, by default True

Methods:

infer –

Inference, given an initial stack of images.
prepare_data –

Prepare input data for training.
train –

Self-supervised training.

Attributes:

n_channels_in (int) –

Returns the number of input channels of the model.
n_channels_out (int) –

Returns the number of output channels of the model.
n_dims (int) –

Returns the expected signal dimensions.

Source code in src/autoden/algorithms/denoiser.py

def __init__(
    self,
    model: int | str | NetworkParams | pt.nn.Module | Mapping,
    data_scale_bias: DataScaleBias | None = None,
    reg_val: float | LossRegularizer | None = None,
    device: str = "cuda" if pt.cuda.is_available() else "cpu",
    batch_size: int | None = None,
    augmentation: str | Augmentation | Sequence[str | Augmentation] | None = None,
    save_epochs_dir: str | None = None,
    verbose: bool = True,
) -> None:
    """Initialize the noise2noise method.

    Parameters
    ----------
    model : str | NetworkParams | pt.nn.Module | Mapping | None
        Type of neural network to use or a specific network (or state) to use
    data_scale_bias : DataScaleBias | None, optional
        Scale and bias of the input data, by default None
    reg_val : float | None, optional
        Regularization value, by default 1e-5
    device : str, optional
        Device to use, by default "cuda" if cuda is available, otherwise "cpu"
    save_epochs_dir : str | None, optional
        Directory where to save network states at each epoch.
        If None disabled, by default None
    verbose : bool, optional
        Whether to produce verbose output, by default True
    """
    if isinstance(model, int):
        if self.save_epochs_dir is None:
            raise ValueError("Directory for saving epochs not specified")

        model = load_model_state(self.save_epochs_dir, epoch_num=model)

    if isinstance(model, (str, NetworkParams, Mapping, pt.nn.Module)):
        self.model = create_network(model, device=device)
    else:
        raise ValueError(f"Invalid model {type(model)}")
    if verbose:
        get_num_parameters(self.model, verbose=True)

    # if augmentation is None:
    #     augmentation = []
    # elif isinstance(augmentation, str):
    #     augmentation = [augmentation.lower()]
    # elif isinstance(augmentation, Sequence):
    #     augmentation = [str(a).lower() for a in augmentation]

    self.data_sb = data_scale_bias

    self.reg_val = reg_val
    self.device = device
    self.batch_size = batch_size
    self.augmentation = augmentation
    self.save_epochs_dir = save_epochs_dir
    self.verbose = verbose

n_channels_in `property` ¶

n_channels_in: int

Returns the number of input channels of the model.

If the model is an instance of SerializableModel and has an init_params attribute containing the key "n_channels_in", this property returns its value. Otherwise, it defaults to 1.

Returns:

int –

The number of input channels.

n_channels_out `property` ¶

n_channels_out: int

Returns the number of output channels of the model.

If the model is an instance of SerializableModel and has an init_params attribute containing the key "n_channels_out", this property returns its value. Otherwise, it defaults to 1.

Returns:

int –

The number of output channels.

n_dims `property` ¶

n_dims: int

Returns the expected signal dimensions.

If the model is an instance of SerializableModel and has an init_params attribute containing the key "n_dims", this property returns its value. Otherwise, it defaults to 2.

Returns:

int –

The expected signal dimensions.

infer ¶

infer(
    inp: NDArray, channel_axis_dst: int | None = None
) -> NDArray

Inference, given an initial stack of images.

Parameters:

inp (NDArray) –

The input stack of images
channel_axis_dst (int | None, default: None ) –

The desired channel axis for the output. If None, the output will have the same channel axis as the input.

Returns:

NDArray –

The denoised stack of images

Source code in src/autoden/algorithms/denoiser.py

def infer(self, inp: NDArray, channel_axis_dst: int | None = None) -> NDArray:
    """Inference, given an initial stack of images.

    Parameters
    ----------
    inp : NDArray
        The input stack of images
    channel_axis_dst : int | None, optional
        The desired channel axis for the output. If None, the output will have the same channel axis as the input.

    Returns
    -------
    NDArray
        The denoised stack of images
    """
    # Rescale input
    if self.data_sb is not None:
        inp = inp * self.data_sb.scale_inp - self.data_sb.bias_inp

    channel_ax_inp = -self.n_dims - 1 if self.n_channels_in > 1 else None
    inp_t = data_to_tensor(inp, device=self.device, n_dims=self.n_dims, channel_axis=channel_ax_inp)

    self.model.eval()
    with pt.inference_mode():
        out_t: pt.Tensor = self.model(inp_t)
        output = out_t.squeeze(dim=(0, 1)).to("cpu").numpy()

    # Rescale output
    if self.data_sb is not None:
        output = (output + self.data_sb.bias_out) / self.data_sb.scale_out

    if channel_axis_dst is not None:
        output = self._move_output_channel_axis(output, channel_axis_dst)

    return output

prepare_data ¶

prepare_data(
    inp: NDArray,
    num_tst_ratio: float = 0.2,
    channel_axis: int | None = None,
) -> tuple[NDArray, list[int]]

Prepare input data for training.

Parameters:

inp (NDArray) –

The input data to be used for training. This should be a NumPy array of shape (N, H, W), where N is the number of samples, and H and W are the height and width of each sample, respectively.
num_tst_ratio (float, default: 0.2 ) –

The ratio of the input data to be used for testing. The remaining data will be used for training. Default is 0.2.
channel_axis (int | None, default: None ) –

The axis of the input array that corresponds to the spectral dimension. If None, the spectral dimension is assumed to not be present. Default is None.

Returns:

tuple[NDArray, NDArray, NDArray] –

A tuple containing: - The input data array. - The mask array indicating the training pixels.

Notes

This function generates input-target pairs based on the specified strategy. It also generates a mask array indicating the training pixels based on the provided ratio.

Source code in src/autoden/algorithms/noise2void.py

def prepare_data(
    self,
    inp: NDArray,
    num_tst_ratio: float = 0.2,
    channel_axis: int | None = None,
) -> tuple[NDArray, list[int]]:
    """
    Prepare input data for training.

    Parameters
    ----------
    inp : NDArray
        The input data to be used for training. This should be a NumPy array of shape (N, H, W), where N is the
        number of samples, and H and W are the height and width of each sample, respectively.
    num_tst_ratio : float, optional
        The ratio of the input data to be used for testing. The remaining data will be used for training.
        Default is 0.2.
    channel_axis : int | None, optional
        The axis of the input array that corresponds to the spectral dimension.
        If None, the spectral dimension is assumed to not be present.
        Default is None.

    Returns
    -------
    tuple[NDArray, NDArray, NDArray]
        A tuple containing:
        - The input data array.
        - The mask array indicating the training pixels.

    Notes
    -----
    This function generates input-target pairs based on the specified strategy. It also generates a mask array
    indicating the training pixels based on the provided ratio.
    """
    inp, channel_axis = self._prepare_channel_axis(inp, channel_axis)
    self._check_channel_axis_size(inp, channel_axis, "n_channels_in")
    self._check_channel_axis_size(inp, channel_axis, "n_channels_out")

    model_n_axes = self.n_dims + (channel_axis is not None)
    if inp.ndim < model_n_axes:
        raise ValueError(f"Target data should at least be of {model_n_axes + 1} dimensions, but its shape is {inp.shape}")

    batch_length = inp.shape[0]
    mask_tst = get_random_image_indices(batch_length, num_tst_ratio=num_tst_ratio)

    return inp, mask_tst

train ¶

train(
    inp: NDArray,
    tst_inds: Sequence[int] | NDArray,
    *,
    epochs: int,
    mask_shape: int | Sequence[int] | NDArray = 1,
    ratio_blind_spot: float = 0.015,
    learning_rate: float = 0.001,
    optimizer: str = "adam",
    lower_limit: float | NDArray | None = None
) -> dict[str, NDArray]

Self-supervised training.

Parameters:

inp (NDArray) –

The input images, which will also be targets
tst_inds (Sequence[int] | NDArray) –

The validation set indices (indices if Sequence[int])
epochs (int) –

Number of training epochs
mask_shape (int | Sequence[int] | NDArray, default: 1 ) –

Shape of the blind spot mask, by default 1.
ratio_blind_spot (float, default: 0.015 ) –

Ratio of the blind spot size to the total image size, by default 0.015.
learning_rate (float, default: 0.001 ) –

Learning rate for the optimizer, by default 1e-3.
optimizer (str, default: 'adam' ) –

Optimizer algorithm to use, by default "adam"
lower_limit (float | NDArray | None, default: None ) –

The lower limit for the input data. If provided, the input data will be clipped to this limit. Default is None.

Source code in src/autoden/algorithms/noise2void.py

def train(
    self,
    inp: NDArray,
    tst_inds: Sequence[int] | NDArray,
    *,
    epochs: int,
    mask_shape: int | Sequence[int] | NDArray = 1,
    ratio_blind_spot: float = 0.015,
    learning_rate: float = 1e-3,
    optimizer: str = "adam",
    lower_limit: float | NDArray | None = None,
) -> dict[str, NDArray]:
    """Self-supervised training.

    Parameters
    ----------
    inp : NDArray
        The input images, which will also be targets
    tst_inds : Sequence[int] | NDArray
        The validation set indices (indices if Sequence[int])
    epochs : int
        Number of training epochs
    mask_shape : int | Sequence[int] | NDArray
        Shape of the blind spot mask, by default 1.
    ratio_blind_spot : float
        Ratio of the blind spot size to the total image size, by default 0.015.
    learning_rate : float
        Learning rate for the optimizer, by default 1e-3.
    optimizer : str, optional
        Optimizer algorithm to use, by default "adam"
    lower_limit : float | NDArray | None, optional
        The lower limit for the input data. If provided, the input data will be clipped to this limit.
        Default is None.
    """
    batch_length = inp.shape[0]
    tst_inds = np.array(tst_inds, dtype=int)
    if np.any(tst_inds < 0) or np.any(tst_inds >= batch_length):
        raise ValueError(
            f"Each cross-validation index should be greater or equal than 0, and less than the number of images {batch_length}"
        )
    trn_inds = np.delete(np.arange(batch_length), obj=tst_inds)

    if self.data_sb is None:
        self.data_sb = compute_scaling_selfsupervised(inp)

    # Rescale the datasets
    inp = inp * self.data_sb.scale_inp - self.data_sb.bias_inp

    inp_trn = inp[trn_inds]
    inp_tst = inp[tst_inds]

    reg = self._get_regularization()
    losses = self._train_n2v_pixelmask_small(
        inp_trn,
        inp_tst,
        epochs=epochs,
        mask_shape=mask_shape,
        ratio_blind_spot=ratio_blind_spot,
        learning_rate=learning_rate,
        optimizer=optimizer,
        regularizer=reg,
        lower_limit=lower_limit,
    )

    if self.verbose:
        self._plot_loss_curves(losses, f"Self-supervised {self.__class__.__name__} {optimizer.upper()}")

    return losses

Supervised ¶

Supervised(
    model: int | str | NetworkParams | Module | Mapping,
    data_scale_bias: DataScaleBias | None = None,
    reg_val: float | LossRegularizer | None = None,
    device: str = "cuda" if is_available() else "cpu",
    batch_size: int | None = None,
    augmentation: (
        str
        | Augmentation
        | Sequence[str | Augmentation]
        | None
    ) = None,
    save_epochs_dir: str | None = None,
    verbose: bool = True,
)

Bases: Denoiser

Supervised denoising class.

Parameters:

model (str | NetworkParams | Module | Mapping | None) –

Type of neural network to use or a specific network (or state) to use
data_scale_bias (DataScaleBias | None, default: None ) –

Scale and bias of the input data, by default None
reg_val (float | None, default: None ) –

Regularization value, by default 1e-5
device (str, default: 'cuda' if is_available() else 'cpu' ) –

Device to use, by default "cuda" if cuda is available, otherwise "cpu"
save_epochs_dir (str | None, default: None ) –

Directory where to save network states at each epoch. If None disabled, by default None
verbose (bool, default: True ) –

Whether to produce verbose output, by default True

Methods:

infer –

Inference, given an initial stack of images.
prepare_data –

Prepare input data for training.
train –

Supervised training.

Attributes:

n_channels_in (int) –

Returns the number of input channels of the model.
n_channels_out (int) –

Returns the number of output channels of the model.
n_dims (int) –

Returns the expected signal dimensions.

Source code in src/autoden/algorithms/denoiser.py

def __init__(
    self,
    model: int | str | NetworkParams | pt.nn.Module | Mapping,
    data_scale_bias: DataScaleBias | None = None,
    reg_val: float | LossRegularizer | None = None,
    device: str = "cuda" if pt.cuda.is_available() else "cpu",
    batch_size: int | None = None,
    augmentation: str | Augmentation | Sequence[str | Augmentation] | None = None,
    save_epochs_dir: str | None = None,
    verbose: bool = True,
) -> None:
    """Initialize the noise2noise method.

    Parameters
    ----------
    model : str | NetworkParams | pt.nn.Module | Mapping | None
        Type of neural network to use or a specific network (or state) to use
    data_scale_bias : DataScaleBias | None, optional
        Scale and bias of the input data, by default None
    reg_val : float | None, optional
        Regularization value, by default 1e-5
    device : str, optional
        Device to use, by default "cuda" if cuda is available, otherwise "cpu"
    save_epochs_dir : str | None, optional
        Directory where to save network states at each epoch.
        If None disabled, by default None
    verbose : bool, optional
        Whether to produce verbose output, by default True
    """
    if isinstance(model, int):
        if self.save_epochs_dir is None:
            raise ValueError("Directory for saving epochs not specified")

        model = load_model_state(self.save_epochs_dir, epoch_num=model)

    if isinstance(model, (str, NetworkParams, Mapping, pt.nn.Module)):
        self.model = create_network(model, device=device)
    else:
        raise ValueError(f"Invalid model {type(model)}")
    if verbose:
        get_num_parameters(self.model, verbose=True)

    # if augmentation is None:
    #     augmentation = []
    # elif isinstance(augmentation, str):
    #     augmentation = [augmentation.lower()]
    # elif isinstance(augmentation, Sequence):
    #     augmentation = [str(a).lower() for a in augmentation]

    self.data_sb = data_scale_bias

    self.reg_val = reg_val
    self.device = device
    self.batch_size = batch_size
    self.augmentation = augmentation
    self.save_epochs_dir = save_epochs_dir
    self.verbose = verbose

n_channels_in `property` ¶

n_channels_in: int

Returns the number of input channels of the model.

If the model is an instance of SerializableModel and has an init_params attribute containing the key "n_channels_in", this property returns its value. Otherwise, it defaults to 1.

Returns:

int –

The number of input channels.

n_channels_out `property` ¶

n_channels_out: int

Returns the number of output channels of the model.

If the model is an instance of SerializableModel and has an init_params attribute containing the key "n_channels_out", this property returns its value. Otherwise, it defaults to 1.

Returns:

int –

The number of output channels.

n_dims `property` ¶

n_dims: int

Returns the expected signal dimensions.

If the model is an instance of SerializableModel and has an init_params attribute containing the key "n_dims", this property returns its value. Otherwise, it defaults to 2.

Returns:

int –

The expected signal dimensions.

infer ¶

infer(
    inp: NDArray, channel_axis_dst: int | None = None
) -> NDArray

Inference, given an initial stack of images.

Parameters:

inp (NDArray) –

The input stack of images
channel_axis_dst (int | None, default: None ) –

The desired channel axis for the output. If None, the output will have the same channel axis as the input.

Returns:

NDArray –

The denoised stack of images

Source code in src/autoden/algorithms/denoiser.py

def infer(self, inp: NDArray, channel_axis_dst: int | None = None) -> NDArray:
    """Inference, given an initial stack of images.

    Parameters
    ----------
    inp : NDArray
        The input stack of images
    channel_axis_dst : int | None, optional
        The desired channel axis for the output. If None, the output will have the same channel axis as the input.

    Returns
    -------
    NDArray
        The denoised stack of images
    """
    # Rescale input
    if self.data_sb is not None:
        inp = inp * self.data_sb.scale_inp - self.data_sb.bias_inp

    channel_ax_inp = -self.n_dims - 1 if self.n_channels_in > 1 else None
    inp_t = data_to_tensor(inp, device=self.device, n_dims=self.n_dims, channel_axis=channel_ax_inp)

    self.model.eval()
    with pt.inference_mode():
        out_t: pt.Tensor = self.model(inp_t)
        output = out_t.squeeze(dim=(0, 1)).to("cpu").numpy()

    # Rescale output
    if self.data_sb is not None:
        output = (output + self.data_sb.bias_out) / self.data_sb.scale_out

    if channel_axis_dst is not None:
        output = self._move_output_channel_axis(output, channel_axis_dst)

    return output

prepare_data ¶

prepare_data(
    inp: NDArray,
    tgt: NDArray,
    num_tst_ratio: float = 0.2,
    strategy: Literal[
        "pixel-mask", "self-similar"
    ] = "pixel-mask",
    channel_axis: int | None = None,
) -> tuple[NDArray, NDArray, NDArray | list[int]]

Prepare input data for training.

Parameters:

inp (NDArray) –

The input data to be used for training. This should be a NumPy array of shape (N, [D, H], W), where N is the number of samples, and D, H and W are the depth, height and width of each sample, respectively.
tgt (NDArray) –

The target data to be used for training. This should be a NumPy array of shape (N, [D, H], W), where N is the number of samples, and D, H and W are the depth, height and width of each sample, respectively.
num_tst_ratio (float, default: 0.2 ) –

The ratio of the input data to be used for testing. The remaining data will be used for training. Default is 0.2.
strategy (str, default: 'pixel-mask' ) –

The strategy to be used for creating training and testing sets. The available strategies are: - "pixel-mask": Use randomly chosen pixels in the images as test set. - "self-similar": Use entire randomly chosen images as test set. Default is "pixel-mask".
channel_axis (int | None, default: None ) –

The axis of the target array that corresponds to the spectral dimension. If None, the spectral dimension is assumed to not be present. Default is None.

Returns:

tuple[NDArray, NDArray, NDArray] –

A tuple containing: - The input data array. - The target data array. - Either the mask array indicating the testing pixels or the list of test indices.

Source code in src/autoden/algorithms/supervised.py

def prepare_data(
    self,
    inp: NDArray,
    tgt: NDArray,
    num_tst_ratio: float = 0.2,
    strategy: Literal["pixel-mask", "self-similar"] = "pixel-mask",
    channel_axis: int | None = None,
) -> tuple[NDArray, NDArray, NDArray | list[int]]:
    """
    Prepare input data for training.

    Parameters
    ----------
    inp : NDArray
        The input data to be used for training. This should be a NumPy array of shape (N, [D, H], W), where N is the
        number of samples, and D, H and W are the depth, height and width of each sample, respectively.
    tgt : NDArray
        The target data to be used for training. This should be a NumPy array of shape (N, [D, H], W), where N is the
        number of samples, and D, H and W are the depth, height and width of each sample, respectively.
    num_tst_ratio : float, optional
        The ratio of the input data to be used for testing. The remaining data will be used for training.
        Default is 0.2.
    strategy : str, optional
        The strategy to be used for creating training and testing sets. The available strategies are:
        - "pixel-mask": Use randomly chosen pixels in the images as test set.
        - "self-similar": Use entire randomly chosen images as test set.
        Default is "pixel-mask".
    channel_axis : int | None, optional
        The axis of the target array that corresponds to the spectral dimension.
        If None, the spectral dimension is assumed to not be present.
        Default is None.

    Returns
    -------
    tuple[NDArray, NDArray, NDArray]
        A tuple containing:
        - The input data array.
        - The target data array.
        - Either the mask array indicating the testing pixels or the list of test indices.
    """
    inp, channel_axis_inp = self._prepare_channel_axis(inp, channel_axis)
    self._check_channel_axis_size(inp, channel_axis_inp, "n_channels_in")

    model_inp_axes = self.n_dims + (self.n_channels_in > 1)
    if inp.ndim < model_inp_axes:
        raise ValueError(f"Input data should at least be of {model_inp_axes} dimensions, but its shape is {inp.shape}")

    tgt, channel_axis_tgt = self._prepare_channel_axis(tgt, channel_axis)
    self._check_channel_axis_size(tgt, channel_axis_tgt, "n_channels_out")

    model_tgt_axes = self.n_dims + (self.n_channels_out > 1)
    if tgt.ndim < model_tgt_axes:
        raise ValueError(f"Target data should at least be of {model_tgt_axes} dimensions, but its shape is {tgt.shape}")

    batch_length = inp.shape[0]
    if tgt.ndim == (inp.ndim - 1):
        tgt = np.tile(tgt[None, ...], [batch_length, *np.ones_like(tgt.shape)])

    if inp.shape[-self.n_dims :] != tgt.shape[-self.n_dims :]:
        raise ValueError(
            f"Input and target data must have the same shape. Input shape: {inp.shape}, Target shape: {tgt.shape}"
        )

    if strategy.lower() == "pixel-mask":
        mask_tst = get_random_pixel_mask(inp.shape, mask_pixel_ratio=num_tst_ratio)
    elif strategy.lower() == "self-similar":
        mask_tst = get_random_image_indices(batch_length, num_tst_ratio=num_tst_ratio)
    else:
        raise ValueError(f"Strategy {strategy} not implemented. Please choose one of: ['pixel-mask', 'self-similar']")

    return inp, tgt, mask_tst

train ¶

train(
    inp: NDArray,
    tgt: NDArray,
    tst_inds: Sequence[int] | NDArray,
    *,
    epochs: int,
    learning_rate: float = 0.001,
    optimizer: str = "adam",
    lower_limit: float | NDArray | None = None,
    restarts: int | None = None,
    accum_grads: bool = False
) -> dict[str, NDArray]

Supervised training.

Parameters:

inp (NDArray) –

The input images
tgt (NDArray) –

The target images
tst_inds (Sequence[int] | NDArray) –

The validation set indices (either image indices if Sequence[int] or pixel indices if NDArray)
epochs (int) –

Number of training epochs
learning_rate (float, default: 0.001 ) –

The learning rate for the optimizer. Default is 1e-3.
optimizer (str, default: 'adam' ) –

The optimization algorithm to be used for training. Default is "adam".
lower_limit (float | NDArray | None, default: None ) –

The lower limit for the input data. If provided, the input data will be clipped to this limit. Default is None.
restarts (int | None, default: None ) –

The number of times to restart the cosine annealing of the learning rate. If provided, the cosine annealing of the learning rate will be restarted the specified number of times. Default is None.
accum_grads (bool, default: False ) –

Whether to accumulate gradients over multiple batches. If True, gradients will be accumulated over multiple batches before updating the model parameters. Default is False.

Returns:

dict[str, NDArray] –

A dictionary containing the training history, including the loss and validation loss over the epochs.

Source code in src/autoden/algorithms/supervised.py

def train(
    self,
    inp: NDArray,
    tgt: NDArray,
    tst_inds: Sequence[int] | NDArray,
    *,
    epochs: int,
    learning_rate: float = 1e-3,
    optimizer: str = "adam",
    lower_limit: float | NDArray | None = None,
    restarts: int | None = None,
    accum_grads: bool = False,
) -> dict[str, NDArray]:
    """Supervised training.

    Parameters
    ----------
    inp : NDArray
        The input images
    tgt : NDArray
        The target images
    tst_inds : Sequence[int] | NDArray
        The validation set indices (either image indices if Sequence[int] or pixel indices if NDArray)
    epochs : int
        Number of training epochs
    learning_rate : float, optional
        The learning rate for the optimizer. Default is 1e-3.
    optimizer : str, optional
        The optimization algorithm to be used for training. Default is "adam".
    lower_limit : float | NDArray | None, optional
        The lower limit for the input data. If provided, the input data will be clipped to this limit.
        Default is None.
    restarts : int | None, optional
        The number of times to restart the cosine annealing of the learning rate. If provided, the cosine annealing
        of the learning rate will be restarted the specified number of times. Default is None.
    accum_grads : bool, optional
        Whether to accumulate gradients over multiple batches. If True, gradients will be accumulated over multiple
        batches before updating the model parameters. Default is False.

    Returns
    -------
    dict[str, NDArray]
        A dictionary containing the training history, including the loss and validation loss over the epochs.
    """
    num_imgs = inp.shape[0]

    if self.data_sb is None:
        self.data_sb = compute_scaling_supervised(inp, tgt)

    # Rescale the datasets
    inp = inp * self.data_sb.scale_inp - self.data_sb.bias_inp
    tgt = tgt * self.data_sb.scale_tgt - self.data_sb.bias_tgt

    reg = self._get_regularization()

    if isinstance(tst_inds, Sequence):
        tst_inds = np.array(tst_inds, dtype=int)
        if np.any(tst_inds < 0) or np.any(tst_inds >= num_imgs):
            raise ValueError(
                "Each cross-validation index should be greater or equal than 0,"
                f" and less than the number of images {num_imgs}"
            )
        trn_inds = np.delete(np.arange(num_imgs), obj=tst_inds)

        # Create datasets
        dset_trn = (inp[trn_inds], tgt[trn_inds])
        dset_tst = (inp[tst_inds], tgt[tst_inds])

        losses = self._train_selfsimilar_batched(
            dset_trn,
            dset_tst,
            epochs=epochs,
            learning_rate=learning_rate,
            optimizer=optimizer,
            regularizer=reg,
            lower_limit=lower_limit,
            restarts=restarts,
            accum_grads=accum_grads,
        )
    elif isinstance(tst_inds, np.ndarray):
        losses = self._train_pixelmask_batched(
            inp,
            tgt,
            tst_inds,
            epochs=epochs,
            learning_rate=learning_rate,
            optimizer=optimizer,
            regularizer=reg,
            lower_limit=lower_limit,
            restarts=restarts,
            accum_grads=accum_grads,
        )
    else:
        raise ValueError(
            "`tst_inds` should either be a Sequence[int] or NDArray. Please use the the `prepare_data` function if unsure."
        )

    if self.verbose:
        self._plot_loss_curves(losses, f"Supervised {optimizer.upper()}")

    return losses

autoden ¶

DIP ¶

n_channels_in property ¶

n_channels_out property ¶

n_dims property ¶

infer ¶

prepare_data ¶

train ¶

N2N ¶

n_channels_in property ¶

n_channels_out property ¶

n_dims property ¶

infer ¶

prepare_data ¶

train ¶

N2V ¶

n_channels_in property ¶

n_channels_out property ¶

n_dims property ¶

infer ¶

prepare_data ¶

train ¶

Supervised ¶

n_channels_in property ¶

n_channels_out property ¶

n_dims property ¶

infer ¶

prepare_data ¶

train ¶

n_channels_in `property` ¶

n_channels_out `property` ¶

n_dims `property` ¶

n_channels_in `property` ¶

n_channels_out `property` ¶

n_dims `property` ¶

n_channels_in `property` ¶

n_channels_out `property` ¶

n_dims `property` ¶

n_channels_in `property` ¶

n_channels_out `property` ¶

n_dims `property` ¶