ml4gw.transforms.qtransform

Classes

QScan(duration, sample_rate, spectrogram_shape)	Calculate the Q-transform of a batch of multi-channel time series data for a range of Q values and return the interpolated Q-transform with the highest energy.
QTile(q, frequency, duration, sample_rate, ...)	Compute the row of Q-tiles for a single Q value and a single frequency for a batch of multi-channel frequency series data.
SingleQTransform(duration, sample_rate, ...)	Compute the Q-transform for a single Q value for a batch of multi-channel time series data.

class ml4gw.transforms.qtransform.QScan(duration, sample_rate, spectrogram_shape, qrange=None, frange=None, interpolation_method='bicubic', mismatch=0.2)

Bases: Module

Calculate the Q-transform of a batch of multi-channel time series data for a range of Q values and return the interpolated Q-transform with the highest energy.

Parameters:

• duration (float) -- Length of the time series data in seconds

• sample_rate (float) -- Sample rate of the data in Hz

• spectrogram_shape (Tuple[int, int]) -- The shape of the interpolated spectrogram, specified as (num_f_bins, num_t_bins). Because the frequency spacing of the Q-tiles is in log-space, the frequency interpolation is log-spaced as well.

• qrange (Optional[List[float]]) -- The lower and upper values of Q to consider. The actual values of Q used for the transforms are determined by the get_qs method

• frange (Optional[List[float]]) -- The lower and upper frequency limit to consider for the transform. If unspecified, default values will be chosen based on q, sample_rate, and duration

• mismatch (float) -- The maximum fractional mismatch between neighboring tiles

forward(X, fsearch_range=None, norm='median')

Compute the set of QTiles for each Q transform and determine which has the highest energy value. Interpolate and return the corresponding set of tiles.

Parameters:

• X (Union[Float[Tensor, 'time'], Float[Tensor, 'channel time'], Float[Tensor, 'batch channel time']]) -- Time series of data. Should have the duration and sample rate used to initialize this object. Expected input shape is (B, C, T), where T is the number of samples, C is the number of channels, and B is the number of batches. If less than three-dimensional, axes will be added during Q-tile computation.

• fsearch_range (Optional[List[float]]) -- The lower and upper frequency values within which to search for the maximum energy

• norm (str) -- The method of interpolation used by each QTile

Returns:

An interpolated Q-transform for the batch of data. Output will have one more dimension than the input

get_qs()

Determine the values of Q to try for the set of Q-transforms

Return type:

List[float]

class ml4gw.transforms.qtransform.QTile(q, frequency, duration, sample_rate, mismatch)

Bases: Module

Compute the row of Q-tiles for a single Q value and a single frequency for a batch of multi-channel frequency series data. Should really be called QRow, but I want to match GWpy. Input data should have three dimensions or fewer. If fewer, dimensions will be added until the input is three-dimensional.

Parameters:

• q (float) -- The Q value to use in computing the Q tile

• frequency (float) -- The frequency for which to compute the Q tile in Hz

• duration (float) -- The length of time in seconds that the input frequency series represents

• sample_rate (float) -- The sample rate of the original time series in Hz

• mismatch (float) -- The maximum fractional mismatch between neighboring tiles

forward(fseries, norm='median')

Compute the transform for this row

Parameters:

• fseries (Union[Float[Tensor, 'frequency'], Float[Tensor, 'channel frequency'], Float[Tensor, 'batch channel frequency']]) -- Frequency series of data. Should correspond to data with the duration and sample rate used to initialize this object. Expected input shape is (B, C, F), where F is the number of samples, C is the number of channels, and B is the number of batches. If less than three-dimensional, axes will be added.

• norm (str) -- The method of normalization. Options are "median", "mean", or None.

Return type:

Union[Float[Tensor, 'time'], Float[Tensor, 'channel time'], Float[Tensor, 'batch channel time']]

Returns:

The row of Q-tiles for the given Q and frequency. Output is three-dimensional: (B, C, T)

get_data_indices()

Get the index array of relevant frequencies for this row

Return type:

Int[Tensor, 'windowsize']

get_window()

Generate the bi-square window for this row

Return type:

Float[Tensor, 'windowsize']

ntiles()

Number of tiles in this frequency row

Return type:

int

class ml4gw.transforms.qtransform.SingleQTransform(duration, sample_rate, spectrogram_shape, q=12, frange=None, mismatch=0.2, interpolation_method='bicubic')

Bases: Module

Compute the Q-transform for a single Q value for a batch of multi-channel time series data. Input data should have three dimensions or fewer.

Parameters:

• duration (float) -- Length of the time series data in seconds

• sample_rate (float) -- Sample rate of the data in Hz

• spectrogram_shape (Tuple[int, int]) -- The shape of the interpolated spectrogram, specified as (num_f_bins, num_t_bins). Because the frequency spacing of the Q-tiles is in log-space, the frequency interpolation is log-spaced as well.

• q (float) -- The Q value to use for the Q transform

• frange (Optional[List[float]]) -- The lower and upper frequency limit to consider for the transform. If unspecified, default values will be chosen based on q, sample_rate, and duration

• mismatch (float) -- The maximum fractional mismatch between neighboring tiles

• interpolation_method (str) -- The method by which to interpolate each QTile to the specified number of time and frequency bins. The acceptable values are "bilinear", "bicubic", and "spline". The "bilinear" and "bicubic" options will use PyTorch's built-in interpolation modes, while "spline" will use the custom Torch-based implementation in ml4gw, as PyTorch does not have spline-based intertpolation. The "spline" mode is most similar to the results of GWpy's Q-transform, which uses scipy to do spline interpolation. However, it is also the slowest and most memory intensive due to the matrix equation solving steps. Therefore, the default method is "bicubic" as it produces the most similar results while optimizing for computing performance.

compute_qtiles(X, norm='median')

Take the FFT of the input timeseries and calculate the transform for each QTile

Return type:

None

Parameters:

• X (Float[Tensor, 'time'] | Float[Tensor, 'channel time'] | Float[Tensor, 'batch channel time'])

• norm (str)

forward(X, norm='median')

Compute the Q-tiles and interpolate

Parameters:

• X (Union[Float[Tensor, 'time'], Float[Tensor, 'channel time'], Float[Tensor, 'batch channel time']]) -- Time series of data. Should have the duration and sample rate used to initialize this object. Expected input shape is (B, C, T), where T is the number of samples, C is the number of channels, and B is the number of batches. If less than three-dimensional, axes will be added during Q-tile computation.

• norm (str) -- The method of normalization used by each QTile

Returns:

The interpolated Q-transform for the batch of data. Output will have one more dimension than the input

get_freqs()

Calculate the frequencies that will be used in this transform. For each frequency, a QTile is created.

Return type:

Float[Tensor, 'nfreq']

get_max_energy(fsearch_range=None, dimension='both')

Gets the maximum energy value among the QTiles. The maximum can be computed across all batches and channels, across all channels, across all batches, or individually for each channel/batch combination. This could be useful for allowing the use of different Q values for different channels and batches, but the slicing would be slow, so this isn't used yet.

Optionally, a pair of frequency values can be specified for fsearch_range to restrict the frequencies in which the maximum energy value is sought.

Parameters:

• fsearch_range (List[float] | None)

• dimension (str)

interpolate()

Return type:

Float[Tensor, 'batch channel time']