dgt

Discrete Gabor transform

Since R2025a

Syntax

d = dgt(x)

d = dgt(x,Name=Value)

[d,f] = dgt(___)

[d,f,t] = dgt(___)

dgt(___)

Description

d = dgt(x) returns the discrete Gabor transform (DGT) of x. For more information, see Discrete Gabor Transform.

d = dgt(x,Name=Value) specifies options using or more name-value arguments, in addition to the input argument of the previous syntax. For example, to specify a sample rate of 500 Hz, set SampleRate to 500.

[d,f] = dgt(___) returns the frequencies at which the DGT is evaluated.

[d,f,t] = dgt(___) returns the times at which the DGT is evaluated.

dgt(___) with no output arguments plots the magnitude of the DGT in dB in the current figure.

Examples

Discrete Gabor Transform of Linear Chirp

Generate a linear chirp with normalized frequency. Cast the signal to single precision.

t = 0:2*2048-1;
x = chirp(t,250/2048,2048,500/2048);
xs = single(x);

Obtain the DGT of the single-precision signal. Confirm the underlying data type is single.

d = dgt(xs);
underlyingType(d)

ans = 
'single'

Display the magnitude of the DGT.

dgt(xs)

Discrete Gabor Transform of Signal in Timetable

Load the hyperbolic chirp signal. The signal is sampled at 2048 Hz for one second.

load hyperbolchirp
whos hyperbolchirp

  Name                  Size            Bytes  Class        Attributes

  hyperbolchirp      2048x1             33759  timetable              

Extract the row time times from the timetable. Confirm the sample rate is 2048 Hz.

rt = hyperbolchirp.Properties.RowTimes;
rts = seconds(rt);
[min(1./diff(rts)) max(1./diff(rts))]

ans = 1×2
103 ×

    2.0480    2.0480

Display the DGT of the signal. Set the hop length to 16 samples and number of frequency bins to 512.

dgt(hyperbolchirp,HopLength=16,NumFrequencyBins=512)

One-Sided Discrete Gabor Transform

Load the quadratic chirp signal. The signal has 4001 samples.

load quadchirp

Compute and display the one-sided DGT of the signal. Because the sample rate is not defined, the frequency is in cycles per sample.

dgt(quadchirp,FrequencyRange="onesided")

Obtain the one-sided DGT of the signal. This time, specify a sample rate of 1 kHz. Also obtain the frequencies and time instants of the DGT.

Fs = 1000;
[d,f,t] = dgt(quadchirp,SampleRate=Fs, ...
    FrequencyRange="onesided");

Confirm the number of rows and columns in the DGT are equal to the lengths of the frequency vector and time vector, respectively.

isequal(size(d,1),length(f))

ans = logical
   1

isequal(size(d,2),length(t))

ans = logical
   1

Plot the magnitude of the DGT as a surface.

surf(t,f,20*log10(abs(d)+eps))
shading interp
xlabel("Time (s)")
ylabel("Frequency (Hz)")
zlabel("Magnitude (dB)")
title("Discrete Gabor Transform")
colormap jet

Discrete Gabor Transform of Complex-Valued Signal

Create a complex-valued signal. Specify a sample rate of 2 kHz and sample the signal for one second.

Fs = 2000;
sigLen = 2000;
t = (0:sigLen-1)/Fs;
sig = exp(1i*2*pi*25*cos(2*pi*2*t));

Compute and display the DGT of the signal. Specify a window length of 32, hop length of 1. Set the number of frequency bins to the signal length. By default, the function computes the two-sided and centered DGT.

winLen = 32;
hopLen = 1;
numBins = length(sig);
dgt(sig,WindowLength=winLen,HopLength=hopLen, ...
    SampleRate=Fs,NumFrequencyBin=numBins)

Compute and display the DGT using the same values, but this time set FrequencyRange to "twosided".

dgt(sig,WindowLength=winLen,HopLength=hopLen, ...
    SampleRate=Fs,NumFrequencyBin=numBins, ...
    FrequencyRange="twosided")

Visualize DGT of Gaussian Window

Create a periodic Gaussian window whose length is 1024 samples. Specify a time-frequency ratio of 1. For more information, see Time-Frequency Ratio.

L = 1024;
tfr = 1;
P = ceil(4/sqrt(L/sqrt(tfr)));
g = 0;
for p = -P:P
    g = g+exp(-pi*((0:L-1)/sqrt(L)-p*sqrt(L)).^2/tfr);
end
g = g(:)/norm(g,2);

Visualize the DGT of the window. Set WindowLength to round(sqrt(4*L*log(2)/pi)), HopLength to 8, and NumFrequencyBins to 128.

dgt(fftshift(g),WindowLength=round(sqrt(4*L*log(2)/pi)), ...
    HopLength=8,NumFrequencyBins=128)

Input Arguments

x — Input signal

vector | timetable

Input signal, specified as a vector or a timetable with a single variable containing a vector. If x is a timetable, it must contain finite and uniformly increasing row times.

If the signal length is not an integer multiple of the least common multiple (LCM) of the hop length, HopLength, and the length of the Gaussian window, WindowLength, the dgt function zero-pads the signal to the nearest largest length that is a multiple of this LCM.

Data Types: single | double
Complex Number Support: Yes

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Example: d=dgt(x,SampleRate=1e3,WindowLength=512) specifies a sample rate of 1kH and a Gaussian window whose length is 512 samples.

WindowLength — Gaussian window length

128 (default) | positive integer

Gaussian window length in samples, specified as a positive integer. The window length also determines the time-frequency ratio (TFR) of the window. For more information, see Time-Frequency Ratio.

Data Types: single | double

HopLength — Hop length

32 (default) | nonnegative integer

Hop length or time shift of the Gaussian windows in samples, specified as a nonnegative integer. The hop length affects the overlap between the windows and thus the time resolution of the transform.

Data Types: single | double

NumFrequencyBins — Number of frequency bins

256 (default) | positive integer

Number of frequency bins to use to calculate the DGT, specified as a positive integer. The number of bins determines the frequency resolution in the time-frequency representation of the signal.

Data Types: single | double

SampleRate — Sample rate

positive scalar

Sample rate of the input signal in hertz, specified as a positive scalar. If you do not specify a sample rate, normalized frequency is used. If x is a timetable, you cannot specify a sample rate. The function determines the sample rate from the row times in the timetable.

Data Types: single | double

FrequencyRange — DGT frequency range

"centered" (default) | "onesided" | "twosided"

DGT frequency range, specified as "centered", "onesided", or "twosided".

• "centered" — Compute a two-sided and centered DGT. d is computed over the interval (−1/2,1/2] if NumFrequencyBins is even and (−1/2,1/2) if NumFrequencyBins is odd. If you specify time information, the intervals become (−Fs/2,Fs/2] and (−Fs/2,Fs/2), respectively, where Fs is the effective sample rate.

• "onesided" — Compute a one-sided DGT. d is computed over the interval [0,1/2] if NumFrequencyBins is even and [0,1/2) if NumFrequencyBins is odd. If you specify time information, the intervals become [0,Fs/2] and [0,Fs/2), respectively, where Fs is the effective sample rate.

• "twosided" — Compute a two-sided DGT over the interval [0,1). If you specify time information, the interval is [0,Fs), where Fs is the effective sample rate.

Output Arguments

d — Discrete Gabor transform

matrix

Discrete Gabor transform of x, returned as a matrix. Time increases across the columns and frequency increases down the rows.

f — Frequencies

vector

Frequencies at which the DGT is evaluated, returned as a vector. If you specify time information, f is in hertz. Otherwise, f is in cycles per sample. The length of f and number of rows in d are equal.

t — Time instants

vector

Time instants at which the DGT is evaluated, returned as a vector. If x is a timetable, t has the same data type and format as the row times in x. If you specify time information, t contains the time values in seconds. Otherwise, t is in sample numbers. The length of t and the number of columns in d are equal.

More About

Time-Frequency Ratio

The time-frequency ratio (TFR) is the ratio between the effective support of the Gaussian window in time and in frequency. The TFR is computed as $$\pi W^2/4L\log 2$$, where W is the length of the Gaussian window in samples and L is the length of the input signal. The periodic Gaussian is given by

$$g_p={\displaystyle \sum _{p=-P}^{P}g}(l-pL),$$

where $$g(l)=\exp \left(-\pi \frac{l^2}{L\text{TFR}}\right),l=0,\dots ,L-1$$ and $$P=\lceil 4/\sqrt{\raisebox{1ex}{$L$}\!\left/ \!\raisebox{-1ex}{$\sqrt{\text{TFR}}$}\right.}\rceil$$ [2].

If the TFR is greater than 1, then the window has a wider support in the time domain.

Discrete Gabor Transform

The discrete Gabor transform (DGT) is a commonly used transform in signal analysis and synthesis, especially when a linear frequency scale is required. The DGT of a discrete signal is computed based on the canonical tight window of a Gabor frame with a periodic Gaussian window [3]. The DGT is computed by sliding the Gaussian window over the signal and calculating the DGT of each segment of windowed data.

The DGT of a discrete signal x is given as:

$$D(m,n)={\displaystyle \sum _{l=0}^{L-1}x}(l)\overline{g(l-an)}{e}^{-2\pi ılm/M},$$

where:

• g(l) is the (analysis) window function (filter prototype) that localizes the signal in time and in frequency. The bar over the window function indicates complex conjugate.

• a is the hop length, which determines how much the window is shifted for each time step.

• M is the number of frequency points (frequency bins), determining the frequency resolution.

• L is the signal length that satisfies L = a N = b M, where N and b are positive integers.

• D(m,n) are the time-frequency coefficients, representing the signal's content at time index n and frequency index m.

By default, the dgt function shifts the Gaussian window, whose length is 128 samples, by 32 samples in time. This yields an overlap of 75%.

References

[1] Qian, S., and D. Chen. “Discrete Gabor Transform.” IEEE Transactions on Signal Processing 41, no. 7 (July 1993): 2429–38. https://doi.org/10.1109/78.224251.

[2] Mallat, S.G. and Zhifeng Zhang. “Matching Pursuits with Time-Frequency Dictionaries.” IEEE Transactions on Signal Processing 41, no. 12 (December 1993): 3397–3415. https://doi.org/10.1109/78.258082.

[3] Søndergaard, Peter. “An Efficient Algorithm for the Discrete Gabor Transform Using Full Length Windows.” In SAMPTA ’09 International Conference on SAMPling Theory and Applications, edited by Laurent Fesquet and Bruno Torresani, 223–26. Marseille, France, 2009. https://hal.science/hal-00495456/file/SampTAProceedings.pdf.

[4] Søndergaard, Peter. “Finite Discrete Gabor Analysis.” Ph.D. Thesis, Technical University of Denmark, 2007. https://orbit.dtu.dk/files/4697157/main.pdf.

Extended Capabilities

C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.

GPU Arrays

Accelerate code by running on a graphics processing unit (GPU) using Parallel Computing Toolbox™.

The dgt function fully supports GPU arrays. To run the function on a GPU, specify the input data as a gpuArray (Parallel Computing Toolbox). For more information, see Run MATLAB Functions on a GPU (Parallel Computing Toolbox).

Version History

Introduced in R2025a