Util - utility functions

Note

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.

DSP.Unwrap.unwrapFunction
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.
source
DSP.Util.hilbertFunction
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.

source
DSP.Util.nextfastfftFunction
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.

source
DSP.Util.pow2dbFunction
pow2db(a)

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

source
DSP.Util.amp2dbFunction
amp2db(a)

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

source
DSP.Util.db2powFunction
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.

source
DSP.Util.db2ampFunction
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.

source
DSP.Util.rmsFunction
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.

source
DSP.Util.rmsfftFunction
rmsfft(f)

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

source
DSP.Util.meanfreqFunction
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.

source
DSP.Util.finddelayFunction
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
source
DSP.Util.shiftin!Function
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
source
DSP.Util.shiftsignalFunction
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!.

source
DSP.Util.alignsignalsFunction
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!.

source
DSP.diricFunction
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
source