Time-Frequency Analysis in MATLAB

Analyze how frequency content evolves over time using STFT, CWT, synchrosqueezing, reassignment, cross-signal methods, and data-adaptive decomposition.

Agent directive: Consult the reference guides in references/ before answering. Each guide covers a specific domain with syntax, gotchas, and common mistakes.

When To Use

• Analyzing how frequency content evolves over time (spectrogram, scalogram)
• Choosing between STFT, CWT, synchrosqueezing, reassignment, or EMD/VMD
• Extracting and reconstructing individual signal components from a TF representation
• Computing time-varying coherence or cross-spectrum between two signals
• Decomposing signals into additive time-domain components (wavelet MRA, EMD, VMD)
• Estimating instantaneous frequency or Hilbert spectrum

When Not To Use

• Designing or applying classical FIR/IIR filters — use matlab-design-digital-filter
• Extracting scalar features for ML classification — use matlab-extract-signal-features
• Signal preprocessing (resampling, detrending, gap filling) — use matlab-prepare-signal-data
• Quadratic/bilinear TFDs (Wigner-Ville) — not supported in MATLAB toolboxes
• Audio-specific representations (mel spectrogram, MFCC) — use Audio Toolbox

Method Selection

Choose the analysis method based on the user's goal and signal characteristics:

For detailed decision logic, see references/method-selection-guide.md.

Quick Decision Tree

What is the primary goal?
│
├── Interactive exploration (adjust parameters, compare views)
│   └── signalAnalyzer — supports spectrogram + scalogram (CWT) side by side
│
├── Visualize one signal's TF content
│   ├── Need uniform frequency resolution? → stft / spectrogram / pspectrum
│   ├── Need multi-resolution (better low-freq)? → cwt
│   └── Need sharpest picture (no reconstruction)? → spectrogram("reassigned")
│
├── Remove unwanted content visible in spectrogram
│   └── Define binary mask over TF plane → tffilt (Gabor domain)
│
├── Extract and reconstruct individual components
│   ├── From TF representation (invertible)?
│   │   ├── STFT domain → fsst → tfridge → ifsst
│   │   └── CWT domain → wsst → wsstridge → iwsst
│   ├── Additive time-domain components?
│   │   ├── Octave bands → modwt + modwtmra
│   │   ├── Uniform bands → modwptdetails
│   │   └── Data-adaptive → emd or vmd
│   └── From CWT directly? → icwt (see references/cwt-guide.md)
│
├── Compare two signals
│   ├── Time-varying coherence? → wcoherence
│   ├── Time-varying cross-spectrum? → xspectrogram
│   └── Global relationship? → mscohere / cpsd
│
└── Estimate instantaneous frequency
    ├── Single monocomponent signal? → instfreq(x, fs)
    ├── Multicomponent (want per-mode IF)? → emd → instfreq(imf, fs)
    └── Multicomponent (want single average)? → instfreq(x, fs, Method="tfmoment")

Critical Rules

1. stft has no reassignment option. Use fsst for invertible synchrosqueezing or spectrogram("reassigned") for non-invertible visualization.

2. wsstridge argument order differs from tfridge:

   • wsstridge(sst, penalty, f, ...) — penalty is 2nd positional arg
   • tfridge(tfm, f, penalty, ...) — penalty is 3rd positional arg

3. wsst subtracts the signal mean internally. iwsst does NOT restore it. Add mean(x) back manually if DC matters.

4. ifsst is machine-precision; iwsst is approximate (Morlet single-integral formula).

5. xspectrogram first output is real (cross-spectrogram magnitude). For phase, use the 4th output P. This differs from spectrogram whose first output is complex STFT.

6. wcoherence has no Parent option. For App Designer, compute outputs and plot manually.

7. wcoherence phase arrows show the phase lag of Y relative to X:

   • ↑ = Y lags X by π/2
   • ↓ = Y leads X by π/2
   • → = in-phase
   • ← = anti-phase PhaseDisplayThreshold (default 0.5) is plot-only — it controls which arrows are drawn but has no effect on returned numeric outputs.

8. hht takes IMFs, not raw signal. Always decompose first: imf = emd(x); hht(imf, fs).

9. instfreq Hilbert method is meaningless for multicomponent signals. Decompose first, or use Method="tfmoment" for a single average curve.

10. Synchrosqueezing is precision-sensitive. Use double-precision data with fsst/wsst for reproducible results across MATLAB, codegen, and GPU.

Signal Assessment Workflow

When the user provides a signal and asks "what should I use?", run the assessment script then apply agent-side interpretation:

Step 1: Run MATLAB assessment

report = assessSignalForTF(x, fs);
disp(report)
disp(report.recommendations)

The script returns: signal length, occupied bandwidth, number of spectral peaks (with frequencies), nonstationarity indicator, DC content, precision, and auto-generated recommendations.

Step 2: Agent-side interpretation (combine script output with user goals)

Step 3: Refine with follow-up questions if ambiguous

• "Do you need to reconstruct the signal, or just visualize?"
• "Do you need uniform frequency resolution, or is multi-resolution acceptable?"
• "Are you comparing this signal to another?"

Reference Guides

Toolbox Requirements

Documentation References

Copyright 2026 The MathWorks, Inc.