timefrequency - Time-Frequency representations

Quaternion Embedding

class bispy.timefrequency.Hembedding(q)[source]

H-embedding class. Computes quaternion embedding of complex-valued signals.

Parameters:
qarray_type

quaternion input signal

Attributes:
signalarray_type

original input signal

Hembeddingarray_type

Quaternion-embedding of the input signal

aarray_type

instantaneous amplitude

thetaarray_type

instantaneous orientation

chiarray_type

instantaneous ellipticity

phiarray_type

instantaneous phase

Q-STFT

class bispy.timefrequency.QSTFT(x, t=None)[source]

Compute the Quaternion-Short Term Fourier Transform for bivariate signals taken as (1, i)-quaternion valued signals.

Parameters:
xarray_type

input signal array

tarray_type (optional)

time samples array. Default is t = np.arange(x.shape[0])

Attributes:
tarray_type

time samples array

xarray_type

input signal array

paramsdict

parameters used for the computation of the Q-STFT.

sampled_timearray_type

sampled times instants

farray_type

sampled frequencies

tfprarray_type

Q-STFT coefficients array

S0, S1, S2, S3array_type

Time-frequency Stokes parameters, non-normalized [w.r.t. S0]

S1n, S2n, S3narray_type

normalized time-frequency Stokes parameters [w.r.t. S0] using the tolerance factor tol. See utils.normalizeStokes.

ridgeslist

List of ridges index and values extracted from the time-frequency energy density S0. Requires call of extractRidges for ridges to be added.

Methods

compute([window, nperseg, noverlap, nfft, ...])

Compute the Q-STFT of the signal x.

extractRidges([parThresh, parMinD])

Extracts ridges from the time-frequency energy density S0.

inverse([mask])

Compute inverse Q-STFT

normalizeStokes([tol])

Re-compute normalized Stokes parameters with a different normalization.

plotRidges([quivertdecim])

Plot S0, the orientation and ellipticity recovered from the ridges in time-frequency domain

plotSignal([kind])

Plot the bivariate signal x.

plotStokes([S0_cmap, s_cmap, single_sided])

Time-frequency plot of time-frequency energy map (S0) and time-frequency polarization parameters (normalized Stokes parameters S1n, S2n, S3n)

compute(window='hamming', nperseg=128, noverlap=None, nfft=None, boundary='zeros', tol=0.01, ridges=False)[source]

Compute the Q-STFT of the signal x.

It takes advantages of the scipy.signal.stft function for greater flexibility.

Parameters:
window, nperseg, noverlap, nfft, boundarystft parameters

See scipy.signal.stft

tolfloat, optional

tolerance factor used in normalization of Stokes parameters. Default to 0.01

ridges: bool, optional

If True, compute also the ridges of the transform. Default to False. Ridges can be later computed using extractRidges().

extractRidges(parThresh=4, parMinD=3)[source]

Extracts ridges from the time-frequency energy density S0.

Parameters:
parThreshfloat, optional

Controls the threshold at which local maxima of S0 are accepted or rejected. Larger values of `parThresh`increase the number of eligible points.

parMinDfloat, optional

Ridge smoothness parameter. Controls at which maximal distance can be located two eligible same ridge points. The smaller `parMinD`is the smoother ridges are.

Returns:
ridgeslist

list of detected ridges

inverse(mask=None)[source]

Compute inverse Q-STFT

Parameters:
mask: array_type

mask applied to Q-STFT coefficients prior to inversion. If mask=None, no mask is employed.

plotRidges(quivertdecim=10)[source]

Plot S0, the orientation and ellipticity recovered from the ridges in time-frequency domain

If ridges are not extracted yet, it runs extractRidges method first.

Parameters:
quivertdecimint, optional

time-decimation index (allows faster and cleaner visualization of orientation vector field)

Returns:
fig, axfigure and axis handles

may be needed to tweak the plot

plotStokes(S0_cmap='viridis', s_cmap='coolwarm', single_sided=True)[source]

Time-frequency plot of time-frequency energy map (S0) and time-frequency polarization parameters (normalized Stokes parameters S1n, S2n, S3n)

Parameters:
S0_cmapcolormap (sequential)

to use for S0 time-frequency distribution

s_cmapcolormap (diverging)

to use for normalized Stokes time-frequency distribution

Returns:
fig, axfigure and axis handles

may be needed to tweak the plot

Q-CWT

class bispy.timefrequency.QCWT(x, t=None)[source]

Methods

compute(fmin, fmax, waveletParams[, ...])

Compute the Q-CWT of x using a specified wavelet.

extractRidges([parThresh, parMinD])

Extracts ridges from the time-scale energy density S0.

normalizeStokes([tol])

Re-compute normalized Stokes parameters with a different normalization.

plotRidges([quivertdecim])

Plot S0, and the orientation and ellipticity recovered from the ridges in time-scale domain

plotSignal([kind])

Plot the bivariate signal x.

plotStokes([S0_cmap, s_cmap])

Time-frequency plot of time-frequency energy map (S0) and time-frequency polarization parameters (normalized Stokes parameters S1n, S2n, S3n)

compute(fmin, fmax, waveletParams, Nscales=50, tol=0.01, ridges=False)[source]

Compute the Q-CWT of x using a specified wavelet.

Parameters:
fmin, fmaxfloat

min and max frequencies

waveletParamsdict

dictionary containing wavelet features. Currently 2 types, ‘Morlet’ and ‘Morse’ are supported.

Nscalesint

number of scales to analyze. Controls the size of the sampled_frequencies array.

tolfloat, optional

tolerance factor used in normalization of Stokes parameters. Default to 0.01

ridges: bool, optional

If True, compute also the ridges of the transform. Default to False. Ridges can be later computed using extractRidges().

extractRidges(parThresh=4, parMinD=3)[source]

Extracts ridges from the time-scale energy density S0.

Parameters:
parThreshfloat, optional

Controls the threshold at which local maxima of S0 are accepted or rejected. Larger values of `parThresh`increase the number of eligible points.

parMinDfloat, optional

Ridge smoothness parameter. Controls at which maximal distance can be located two eligible same ridge points. The smaller `parMinD`is the smoother ridges are.

Returns:
ridgeslist

list of detected ridges

plotRidges(quivertdecim=10)[source]

Plot S0, and the orientation and ellipticity recovered from the ridges in time-scale domain

If ridges are not extracted yet, it runs extractRidges method first.

Parameters:
quivertdecimint, optional

time-decimation index (allows faster and cleaner visualization of orientation vector field)

Returns:
fig, axfigure and axis handles

may be needed to tweak the plot

plotStokes(S0_cmap='viridis', s_cmap='coolwarm')[source]

Time-frequency plot of time-frequency energy map (S0) and time-frequency polarization parameters (normalized Stokes parameters S1n, S2n, S3n)

Parameters:
S0_cmapcolormap (sequential)

to use for S0 time-frequency distribution

s_cmapcolormap (diverging)

to use for normalized Stokes time-frequency distribution

Returns:
fig, axfigure and axis handles

may be needed to tweak the plot