Skip to content

Normalization Config

Source

Pydantic models for normalization strategies.

MeanStdConfig

Bases: BaseModel

Mean and standard deviation normalization configuration.

Holds mean and standard deviation statistics for input and target, used to normalize data. Each statistic can be a single float (applied globally to all channels) or a list of floats (one per channel). If not provided, statistics can be computed automatically.

Attributes:

  • name (Literal['mean_std']) –

    Identifier for the mean-std normalization scheme.

  • per_channel (bool) –

    When True (default), statistics are computed independently for each channel. When False, a single statistic is computed across all channels.

  • skip_target (bool) –

    When True, target normalization is skipped and target statistics are not computed. Default is False.

  • input_means (float | list[float] | None) –

    Means for input normalization. None for automatic computation.

  • input_stds (float | list[float] | None) –

    Standard deviations for input normalization. None for automatic computation.

  • target_means (float | list[float] | None) –

    Means for target normalization. None for automatic computation.

  • target_stds (float | list[float] | None) –

    Standard deviations for target normalization. None for automatic computation.

needs_computation()

Check if statistics need to be computed.

Returns:

  • bool –

    True if input statistics are missing, False otherwise.

set_input_stats(means, stds)

Set input means and stds together to avoid validation errors.

Parameters:

  • means (list[float]) –

    Mean values per channel.

  • stds (list[float]) –

    Standard deviation values per channel.

set_target_stats(means, stds)

Set target means and stds together to avoid validation errors.

Parameters:

  • means (list[float]) –

    Mean values per channel.

  • stds (list[float]) –

    Standard deviation values per channel.

target_needs_computation()

Check if target statistics need to be computed.

Returns:

  • bool –

    True if target statistics need to be computed, False otherwise.

validate_global_stats_single_element(v, info) classmethod

Validate stats length against the per_channel parameter.

Parameters:

  • v (OptionalFloatStats) –

    Value to validate.

  • info (ValidationInfo) –

    Validated values.

Returns:

  • OptionalFloatStats –

    Validate value.

validate_means_stds()

Validate that means and stds are provided in pairs or set to None.

Returns:

  • Self –

    The validated model instance.

Raises:

  • ValueError –

    If only one of means or stds is provided for input or target, or if paired lists have mismatched lengths.

validate_size(n_input_channels, n_output_channels)

Validate that statistics sizes match the number of channels.

If target normalization is skipped, only input statistics are validated against the number of input channels, and target statistics are not validated.

Parameters:

  • n_input_channels (int) –

    The number of input channels to validate against.

  • n_output_channels (int) –

    The number of output channels to validate against.

Raises:

  • ValueError –

    If any provided statistics list does not match the expected size.

warn_targets_not_applicable()

Warn users when target statistics are provided but skip_target is True.

Returns:

  • Self –

    The validated model instance.

MinMaxConfig

Bases: BaseModel

Min-max normalization configuration.

Stores minimum and maximum statistics for scaling data into a desired range. Each statistic can be a single float (applied globally to all channels) or a list of floats (one per channel). If not provided, statistics can be computed automatically.

Attributes:

  • name (Literal['min_max']) –

    Identifier for min-max normalization.

  • per_channel (bool, default=True) –

    When True, statistics are computed independently for each channel. When False, a single statistic is computed across all channels.

  • skip_target (bool, default=False) –

    When True, target normalization is skipped and target statistics are not computed.

  • input_mins (float | list[float] | None) –

    Minimum values for input normalization. None for automatic computation.

  • input_maxes (float | list[float] | None) –

    Maximum values for input normalization. None for automatic computation.

  • target_mins (float | list[float] | None) –

    Minimum values for target normalization. None for automatic computation.

  • target_maxes (float | list[float] | None) –

    Maximum values for target normalization. None for automatic computation.

needs_computation()

Check if min/max values need to be computed.

Returns:

  • bool –

    True if input statistics are missing, False otherwise.

set_input_range(mins, maxes)

Set input mins and maxes together to avoid validation errors.

Parameters:

  • mins (list[float]) –

    Minimum values per channel.

  • maxes (list[float]) –

    Maximum values per channel.

set_target_range(mins, maxes)

Set target mins and maxes together to avoid validation errors.

Parameters:

  • mins (list[float]) –

    Minimum values per channel.

  • maxes (list[float]) –

    Maximum values per channel.

target_needs_computation()

Check if target min/max values need to be computed.

Returns:

  • bool –

    True if target statistics are missing, False otherwise.

validate_global_stats_single_element(v, info) classmethod

Validate stats length against the per_channel parameter.

Parameters:

  • v (OptionalFloatStats) –

    Value to validate.

  • info (ValidationInfo) –

    Validated values.

Returns:

  • OptionalFloatStats –

    Validate value.

validate_mins_maxes()

Validate that mins and maxes are provided in pairs or both None.

Returns:

  • Self –

    The validated model instance.

Raises:

  • ValueError –

    If only one of mins or maxes is provided for input or target, or if paired lists have mismatched lengths.

validate_size(n_input_channels, n_output_channels)

Validate that statistics sizes match the number of channels.

If target normalization is skipped, only input statistics are validated against the number of input channels, and target statistics are not validated.

Parameters:

  • n_input_channels (int) –

    The number of input channels to validate against.

  • n_output_channels (int) –

    The number of output channels to validate against.

Raises:

  • ValueError –

    If any provided statistics list does not match the expected size.

warn_targets_not_applicable()

Warn users when target mins/maxes are provided but skip_target is True.

Returns:

  • Self –

    The validated model instance.

NoNormConfig

Bases: BaseModel

No normalization configuration.

Indicates that no normalization should be applied.

Attributes:

  • name (Literal['none']) –

    Identifier for no normalization scheme.

needs_computation()

Check if statistics need to be computed.

Returns:

  • bool –

    Always False, as no statistics are required.

target_needs_computation()

Check if target statistics need to be computed.

Returns:

  • bool –

    Always False, as no statistics are required.

validate_size(*args, **kwargs)

No validation needed.

Parameters:

  • *args (Any, default: () ) –

    Parameters will be ignored.

  • **kwargs (Any, default: {} ) –

    Parameters will be ignored.

QuantileConfig

Bases: BaseModel

Quantile normalization configuration.

Normalizes data using quantile-based range scaling. Quantile levels can be specified as a single value (applied to all channels) or a list (one per channel). If not provided, quantile values can be computed automatically.

Attributes:

  • name (Literal['quantile']) –

    Identifier for quantile normalization.

  • per_channel (bool, default=True) –

    When True, quantile values are computed independently for each channel. When False, a single quantile is computed across all channels.

  • skip_target (bool, default=False) –

    When True, target normalization is skipped and target quantile values are not computed.

  • lower_quantiles (float | list[float]) –

    Lower quantile level(s). Values must be in [0, 1).

  • upper_quantiles (float | list[float]) –

    Upper quantile level(s). Values must be in (0, 1].

  • input_lower_quantile_values (float | list[float] | None) –

    Computed lower quantile values for input.

  • input_upper_quantile_values (float | list[float] | None) –

    Computed upper quantile values for input.

  • target_lower_quantile_values (float | list[float] | None) –

    Computed lower quantile values for target.

  • target_upper_quantile_values (float | list[float] | None) –

    Computed upper quantile values for target.

needs_computation()

Check if quantile values need to be computed.

Returns:

  • bool –

    True if quantile values need to be computed.

set_input_quantile_values(lower, upper)

Set input quantile values together to avoid validation errors.

Parameters:

  • lower (list[float]) –

    Lower quantile values per channel.

  • upper (list[float]) –

    Upper quantile values per channel.

set_target_quantile_values(lower, upper)

Set target quantile values together to avoid validation errors.

Parameters:

  • lower (list[float]) –

    Lower quantile values per channel.

  • upper (list[float]) –

    Upper quantile values per channel.

target_needs_computation()

Check if target quantile values need to be computed.

Returns:

  • bool –

    True if target quantile values need to be computed.

validate_global_stats_single_element(v, info) classmethod

Validate stats length against the per_channel parameter.

Parameters:

  • v (OptionalFloatStats) –

    Value to validate.

  • info (ValidationInfo) –

    Validated values.

Returns:

  • OptionalFloatStats –

    Validate value.

validate_quantile_levels()

Validate quantile levels are in valid range and properly ordered.

Returns:

  • Self –

    The validated model instance.

validate_quantile_values()

Validate that computed quantile value lists are provided in pairs.

Returns:

  • Self –

    The validated model instance.

validate_size(n_input_channels, n_output_channels)

Validate that statistics sizes match the number of channels.

If target normalization is skipped, only input statistics are validated against the number of input channels, and target statistics are not validated.

Parameters:

  • n_input_channels (int) –

    The number of input channels to validate against.

  • n_output_channels (int) –

    The number of output channels to validate against.

Raises:

  • ValueError –

    If any provided statistics list does not match the expected size.

warn_targets_not_applicable()

Warn users when target quantiles are provided but skip_target is True.

Returns:

  • Self –

    The validated model instance.