API reference - Sonification Methods
Wavelets based
where: |
is nammed: |
\(x_n\) |
x |
\(N\) |
maxNumberSamples |
\(\delta t\) |
sampleSpacingTime |
\(s_j\) |
scales |
\(\delta j\) |
scaleSpacingLog |
\(\Psi_0(\eta)\) |
waveletFunction |
\(\Psi_0(0)\) |
waveletTimeFactor |
\(C_{\delta}\) |
waveletRescaleFactor |
\(W_n(s_j)\) |
coefficients |
- magSonify.sonificationMethods.wavelets.transform.generateCwtScales(maxNumberSamples, dataLength, scaleSpacingLog=0.1, sampleSpacingTime=1, waveletFunction=<magSonify.sonificationMethods.wavelets.wavelets.Morlet object>)
Generates a set of scales to be used to when scaling the wavlet function during CWT and ICWT.
- Parameters
dataLength – The length of the data series to be subject to the forward CWT. Used to correctly constrain the largest scale. If maxNumberSamples is greater than dataLength or none, it will be set to this value.
Based on CT98: https://psl.noaa.gov/people/gilbert.p.compo/Torrence_compo1998.pdf
\[ \begin{align}\begin{aligned}s_j = s_0\, 2^{j \delta j}, \ \ j = 0, 1, ... J\\J = \delta j^{-1} log_2(N \delta t / s_0)\end{aligned}\end{align} \]
- magSonify.sonificationMethods.wavelets.transform.cwt(x, scales, sampleSpacingTime=1, waveletFunction=<magSonify.sonificationMethods.wavelets.wavelets.Morlet object>)
Computes the forward continous wavelet transform.
Based on CT98: https://psl.noaa.gov/people/gilbert.p.compo/Torrence_compo1998.pdf
\[W(s) = \frac{\sqrt{\delta t}}{s} \, \, \text{fftconvolve}( \, x, \, \Psi_0 \, )\]
- magSonify.sonificationMethods.wavelets.transform.icwt(coefficients, scaleLogSpacing=0.1, sampleSpacingTime=1, waveletRescaleFactor=1, waveletTimeFactor=1)
Computes the inverse continous wavelet transform.
- Parameters
coefficients – The coefficients produced from the forward CWT, in a 2D numpy array.
Based on CT98: https://psl.noaa.gov/people/gilbert.p.compo/Torrence_compo1998.pdf
\[x_n = \frac{\delta j \sqrt{\delta t}}{C_{\delta} \, \Psi_0(0)} \sum\limits_{j=0}^J \mathbb{R} \! \left\{ W_n(s_j) \right\}\]
- magSonify.sonificationMethods.wavelets.transform.icwt_noAdmissibilityCondition(coefficients, scales)
Computes the inverse continous wavlet transform using an alternative algorithm.
- Parameters
coefficients – The coefficients produced from the forward CWT, in a 2D numpy array.
scales – The set of scales to be used to when scaling the wavlet function.
Based on the method presented in:
Computational implementation of the inverse continuous wavelet transform without a requirement of the admissibility condition. Eugene B. Postnikov, Elena A. Lebedeva, Anastasia I. Lavrova. 2015. https://arxiv.org/abs/1507.04971
- magSonify.sonificationMethods.wavelets.transform.interpolateCoeffs(coeffs, interpolate_factor)
Interpolates the coefficients produced by CWT. Real and imaginary parts interpolated seperately.
- magSonify.sonificationMethods.wavelets.transform.interpolateCoeffsPolar(magnitude, phase, interpolate_factor)
Interpolates the polar form of the coefficients produced by CWT. Magnitude and phase interpolated sperately.
- class magSonify.sonificationMethods.wavelets.Morlet(w0=6)
Definition of Morlet wavelet function
- Parameters
w0 (int) – Nondimensional frequency constant. If this is set too low then the wavelet does not sample very well: a value over 5 should be ok; Terrence and Compo set it to 6.
- coi(s)
The e folding time for the autocorrelation of wavelet power at each scale, i.e. the timescale over which an edge effect decays by a factor of 1/e^2.
This can be worked out analytically by solving
\[|Y_0(T)|^2 / |Y_0(0)|^2 = 1 / e^2\]
- fourier_period(s)
Equivalent Fourier period of Morlet
- frequency(w, s=1.0)
Frequency representation of Morlet.
- Parameters
w (float) – Angular frequency. If s is not specified, i.e. set to 1, this can be used as the non-dimensional angular frequency w * s.
s (float) – Scaling factor. Default is 1.
- Returns
Value of the Morlet wavelet at the given frequency
- scale_from_period(period) numpy.array
Compute the scale from the fourier period.
- time(t, s=1.0, complete=False)
Complex Morlet wavelet, centred at zero.
- Parameters
t (float) – Time. If s is not specified, this can be used as the non-dimensional time t/s.
s (float) – Scaling factor. Default is 1.
complete (bool) – Whether to use the complete or the standard version.
- Returns
Value of the Morlet wavelet at the given time
The standard version:
\[\pi^{-0.25} \, \text{exp}(iwx) \, \text{exp}(-0.5(x^2))\]This commonly used wavelet is often referred to simply as the Morlet wavelet. Note that this simplified version can cause admissibility problems at low values of w.
The complete version:
\[\pi^{-0.25} \, ( \text{exp}(iwx) - \text{exp}(-0.5(w^2))) \, \text{exp}(-0.5(x^2))\]The complete version of the Morlet wavelet, with a correction term to improve admissibility. For w greater than 5, the correction term is negligible.
Note that the energy of the return wavelet is not normalised according to s.
The fundamental frequency of this wavelet in Hz is given by
f = 2*s*w*r / Mwhere r is the sampling rate.
Paulstretch
- magSonify.sonificationMethods.paulstretch_mono.paulstretch(audioSample: numpy.array, stretch: float, windowsize_seconds: float, samplerate=44100, enableDebugOutput=False) numpy.array
Implementation of paulstretch.
- Parameters
debugOutput – Returns a tuple as output, where the first element is the standard output, the second element is a 2D numpy array containing the amplitude component of the fft of each window, the third is the start index of each window and the fourth is the window function.