Engee documentation

Util - utility functions

As of version 0.6.1 of DSP.jl, fftfreq and rfftfreq have been moved from DSP.jl to AbstractFFTs.jl version 0.5 and above. You can also access these functions through FFTW.jl version 1.1 and above.

 
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, , where 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 . The inverse of db2pow.

amp2db(a)

Convert an amplitude ratio to dB (decibel), or . 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 is the Nyquist frequency, and 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 , 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