`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.

`DSP.Unwrap.unwrap`

— Function`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.

`DSP.Unwrap.unwrap!`

— Function`unwrap!(m; kwargs...)`

In-place version of `unwrap`

.

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

Unwrap `m`

storing the result in `y`

, see `unwrap`

.

`DSP.Util.hilbert`

— Function`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.

`DSP.Util.nextfastfft`

— Function`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.

`DSP.Util.pow2db`

— Function`pow2db(a)`

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

.

`DSP.Util.amp2db`

— Function`amp2db(a)`

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

.

`DSP.Util.db2pow`

— Function`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`

.

`DSP.Util.db2amp`

— Function`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`

.

`DSP.Util.rms`

— Function`rms(s)`

Return the root mean square of signal `s`

.

`DSP.Util.rmsfft`

— Function`rmsfft(f)`

Return the root mean square of signal `s`

given the FFT transform `f = fft(s)`

. Equivalent to `rms(ifft(f))`

.

`DSP.Util.meanfreq`

— Function`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.

`DSP.Util.finddelay`

— Function`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
```

`DSP.Util.shiftsignal`

— Function`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!`

.

`DSP.Util.shiftsignal!`

— Function`shiftsignal!(x, s)`

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

See also `shiftsignal`

.

`DSP.Util.alignsignals`

— Function`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!`

.

`DSP.Util.alignsignals!`

— Function`alignsignals!(x, y)`

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

See also `alignsignals`

.

`DSP.diric`

— Function`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
```