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.

fftfreq(n, fs=1)

Return discrete fourier transform sample frequencies. The returned Frequencies object is an AbstractVector containing the frequency bin centers at every sample point. fs is the sample rate of the input signal.

rfftfreq(n, fs=1)

Return discrete fourier transform sample frequencies for use with rfft. The returned Frequencies object is an AbstractVector containing the frequency bin centers at every sample point. fs is the sample rate of the input signal.

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:

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 Array{Int64,1}:
 0
 0
 1

julia> shiftsignal([1, 2, 3], -2)
3-element Array{Int64,1}:
 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.