---

name: matlab-analyze-time-frequency-content description: > Perform time-frequency analysis in MATLAB using CWT, STFT, synchrosqueezing, reassignment, wavelet coherence, cross spectrogram, EMD/VMD, multiresolution analysis, and time-frequency filtering. Triggers on: time-frequency, spectrogram, scalogram, cwt, stft, istft, fsst, wsst, wcoherence, xspectrogram, modwt, modwtmra, modwpt, emd, vmd, hht, tffilt, dgt, gabor, instantaneous frequency, synchrosqueezing, reassignment, ridge extraction, wavelet coherence, cross spectrum, mode decomposition, signal decomposition, time-frequency filtering. license: https://www.mathworks.com/content/dam/mathworks/license/pmrl/license.md metadata: author: MathWorks version: "2.0"

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:

| Goal | Method | Guide | |------|--------|-------| | Interactive TF exploration (spectrogram + scalogram) | signalAnalyzer | — | | General TF visualization (uniform freq resolution) | stft, spectrogram, pspectrum | references/stft-guide.md | | TF visualization (multi-resolution, constant-Q) | cwt, cwtfilterbank | references/cwt-guide.md | | Sharpest TF picture (non-invertible) | spectrogram("reassigned"), pspectrum(Reassigned=true) | references/reassignment-guide.md | | Remove specific TF regions (mask-based filtering) | tffilt with binary mask | references/stft-guide.md | | Mode extraction + reconstruction (STFT domain) | fsst → tfridge → ifsst | references/reassignment-guide.md | | Mode extraction + reconstruction (CWT domain) | wsst → wsstridge → iwsst | references/reassignment-guide.md | | Signal reconstruction from CWT | icwt (exact or approximate) | references/cwt-guide.md | | Additive decomposition (octave bands) | modwt + modwtmra | references/multiresolution-guide.md | | Additive decomposition (uniform bands) | modwptdetails | references/multiresolution-guide.md | | Adaptive decomposition (unknown components) | emd | references/multiresolution-guide.md | | Adaptive decomposition (known mode count) | vmd | references/multiresolution-guide.md | | Hilbert spectrum / instantaneous frequency | hht, instfreq | references/multiresolution-guide.md | | Time-varying coherence between two signals | wcoherence | references/cross-analysis-guide.md | | Cross spectrogram between two signals | xspectrogram | references/cross-analysis-guide.md | | Global coherence (no time axis) | mscohere, cpsd | references/cross-analysis-guide.md |

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)

| User Goal | Key Report Fields | Recommendation Logic | |-----------|-------------------|---------------------| | "Explore / I'm not sure what I need" | — | Suggest signalAnalyzer for interactive exploration (spectrogram + scalogram views, adjustable parameters) | | "Visualize frequency content over time" | likelyNonstationary, fractionalBandwidth | If wideband (>2 octaves): cwt. If narrowband or uniform resolution needed: stft/spectrogram | | "Separate/extract components" | numSpectralPeaks, peakFrequenciesHz | 2–3 peaks: synchrosqueezing (fsst/wsst). Many peaks: emd/vmd. Closely-spaced: modwptdetails or fsst | | "Reconstruct after filtering" | hasDC, precision | fsst/ifsst for exact. wsst/iwsst for CWT-domain (warn about mean). icwt for CWT bandpass | | "Compare two signals" | (run on both) | wcoherence for coherence. xspectrogram for cross-spectrum | | "Detect transients/events" | signalLength, occupiedBandHz | cwt with low TimeBandwidth. Or short-window stft |

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

| File | Coverage | |------|----------| | references/stft-guide.md | stft/istft, spectrogram, pspectrum, stftmag2sig, length preservation, COLA | | references/cwt-guide.md | cwt, cwtfilterbank, icwt, dlicwt/icwtLayer, boundary, constant-Q | | references/reassignment-guide.md | fsst/ifsst, wsst/iwsst, spectrogram("reassigned"), pspectrum(Reassigned=true), ridge extraction, penalty | | references/cross-analysis-guide.md | wcoherence, xspectrogram, cpsd, mscohere, phase arrows, unsmoothed cross-spectrum | | references/multiresolution-guide.md | modwt/modwtmra, modwpt/modwptdetails, emd, vmd, hht, instfreq, instbw | | references/method-selection-guide.md | Decision logic for choosing among all methods |

Toolbox Requirements

| Toolbox | Functions | |---------|-----------| | Signal Processing | stft, istft, spectrogram, pspectrum, fsst, ifsst, tfridge, xspectrogram, instfreq, instbw, stftmag2sig, cpsd, mscohere | | Wavelet | cwt, cwtfilterbank, icwt, wsst, iwsst, wsstridge, wcoherence, modwt, modwtmra, modwpt, modwptdetails, emd, vmd, hht, tffilt, dgt |

| Function | Available From | Note | |----------|---------------|------| | tffilt | R2025a | TF mask-based filtering; all other functions available in R2024b |

Documentation References

| Topic | Link | |-------|------| | Time-frequency gallery | https://www.mathworks.com/help/signal/time-frequency-analysis.html | | Wavelet time-frequency | https://www.mathworks.com/help/wavelet/time-frequency-analysis.html | | CWT reference | https://www.mathworks.com/help/wavelet/ref/cwt.html | | STFT reference | https://www.mathworks.com/help/signal/ref/stft.html | | Synchrosqueezing example | https://www.mathworks.com/help/wavelet/ug/time-frequency-reassignment-and-mode-extraction-with-synchrosqueezing.html | | Wavelet coherence example | https://www.mathworks.com/help/wavelet/ug/compare-time-frequency-content-in-signals-with-wavelet-coherence.html |

---

Copyright 2026 The MathWorks, Inc.

---