clawdia.estimators#

Estimators and metrics for signal analysis and comparison.

This module provides a variety of functions to compute statistical and signal-processing metrics, such as mean squared error, structural similarity index, overlaps, signal-to-noise ratios, and others. While some functions are specifically designed for gravitational-wave signal analysis, they can also be applied to broader signal-processing contexts.

clawdia.estimators.doverlap(x, y, *, at, psd=None, window=('tukey', 0.5))[source]#

Compute the Overlap pseudo-distance.

Useful to use the overlap as loss function.

Reference values:

0 → Perfect correlation. ½ → No correlation. 1 → Perfect anticorrelation.

Parameters:
x, y: array

Signals to compare.

at: float

Sample time step.

psd: 2d-array, optional

PSD to weight the overlap, will be linearly interpolated to the right frequencies.

psd[0] = frequencies psd[1] = psd samples

clawdia.estimators.dssim(x, y)[source]#

Structural Dissimilarity.

Reference values:

0 → Perfect correlation. ½ → No correlation. 1 → Perfect anticorrelation.

clawdia.estimators.find_merger(h: ndarray) → int[source]#

Estimate the index position of the merger in the given strain.

This could be done with a better estimation model, like a gaussian in the case of binary mergers. However for our current project this does not make much difference.

clawdia.estimators.imatch(x, y, *, at=1, psd=None, window=('tukey', 0.5), return_lag=False)[source]#

Shorthand for 1 - match().

clawdia.estimators.inner_product_weighted(x, y, *, at, psd=None, window='hann')[source]#

Compute the weighted inner product (x|y) between two signals.

Parameters:
x, y: ndarray

Signals to compare.

at: float

Sample time step.

psd: 2d-array, optional

PSD to weight the overlap, will be linearly interpolated to the right frequencies. psd[0] = frequencies psd[1] = psd samples

References

[1]: Eq. 12, DOI: 10.48550/arxiv.2210.06194

clawdia.estimators.issim(x, y)[source]#

Inverse Structural SimilarityIndex Measure.

In this case:

  • 1: Perfect anti-correlation.

  • 0: No similarity.

  • -1: Perfect similarity.

Useful as a loss function to perform minimization.

clawdia.estimators.match(x, y, *, at=1, psd=None, window=('tukey', 0.5), return_lag=False)[source]#

Time/phase–maximised match between two (whitened) signals.

This computes the PSD-weighted, normalised inner product maximised over a cyclic time shift (lag) and over phase (by taking the absolute value).

TODO: The values don’t seem to match exactly PyCBC’s match function. Check.

Parameters:
x, yndarray

Signals to compare (same length).

atfloat

Sample time step (seconds).

psd2d-array, optional

If given, weights the frequency-domain inner product; linearly interpolated to FFT frequencies. psd[0]=freqs, psd[1]=PSD samples. If None, the signal is assumed to be whitened, and therefore at can be left at=1 since it cancels out.

windowstr | tuple, optional

Any scipy.signal window spec; applied equally to x and y.

return_lagbool, optional

If True, also return (lag_samples, lag_seconds) at which the maximum match is attained (cyclic correlation notion).

Returns:
mfloat

Match in [0, 1].

(k, tau)tuple[int, float], optional

Index lag and time lag in seconds (only if return_lag=True).

clawdia.estimators.medse(x, y)[source]#

Median Squared Error.

clawdia.estimators.mse(x, y)[source]#

Mean Squared Error.

clawdia.estimators.overlap(x, y, *, at=1, psd=None, window=('tukey', 0.5))[source]#
Compute the Overlap between two signals:

O = (x|y) / sqrt((x|x) · (y|y))

Reference values:

1 → Perfect correlation. 0 → No correlation.

-1 → Perfect anticorrelation.

Parameters:
x, y: array

Signals to compare.

at: float

Sample time step. Leave as at=1 if signals in whitened space.

psd: 2d-array, optional

PSD to weight the overlap, will be linearly interpolated to the right frequencies.

psd[0] = frequencies psd[1] = psd samples

References

[1]: Badger C. et al., 2022 (10.48550/arxiv.2210.06194)

clawdia.estimators.residual(x, y)[source]#

Norm of the difference between ‘x’ and ‘y’.

clawdia.estimators.snr(strain, *, psd, at, window=('tukey', 0.5))[source]#

Signal to Noise Ratio.

clawdia.estimators.softmax(x, axis=None)[source]#

Softmax probability distribution.

clawdia.estimators.ssim(x, y)[source]#

Structural Similarity Index Measure (SSIM).

Compute the Structural Similarity Index Measure (SSIM) between two arrays, x and y. SSIM is a perceptual metric that quantifies the similarity between two signals or images, accounting for luminance, contrast, and structure [1], [2].

Reference values:

1 → Perfect similarity. 0 → No similarity.

-1 → Perfect anti-correlation.

Parameters:
xarray_like

Input signal or image. Must be of the same shape as y.

yarray_like

Input signal or image. Must be of the same shape as x.

Returns:
resfloat

The Structural Similarity Index Measure between the signals x and y.

References

[1]

Wang, Z., Bovik, A. C., Sheikh, H. R., & Simoncelli, E. P. (2004). Image quality assessment: From error visibility to structural similarity. IEEE Transactions on Image Processing, 13(4), 600-612.