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=default_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::Integer)
nextfastfft(ns::Tuple)

Return an estimate for the padded size of an array that is optimal for the performance of an n-dimensional FFT.

For Tuple inputs, this returns a Tuple that is the size of the padded array.

For Integer inputs, this returns 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 inputs that are a product of these sizes faster than for inputs 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; dims)

Return the root mean square (rms) of signal s. Optional keyword parameter dims can be used to specify the dimensions along which to compue the rms.

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

shiftin!(a::AbstractVector{T}, b::AbstractVector{T}) where T

Shifts b into the end of a.

julia> shiftin!([1,2,3,4], [5, 6])
4-element Vector{Int64}:
 3
 4
 5
 6

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.

Typically returns $\frac{\sin(Ω \cdot n/2)}{n * \sin(Ω / 2)}$, but returns $±1$ when Ω is a multiple of 2π.

In the usual case where n is odd, the output is equivalent to $\frac{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

\[\mathrm{diric}(Ω,n) = \frac{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