Quantifiers

Quantifiers are used to specify rules for how a sequence of transformations or quantifiers should be applied.

Each quantifier class is a subclass of the more generic Quantifier base class, which provides a basic interface that can also be used to write custom quantifiers, though there is rarely a need for this.

As with transformations, Sigment offers a familiar interface for quantifiers, taking inspiration from popular augmentation libraries such as imgaug and nlpaug.

Available quantifiers

In the below quantifiers, the steps argument is a list of Transform and/or Quantifier objects, specifying a sequence of transformations or quantifiers to be applied.

Pipeline

class sigment.quantifiers.Pipeline(steps, random_order=False, random_state=None)[source]

Sequentially executes each transformation or quantifier step.

Sometimes

class sigment.quantifiers.Sometimes(steps, p=0.5, random_order=False, random_state=None)[source]

Probabilistically applies the provided transformation or quantifier steps.

Parameters
p: float [0 ≤ p ≤ 1]

The probability of executing the transformations or quantifiers.

Some Of

class sigment.quantifiers.SomeOf(steps, n, random_order=False, random_state=None)[source]

Randomly applies a number of the provided transformation or quantifier steps.

Parameters
n: int [n > 0] or (int, int)

The number of transformation or quantifier steps to apply.

Notes

  • The chosen steps will still be applied in the same order they were defined by default.

One Of

class sigment.quantifiers.OneOf(steps, random_order=False, random_state=None)[source]

Randomly applies a single step from the provided transformation or quantifier steps.

Notes

  • This is a special case of the SomeOf quantifier, with n=1.

Using quantifiers

Each quantifier class comes with a number of methods that can be used to apply the transformations to either a numpy.ndarray or WAV file.

All quantifiers accept the random_order and random_state parameters, inherited from the Quantifier base class described below.

class sigment.quantifiers.Quantifier(steps, random_order=False, random_state=None)[source]

Specifies how to execute transformation or quantifier steps.

Note

As this is a base class, it should not be directly instantiated.

Parameters
steps: List[Transform, Quantifier]

A collection of transformation or quantifier steps to apply.

random_order: bool

Whether or not to randomize the order of execution of steps.

random_state: numpy.RandomState, int, optional

A random state object or seed for reproducible randomness.

__call__(self, X, sr=None)[source]

Runs the transformations or quantifiers on a provided input signal.

Parameters
X: numpy.ndarray [shape (T,) or (1xT) for mono, (2xT) for stereo]

The input signal to transform.

sr: int [sr > 0], optional

The sample rate for the input signal.

Note

Not required if using transformations that do not require a sample rate.

Returns
transformed: numpy.ndarray [shape (T,) for mono, (2xT) for stereo]

The transformed signal, clipped so that it fits into the \([-1,1]\) range required for 32-bit floating point WAVs.

Note

If a mono signal X of shape (1xT) was used, the output is reshaped to (T,).

Examples

>>> import numpy as np
>>> from sigment.quantifiers import SomeOf
>>> from sigment.transforms import GaussianWhiteNoise, PitchShift, EdgeCrop
>>> # Create an example stereo signal.
>>> X = np.array([
>>>     [0.325, 0.53 , 0.393, 0.211],
>>>     [0.21 , 0.834, 0.022, 0.38 ]
>>> ])
>>> # Use the SomeOf quantifier to run only 1 to 2 of the transformations.
>>> transform = SomeOf([
>>>     GaussianWhiteNoise(scale=(0.05, 0.15)),
>>>     PitchShift(n_steps=(-1., 1.)),
>>>     EdgeCrop(side='start', crop_size=(0.02, 0.05))
>>> ], n=(1, 2))
>>> # Run the __call__ method on the quantifier object to transform X.
>>> # NOTE: Pitch shifting requires a sample rate when called, therefore
>>> #   we must call the quantifier with a specified sample rate parameter.
>>> X_transform = transform(X, sr=10)
generate(self, X, n, sr=None)[source]

Runs the transformations or quantifiers on a provided input signal, producing multiple augmented copies of the input signal.

Parameters
X: numpy.ndarray [shape (T,) or (1xT) for mono, (2xT) for stereo]

The input signal to transform.

n: int [n > 0]

Number of augmented copies of X to generate.

sr: int [sr > 0], optional

The sample rate for the input signal.

Note

Not required if not using transformations that require a sample rate.

Returns
augmented: List[numpy.ndarray] or numpy.ndarray

The augmented copies (or copy if n=1) of the signal X, clipped so that they fit into the \([-1,1]\) range required for 32-bit floating point WAVs.

Note

If a mono signal X of shape (1xT) was used, the output is reshaped to (T,).

Examples

>>> import numpy as np
>>> from sigment.quantifiers import Sometimes, OneOf
>>> from sigment.transforms import LinearFade, GaussianWhiteNoise
>>> # Create an example stereo signal.
>>> X = np.array([
>>>     [0.325, 0.53 , 0.393, 0.211],
>>>     [0.21 , 0.834, 0.022, 0.38 ]
>>> ])
>>> # Use the Sometimes and OneOf quantifiers to sometimes (with probability 0.65)
>>> # apply a Gaussian white noise transformation and either a fade-in or fade-out.
>>> transform = Sometimes([
>>>     GaussianWhiteNoise(scale=(0.05, 0.15)),
>>>     OneOf([
>>>         LinearFade(direction='in', fade_size=(0.05, 0.1)),
>>>         LinearFade(direction='out', fade_size=(0.05, 0.1))
>>>     ])
>>> ], p=0.65)
>>> # Generate 5 augmented versions of X, using the quantifier object.
>>> Xs_transform = transform.generate(X, n=5)
apply_to_wav(self, source, out=None)

Applies the augmentation to the provided input WAV file and writes the resulting signal back to a WAV file.

Note

The resulting signal is always clipped so that it fits into the \([-1,1]\) range required for 32-bit floating point WAVs.

Parameters
source: str, Path or path-like

Path to the input WAV file.

out: str, Path or path-like

Output WAV path for the augmented signal.

Warning

If out is set to None (which is the default) or the same as source, the input WAV file will be overwritten!

Examples

>>> from sigment import *
>>> # Create a transformation or quantifier object.
>>> transform = ...
>>> # Apply the transformation to the input WAV file and write it to the output file
>>> transform.apply_to_wav('in.wav', 'out.wav')
generate_from_wav(self, source, n=1)

Applies the augmentation to the provided input WAV file and returns a numpy.ndarray.

Parameters
source: str, Path or path-like

Path to the input WAV file.

n: int [n > 0]

Number of augmented versions of the source signal to generate.

Returns
augmented: List[numpy.ndarray] or numpy.ndarray

The augmented versions (or version if n=1) of the source signal, clipped so that they fit into the \([-1,1]\) range required for 32-bit floating point WAVs.

Examples

>>> from sigment import *
>>> # Create a transformation or quantifier object.
>>> transform = ...
>>> # Generate 5 augmented versions of the signal data from 'signal.wav' as numpy.ndarrays.
>>> transformed = transform.generate_from_wav('signal.wav', n=5)