ml4gw.transforms package

Submodules

ml4gw.transforms.pearson module

class ml4gw.transforms.pearson.ShiftedPearsonCorrelation(max_shift)

Bases: Module

Compute the [Pearson correlation] (https://en.wikipedia.org/wiki/Pearson_correlation_coefficient) for two equal-length timeseries over a pre-defined number of time shifts in each direction. Useful for when you want a correlation, but not over every possible shift (i.e. a convolution).

The number of dimensions of the second timeseries y passed at call time should always be less than or equal to the number of dimensions of the first timeseries x, and each dimension should match the corresponding one of x in reverse order (i.e. if x has shape (B, C, T) then y should either have shape (T,), (C, T), or (B, C, T)).

Note that no windowing to either timeseries is applied at call time. Users should do any requisite windowing beforehand.

TODOs: - Should we perform windowing? - Should we support stride > 1?

Parameters:

max_shift (int) -- The maximum number of 1-step time shifts in each direction over which to compute the Pearson coefficient. Output shape will then be (2 * max_shifts + 1, B, C).

forward(x, y)

Define the computation performed at every call.

Should be overridden by all subclasses. :rtype: Tensor

Note

Although the recipe for forward pass needs to be defined within this function, one should call the Module instance afterwards instead of this since the former takes care of running the registered hooks while the latter silently ignores them.

ml4gw.transforms.scaler module

class ml4gw.transforms.scaler.ChannelWiseScaler(num_channels=None)

Bases: FittableTransform

Scale timeseries channels to be zero mean unit variance

Scales timeseries channels by the mean and standard deviation of the channels of the timeseries used to fit the module. To reverse the scaling, provide the reverse=True keyword argument at call time. By default, the scaling parameters are set to zero mean and unit variance, amounting to an identity transform.

Parameters:

num_channels (Optional[int]) -- The number of channels of the target timeseries. If left as None, the timeseries will be assumed to be 1D (single channel).

fit(X)

Fit the scaling parameters to a timeseries

Computes the channel-wise mean and standard deviation of the timeseries X and sets these values to the mean and std parameters of the scaler.

Return type:

None

forward(X, reverse=False)

Define the computation performed at every call.

Should be overridden by all subclasses. :rtype: Tensor

Note

Although the recipe for forward pass needs to be defined within this function, one should call the Module instance afterwards instead of this since the former takes care of running the registered hooks while the latter silently ignores them.

ml4gw.transforms.snr_rescaler module

class ml4gw.transforms.snr_rescaler.SnrRescaler(num_channels, sample_rate, waveform_duration, highpass=None, dtype=torch.float32)

Bases: FittableSpectralTransform

fit(*background, fftlength=None, overlap=None)

forward(responses, target_snrs=None)

Define the computation performed at every call.

Should be overridden by all subclasses.

Note

Although the recipe for forward pass needs to be defined within this function, one should call the Module instance afterwards instead of this since the former takes care of running the registered hooks while the latter silently ignores them.

ml4gw.transforms.spectral module

class ml4gw.transforms.spectral.SpectralDensity(sample_rate, fftlength, overlap=None, average='mean', window=None, fast=False)

Bases: Module

Transform for computing either the power spectral density of a batch of multichannel timeseries, or the cross spectral density of two batches of multichannel timeseries.

On SpectralDensity.forward call, if only one tensor is provided, this transform will compute its power spectral density. If a second tensor is provided, the cross spectral density between the two timeseries will be computed. For information about the allowed relationships between these two tensors, see the documentation to ml4gw.spectral.fast_spectral_density.

Note that the cross spectral density computation is currently only available for the fast_spectral_density option. If fast=False and a second tensor is passed to SpectralDensity.forward, a NotImplementedError will be raised.

Parameters:

• sample_rate (float) -- Rate at which tensors passed to forward will be sampled

• fftlength (float) -- Length of the window, in seconds, to use for FFT estimates

• overlap (Optional[float]) -- Overlap between windows used for FFT calculation. If left as None, this will be set to fftlength / 2.

• average (str) -- Aggregation method to use for combining windowed FFTs. Allowed values are "mean" and "median".

• window (Optional[Tensor]) -- Window array to multiply by each FFT window before FFT computation. Should have length nperseg. Defaults to a hanning window.

• fast (bool) -- Whether to use a faster spectral density computation that support cross spectral density, or a slower one which does not. The cost of the fast implementation is that it is not exact for the two lowest frequency bins.

forward(x, y=None)

Define the computation performed at every call.

Should be overridden by all subclasses.

Note

Although the recipe for forward pass needs to be defined within this function, one should call the Module instance afterwards instead of this since the former takes care of running the registered hooks while the latter silently ignores them.

ml4gw.transforms.spectrogram module

class ml4gw.transforms.spectrogram.MultiResolutionSpectrogram(kernel_length, sample_rate, **kwargs)

Bases: Module

Create a batch of multi-resolution spectrograms from a batch of timeseries. Input is expected to have the shape (B, C, T), where B is the number of batches, C is the number of channels, and T is the number of time samples.

For each timeseries, calculate multiple normalized spectrograms based on the Spectrogram kwargs given. Combine the spectrograms by taking the maximum value from the nearest time-frequncy bin.

If the largest number of time bins among the spectrograms is N and the largest number of frequency bins is M, the output will have dimensions (B, C, M, N)

Parameters:

• kernel_length (float) -- The length in seconds of the time dimension of the tensor that will be turned into a spectrogram

• sample_rate (float) -- The sample rate of the timeseries in Hz

• kwargs -- Arguments passed in kwargs will used to create `torchaudio.transforms.Spectrogram`s. Each argument should be a list of values. Any list of length greater than 1 should be the same length

forward(X)

Calculate spectrograms of the input tensor and combine them into a single spectrogram

Parameters:

X (Tensor) -- Batch of multichannel timeseries which will be used to calculate the multi-resolution spectrogram. Should have the shape (B, C, T), where B is the number of batches, C is the number of channels, and T is the number of time samples.

Return type:

Tensor

ml4gw.transforms.transform module

class ml4gw.transforms.transform.FittableSpectralTransform

Bases: FittableTransform

normalize_psd(x, sample_rate, num_freqs, fftlength=None, overlap=None)

class ml4gw.transforms.transform.FittableTransform

Bases: Module

build(**params)

ml4gw.transforms.waveforms module

class ml4gw.transforms.waveforms.WaveformProjector(ifos, sample_rate)

Bases: Module

forward(dec, psi, phi, **polarizations)

Define the computation performed at every call.

Should be overridden by all subclasses.

Note

Although the recipe for forward pass needs to be defined within this function, one should call the Module instance afterwards instead of this since the former takes care of running the registered hooks while the latter silently ignores them.

class ml4gw.transforms.waveforms.WaveformSampler(parameters=None, **polarizations)

Bases: Module

forward(N)

Define the computation performed at every call.

Should be overridden by all subclasses.

Note

Although the recipe for forward pass needs to be defined within this function, one should call the Module instance afterwards instead of this since the former takes care of running the registered hooks while the latter silently ignores them.

ml4gw.transforms.whitening module

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

• dtype (dtype) -- Datatype with which background PSD will be stored

fit(fduration, *background, fftlength=None, highpass=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 (Tensor) -- 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 (Optional[float]) -- 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 (Optional[float]) -- 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.

• overlap (Optional[float]) -- 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)

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

Return type:

Tensor

class ml4gw.transforms.whitening.Whiten(fduration, sample_rate, highpass=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 to ml4gw.spectral.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 (Optional[float]) -- Cutoff frequency to apply highpass filtering during whitening. If left as None, no highpass filtering will be performed.

forward(X, psd)

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

Parameters:

• X (Tensor) -- 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 (Tensor) -- 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 ml4gw.spectral.whiten.

Return type:

Tensor

Returns:

Whitened timeseries, with fduration * sample_rate / 2

samples cropped from each edge. Output shape will then be (B, C, N - fduration * sample_rate).

Module contents