ml4gw.transforms.whitening

Classes

`FixedMinimumPhaseWhiten`(num_channels, ...[, ...])	Whiten timeseries with a fitted causal minimum-phase FIR filter.
`FixedWhiten`(num_channels, kernel_length, ...)	Transform that whitens timeseries by a fixed power spectral density that's determined by calling the `.fit` method.
`MinimumPhaseWhiten`(fduration, sample_rate[, ...])	Whiten timeseries with a dynamic causal minimum-phase FIR filter.
`Whiten`(fduration, sample_rate[, highpass, ...])	Normalize the frequency content of timeseries data by a provided power spectral density, such that if the timeseries are sampled from the same distribution as the PSD the normalized power will be approximately unity across all frequency bins.

class ml4gw.transforms.whitening.FixedMinimumPhaseWhiten(num_channels, fduration, sample_rate, dtype=torch.float64)

Bases: FittableSpectralTransform

Whiten timeseries with a fitted causal minimum-phase FIR filter.

This transform does not subtract the mean of the complete input segment because that operation depends on future samples.

Parameters:

num_channels (int) -- Number of channels to whiten.
fduration (float) -- Length of the causal whitening filter in seconds.
sample_rate (float) -- Sampling rate of input timeseries in Hz.
dtype (dtype) -- Datatype used to store the fitted filter.

fit(*background, fftlength=None, highpass=None, lowpass=None, overlap=None)

Fit a minimum-phase whitening filter to background data.

Parameters:

*background (Float[Tensor, 'time'] | Float[Tensor, 'frequency']) -- One time- or frequency-domain tensor per channel. Inputs are interpreted as one-sided PSDs when fftlength is None; otherwise Welch PSDs are estimated from the timeseries. Unscaled physical PSDs may require double precision to avoid underflow.
fftlength (float | None) -- Length in seconds of Welch frames used for time-domain input.
highpass (float | None) -- Optional highpass frequency in Hz. Applied by truncate_inverse_power_spectrum() before minimum-phase factorization.
lowpass (float | None) -- Optional lowpass frequency in Hz. Applied by truncate_inverse_power_spectrum() before minimum-phase factorization.
overlap (float | None) -- Overlap in seconds between Welch frames. Defaults to half of fftlength.

Return type:

None

forward(X, crop=True)

Apply the fitted causal filter.

Parameters:

X (Float[Tensor, 'batch channel time']) -- Batch of multichannel timeseries with shape (B, C, T).
crop (bool) -- If True, remove fduration * sample_rate samples from the left edge. If False, return the full timeseries.

Return type:

Float[Tensor, 'batch channel time']

Returns:

A torch.float32 tensor with shape (B, C, T - L) when cropped, where L = int(fduration * sample_rate), or (B, C, T) otherwise.

class ml4gw.transforms.whitening.FixedWhiten(num_channels, kernel_length, sample_rate, dtype=torch.float64)

Bases: FittableSpectralTransform

Transform that whitens timeseries by a fixed power spectral density that's determined by calling the .fit method.

Parameters:

num_channels (float) -- Number of channels to whiten
kernel_length (float) -- Expected length of tensors to whiten in seconds. Determines the number of frequency bins in the fit PSD.
sample_rate (float) -- Rate at which timeseries will be sampled, in Hz
crop -- Datatype with which background PSD will be stored
dtype (dtype)

fit(fduration, *background, fftlength=None, highpass=None, lowpass=None, overlap=None)

Compute the PSD of channel-wise background to use to whiten timeseries at call time. PSDs will be resampled to have self.kernel_length * self.sample_rate // 2 + 1 frequency bins.

Parameters:

fduration (float) -- Desired length of the impulse response of the whitening filter, in seconds. Fit PSDs will have their spectrum truncated to approximate this response time. A longer fduration will be able to handle narrower spikes in frequency, but at the expense of longer filter settle-in time. As such fduration / 2 seconds of data will be removed from each edge of whitened timeseries.
*background (Float[Tensor, 'time'] | Float[Tensor, 'frequency']) -- 1D arrays capturing the signal to be used to whiten each channel at call time. If fftlength is left as None, it will be assumed that these already represent frequency-domain data that will be possibly resampled and truncated to whiten timeseries at call time. Otherwise, it will be assumed that these represent time-domain data that will be converted to the frequency domain via Welch's method using the specified fftlength and overlap, with a Hann window used to window the FFT frames by default. Should have the same number of args as self.num_channels.
fftlength (float | None) -- Length of frames used to convert time-domain data to the frequency-domain via Welch's method. If left as None, it will be assumed that the background arrays passed already represent frequency- domain data and don't require any conversion.
highpass (float | None) -- Cutoff frequency, in Hz, used for highpass filtering with the fit whitening filter. This is achieved by setting the frequency response of the fit PSDs in the frequency bins below this value to 0. If left as None, the fit filter won't have any highpass filtering properties.
lowpass (float | None) -- Cutoff frequency, in Hz, used for lowpass filtering with the fit whitening filter. This is achieved by setting the frequency response of the fit PSDs in the frequency bins above this value to 0. If left as None, the fit filter won't have any lowpass filtering properties.
overlap (float | None) -- Overlap between FFT frames used to convert time-domain data to the frequency domain via Welch's method. If fftlength is None, this is ignored. Otherwise, if left as None, it will be set to half of fftlength by default.

Return type:

None

forward(X, crop=True)

Whiten the input timeseries tensor using the PSD fit by the .fit method, which must be called before the first call to .forward.

Parameters:

X (Float[Tensor, 'batch channel time']) -- Batch of multichannel timeseries to whiten. Should have the shape (B, C, N), where B is the batch size, C is the number of channels, and N is the number of seconds in the timeseries times self.sample_rate.
crop (bool) -- If True, crop fduration / 2 seconds of data from both sides of the time dimension to remove the corruption from the filter. If False, return the full timeseries.

Return type:

Float[Tensor, 'batch channel time']

class ml4gw.transforms.whitening.MinimumPhaseWhiten(fduration, sample_rate, highpass=None, lowpass=None)

Bases: Module

Whiten timeseries with a dynamic causal minimum-phase FIR filter.

A whitening kernel is constructed from the PSD provided at call time. It uses only current and previous samples. By default, the initial warm-up samples that depend on zero-valued history are removed from the output, along with one additional sample to match Whiten output lengths. Unlike Whiten, it does not subtract the mean of the complete input segment because that operation depends on future samples.

Parameters:

fduration (float) -- Length of the causal whitening filter in seconds.
sample_rate (float) -- Sampling rate of input timeseries in Hz.
highpass (float | None) -- Optional highpass frequency in Hz. The response is constructed by truncate_inverse_power_spectrum(), as in Whiten.
lowpass (float | None) -- Optional lowpass frequency in Hz. The response is constructed by truncate_inverse_power_spectrum(), as in Whiten.

forward(X, psd, crop=True)

Whiten input using a PSD supplied at call time.

Parameters:

X (Float[Tensor, 'batch channel time']) -- Batch of multichannel timeseries with shape (B, C, T).
psd (Float[Tensor, 'frequency'] | Float[Tensor, 'channel frequency'] | Float[Tensor, 'batch channel frequency']) -- One-sided PSD with shape (F,), (C, F), or (B, C, F). Unscaled physical PSDs may require double precision to avoid underflow.
crop (bool) -- If True, remove fduration * sample_rate samples from the left edge. If False, return the full timeseries, including samples computed from zero-valued initial history.

Return type:

Float[Tensor, 'batch channel time']

Returns:

A torch.float32 tensor with shape (B, C, T - L) when cropped, where L = int(fduration * sample_rate), or (B, C, T) otherwise.

class ml4gw.transforms.whitening.Whiten(fduration, sample_rate, highpass=None, lowpass=None)

Bases: Module

Normalize the frequency content of timeseries data by a provided power spectral density, such that if the timeseries are sampled from the same distribution as the PSD the normalized power will be approximately unity across all frequency bins. The whitened timeseries will then also have 0 mean and unit variance.

In order to avoid edge effects due to filter settle-in, the provided PSDs will have their spectrum truncated such that their impulse response time in the time domain is fduration seconds, and fduration / 2 seconds worth of data will be removed from each edge of the whitened timeseries.

For more information, see the documentation for whiten().

Parameters:

fduration (float) -- The length of the whitening filter's impulse response, in seconds. fduration / 2 seconds worth of data will be cropped from the edges of the whitened timeseries.
sample_rate (float) -- Rate at which timeseries data passed at call time is expected to be sampled
highpass (float | None) -- Cutoff frequency to apply highpass filtering during whitening. If left as None, no highpass filtering will be performed.
lowpass (float | None) -- Cutoff frequency to apply lowpass filtering during whitening. If left as None, no lowpass filtering will be performed.

forward(X, psd, crop=True)

Whiten a batch of multichannel timeseries by a background power spectral density.

Parameters:

X (Float[Tensor, 'batch channel time']) -- Batch of multichannel timeseries to whiten. Should have the shape (B, C, N), where B is the batch size, C is the number of channels, and N is the number of seconds in the timeseries times self.sample_rate.
psd (Float[Tensor, 'frequency'] | Float[Tensor, 'channel frequency'] | Float[Tensor, 'batch channel frequency']) -- Power spectral density used to whiten the provided timeseries. Can be either 1D, 2D, or 3D, with the last dimension representing power at each frequency value. All other dimensions must match their corresponding value in X, starting from the right. (e.g. if psd.ndim == 2, psd.size(1) should be equal to X.size(1). If psd.ndim == 3, psd.size(1) and psd.size(0) should be equal to X.size(1) and X.size(0), respectively.) For more information about what these different shapes for psd represent, consult the documentation for whiten().
crop (bool) -- If True, crop fduration / 2 seconds of data from both sides of the time dimension to remove the corruption from the filter. If False, return the full timeseries.

Return type:

Float[Tensor, 'batch channel time']

Returns:

Whitened timeseries, with fduration * sample_rate / 2: samples cropped from each edge. Output shape will then be (B, C, N - fduration * sample_rate).