Util - utility functions

unwrap(m; kwargs...)

Assumes m to be a sequence of values that has been wrapped to be inside the given range (centered around zero), and undoes the wrapping by identifying discontinuities. If a single dimension is passed to dims, then m is assumed to have wrapping discontinuities only along that dimension. If a range of dimensions, as in 1:ndims(m), is passed to dims, then m is assumed to have wrapping discontinuities across all ndims(m) dimensions.

A common usage for unwrapping across a singleton dimension is for a phase measurement over time, such as when comparing successive frames of a short-time-fourier-transform, as each frame is wrapped to stay within (-pi, pi].

A common usage for unwrapping across multiple dimensions is for a phase measurement of a scene, such as when retrieving the phase information of of an image, as each pixel is wrapped to stay within (-pi, pi].

Arguments

• m::AbstractArray{T, N}: Array to unwrap.
• dims=nothing: Dimensions along which to unwrap. If dims is an integer, then unwrap is called on that dimension. If dims=1:ndims(m), then m is unwrapped across all dimensions.
• range=2pi: Range of wrapped array.
• circular_dims=(false, ...): When an element of this tuple is true, the unwrapping process will consider the edges along the corresponding axis of the array to be connected.
• rng=GLOBAL_RNG: Unwrapping of arrays with dimension > 1 uses a random initialization. A user can pass their own RNG through this argument.

unwrap!(m; kwargs...)

In-place version of unwrap.

unwrap!(y, m; kwargs...)

Unwrap m storing the result in y, see unwrap.

hilbert(x)

Computes the analytic representation of x, $x_a = x + j \hat{x}$, where $\hat{x}$ is the Hilbert transform of x, along the first dimension of x.

nextfastfft(n)

Return the closest product of 2, 3, 5, and 7 greater than or equal to n. FFTW contains optimized kernels for these sizes and computes Fourier transforms of input that is a product of these sizes faster than for input of other sizes.

pow2db(a)

Convert a power ratio to dB (decibel), or $10\log_{10}(a)$. The inverse of db2pow.

amp2db(a)

Convert an amplitude ratio to dB (decibel), or $20 \log_{10}(a)=10\log_{10}(a^2)$. The inverse of db2amp.

db2pow(a)

Convert dB to a power ratio. This function call also be called using a*dB, i.e. 3dB == db2pow(3). The inverse of pow2db.

db2amp(a)

Convert dB to an amplitude ratio. This function call also be called using a*dBa, i.e. 3dBa == db2amp(3). The inverse of amp2db.

rms(s)

Return the root mean square of signal s.

rmsfft(f)

Return the root mean square of signal s given the FFT transform f = fft(s). Equivalent to rms(ifft(f)).

meanfreq(x, fs)

Calculate the mean power frequency of x with a sampling frequency of fs, defined as:

\[MPF = \frac{\sum_{i=1}^{F} f_i X_i^2 }{\sum_{i=0}^{F} X_i^2 } Hz\]

where $F$ is the Nyquist frequency, and $X$ is the power spectral density.

finddelay(x, y)

Estimate the delay of x with respect to y by locating the peak of their cross-correlation.

The output delay will be positive when x is delayed with respect y, negative if advanced, 0 otherwise.

Example

julia> finddelay([0, 0, 1, 2, 3], [1, 2, 3])
2

julia> finddelay([1, 2, 3], [0, 0, 1, 2, 3])
-2

shiftsignal(x, s)

Shift elements of signal x in time by a given amount s of samples and fill the spaces with zeros. For circular shifting, use circshift.

Example

julia> shiftsignal([1, 2, 3], 2)
3-element Vector{Int64}:
 0
 0
 1

julia> shiftsignal([1, 2, 3], -2)
3-element Vector{Int64}:
 3
 0
 0

See also shiftsignal!.

shiftsignal!(x, s)

Mutating version of shiftsignals(): shift x of s samples and fill the spaces with zeros in-place.

See also shiftsignal.

alignsignals(x, y)

Use finddelay() and shiftsignal() to time align x to y. Also return the delay of x with respect to y.

Example

julia> alignsignals([0, 0, 1, 2, 3], [1, 2, 3])
([1, 2, 3, 0, 0], 2)

julia> alignsignals([1, 2, 3], [0, 0, 1, 2, 3])
([0, 0, 1], -2)

See also alignsignals!.

alignsignals!(x, y)

Mutating version of alignsignals(): time align x to y in-place.

See also alignsignals.

kernel = diric(Ω::Real, n::Integer)

Dirichlet kernel, also known as periodic sinc function, where n should be a positive integer. Returns sin(Ω * n/2) / (n * sin(Ω / 2)) typically, but ±1 when Ω is a multiple of 2π.

In the usual case where 'n' is odd, the output is equivalent to $1/n \sum_{k=-(n-1)/2}^{(n-1)/2} e^{i k Ω}$, which is the discrete-time Fourier transform (DTFT) of a n-point moving average filter.

When n is odd or even, the function is 2π or 4π periodic, respectively. The formula for general n is diric(Ω,n) =e^{-i (n-1) Ω/2}/n \sum_{k=0}^{n-1} e^{i k Ω}, which is a real and symmetric function ofΩ`.

As of 2021-03-19, the Wikipedia definition has different factors. The definition here is consistent with scipy and other software frameworks.

Examples

julia> round.(diric.((-2:0.5:2)*π, 5), digits=9)'
1×9 adjoint(::Vector{Float64}) with eltype Float64:
 1.0  -0.2  0.2  -0.2  1.0  -0.2  0.2  -0.2  1.0

julia> diric(0, 4)
1.0