espnet2.layers.global_mvn.GlobalMVN

source

class espnet2.layers.global_mvn.GlobalMVN(stats_file: Path | str, norm_means: bool = True, norm_vars: bool = True, eps: float = 1e-20)

Bases: AbsNormalize, InversibleInterface

Apply global mean and variance normalization.

This class implements global mean and variance normalization, which can be used to normalize features by their mean and variance across a dataset. It can read the statistics from a specified .npy or .npz file, and normalization can be applied based on the specified parameters.

TODO(kamo): Make this class portable somehow.

stats_file

Path to the statistics file containing mean and variance.

• Type: Path

norm_means

Whether to apply mean normalization. Defaults to True.

• Type: bool

norm_vars

Whether to apply variance normalization. Defaults to True.

• Type: bool

eps

Small constant to prevent division by zero. Defaults to 1.0e-20.

• Type: float

mean

Mean values loaded from the statistics file.

• Type: torch.Tensor

std

Standard deviation values loaded from the statistics file.

• Type: torch.Tensor

• Parameters:

  • stats_file – npy file containing statistics for normalization.
  • norm_means – Apply mean normalization (default: True).
  • norm_vars – Apply variance normalization (default: True).
  • eps – Small constant to prevent division by zero (default: 1.0e-20).

########### Examples

>>> global_mvn = GlobalMVN("path/to/stats_file.npy")
>>> normalized_tensor, ilens = global_mvn(input_tensor, input_lengths)

>>> denormalized_tensor, ilens = global_mvn.inverse(normalized_tensor, ilens)

Initialize internal Module state, shared by both nn.Module and ScriptModule.

extra_repr()

Generate a string representation of the GlobalMVN instance.

This method provides a concise representation of the instance, including the path to the statistics file and the normalization settings for means and variances. It is primarily used for debugging and logging purposes.

• Returns: A string representation of the GlobalMVN instance, showing the stats file, norm_means, and norm_vars attributes.
• Return type: str

########### Examples

>>> mvn = GlobalMVN("path/to/stats.npy", norm_means=True, norm_vars=False)
>>> print(mvn.extra_repr())
stats_file=path/to/stats.npy, norm_means=True, norm_vars=False

forward(x: Tensor, ilens: Tensor | None = None) → Tuple[Tensor, Tensor]

Forward function

This method applies global mean and variance normalization to the input tensor x. It adjusts the input based on the computed mean and standard deviation, which are derived from the statistics loaded from the specified stats_file.

• Parameters:
  • x (torch.Tensor) – Input tensor of shape (B, L, …), where B is the batch size and L is the sequence length.
  • ilens (torch.Tensor , optional) – Tensor of shape (B,) that contains the actual lengths of each sequence in the batch. If not provided, it defaults to the length of x.
• Returns: A tuple containing: : - The normalized tensor of the same shape as x.
  • The tensor ilens that represents the lengths of each sequence.
• Return type: Tuple[torch.Tensor, torch.Tensor]

########### Examples

>>> mvn = GlobalMVN("path/to/stats.npy")
>>> x = torch.randn(2, 5, 10)  # Example input
>>> ilens = torch.tensor([5, 3])  # Example lengths
>>> normalized_x, normalized_ilens = mvn.forward(x, ilens)

inverse(x: Tensor, ilens: Tensor | None = None) → Tuple[Tensor, Tensor]

Apply global mean and variance normalization.

This class implements global mean and variance normalization, which can be used to standardize the input data based on precomputed statistics. The normalization can be applied to both the means and variances, with an optional small epsilon value to prevent division by zero.

TODO(kamo): Make this class portable somehow.

stats_file

Path to the .npy file containing the statistics.

• Type: Path

norm_means

Whether to apply mean normalization.

• Type: bool

norm_vars

Whether to apply variance normalization.

• Type: bool

eps

Small value to prevent division by zero.

• Type: float

mean

Mean values for normalization.

• Type: torch.Tensor

std

Standard deviation values for normalization.

• Type: torch.Tensor

• Parameters:

  • stats_file – npy file containing the statistics for normalization.
  • norm_means – Apply mean normalization (default: True).
  • norm_vars – Apply variance normalization (default: True).
  • eps – Small value to prevent division by zero (default: 1.0e-20).

########### Examples

>>> global_mvn = GlobalMVN(stats_file='stats.npy')
>>> normalized_tensor, lengths = global_mvn.forward(input_tensor)
>>> original_tensor, lengths = global_mvn.inverse(normalized_tensor)

• Raises:
  • ValueError – If the provided statistics file cannot be loaded or is
  • invalid. –