matlab/matlab-agentic-toolkit / skills-catalog/signal-processing/matlab-analyze-time-frequency-content
matlab-analyze-time-frequency-content
UnverifiedPerform 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.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 10.7 KB |
| manifest.yaml | config | 517 B |
| references/cross-analysis-guide.md | markdown | 11.7 KB |
| references/cwt-guide.md | markdown | 22.3 KB |
| references/method-selection-guide.md | markdown | 6.2 KB |
| references/multiresolution-guide.md | markdown | 17.9 KB |
| references/reassignment-guide.md | markdown | 11.8 KB |
| references/stft-guide.md | markdown | 16.4 KB |
| scripts/assessBoundary.m | other | 3.1 KB |
| scripts/assessSignalForTF.m | other | 4.8 KB |
| scripts/assessSpectralEnergy.m | other | 3.4 KB |
| scripts/boundaryExDisjointSine.mat | binary | 7.6 KB |
| scripts/illustrateBoundary.m | other | 902 B |
| scripts/illustrateTransientLocalization.m | other | 1.3 KB |
| scripts/plotAntiAnalyticScalogram.m | other | 831 B |
references/reassignment-guide.md
View on GitHub# Time-Frequency Reassignment Guide
## Overview
Reassignment techniques sharpen time-frequency representations by moving energy from each analysis bin to a more precise location. Two fundamentally different approaches exist:
1. **Full reassignment** (time + frequency) — produces the sharpest visual picture but is **not invertible**. Energy is displaced in both axes, destroying the structure needed for reconstruction.
2. **Synchrosqueezing** (frequency only) — reassigns energy only along the frequency axis toward instantaneous frequency. Because the time axis is untouched, the transform remains **invertible** — individual oscillatory modes can be extracted and reconstructed.
Choose full reassignment for visualization and detection. Choose synchrosqueezing when you need to extract and reconstruct individual signal components.
## Function Landscape
| Function | Domain | Type | Invertible | Toolbox |
|----------|--------|------|------------|---------|
| `fsst` | STFT | Synchrosqueezing | Yes (`ifsst`) — machine precision | Signal Processing |
| `wsst` | CWT | Synchrosqueezing | Yes (`iwsst`) — approximate (Morlet formula) | Wavelet |
| `spectrogram(..., "reassigned")` | STFT | Full reassignment | No | Signal Processing |
| `pspectrum(..., Reassigned=true)` | STFT | Full reassignment | No | Signal Processing |
**No reassignment option exists for:**
- `stft` / `istft` — use `fsst` instead for STFT-domain synchrosqueezing
- `cwt` — use `wsst` instead for CWT-domain synchrosqueezing
## When to Use
- **Visualization only (sharpest picture):** `spectrogram("reassigned")` or `pspectrum(Reassigned=true)`
- **Mode extraction + reconstruction (STFT domain):** `fsst` → `tfridge` → `ifsst`
- **Mode extraction + reconstruction (CWT domain):** `wsst` → `wsstridge` → `iwsst`
## Full Reassignment: spectrogram / pspectrum
Full reassignment displaces each STFT coefficient to the local centroid of the Wigner-Ville distribution — both in time (group delay) and frequency (instantaneous frequency). The result is maximally concentrated but non-invertible.
### spectrogram (reassigned)
```matlab
[s, f, t] = spectrogram(x, window, noverlap, nfft, fs, "reassigned");
```
- Returns reassigned time-frequency matrix directly
- Same window/overlap/nfft interface as standard spectrogram
- The `"reassigned"` flag is a trailing positional argument
### pspectrum (reassigned)
```matlab
[p, f, t] = pspectrum(x, fs, "spectrogram", Reassigned=true);
```
- Name-value syntax: `Reassigned=true`
- Built-in resolution/leakage controls via `FrequencyResolution`, `Leakage`
- Output is power spectrum (not complex STFT coefficients)
### Limitations
- **Not invertible** — cannot reconstruct individual signal components
- **Ridge extraction still works** — use `tfridge` on the reassigned matrix for instantaneous frequency estimation, but you cannot invert back to time domain from the reassigned representation alone
- Useful for detection, classification, and visualization — not for signal separation
## STFT Synchrosqueezing: fsst / ifsst
### Forward Transform
```matlab
[sst, f, t] = fsst(x, fs); % default: Kaiser(256, beta=10)
[sst, f, t] = fsst(x, fs, window); % custom window
fsst(x, fs); % no outputs → auto-plot
```
**Key constraints:**
- Overlap is **always** `window_length - 1` (hop = 1 sample) — not configurable
- `nfft = window_length` — DFT length equals window length
- Real input → one-sided spectrum; complex input → two-sided centered spectrum
### Inverse Transform
```matlab
xrec = ifsst(sst); % full reconstruction
xrec = ifsst(sst, window, f, [flo fhi]); % frequency-range reconstruction
xrec = ifsst(sst, window, iridge); % mode extraction via ridge
xrec = ifsst(sst, [], iridge, NumFrequencyBins=4); % control bandwidth around ridge
```
- **Full reconstruction is machine-precision** (~1e-14 error)
- Window must match the forward `fsst` call
- Ridge-based extraction: pass `iridge` from `tfridge`
### Ridge Extraction with tfridge
```matlab
[fridge, iridge] = tfridge(sst, f, penalty);
[fridge, iridge] = tfridge(sst, f, penalty, NumRidges=2);
```
- `tfridge` is generic — works on any TF matrix (fsst, spectrogram, wsst, etc.)
- Default penalty = 0 (no smoothing)
## CWT Synchrosqueezing: wsst / iwsst
### Forward Transform
```matlab
[sst, f] = wsst(x, fs); % default: amor wavelet, VoicesPerOctave=32
[sst, f] = wsst(x, fs, 'bump'); % specify wavelet
[sst, f, fbparam] = wsst(x, fs, 'bump', VoicesPerOctave=32);
wsst(x, fs); % no outputs → auto-plot
```
**Key details:**
- Only accepts **real-valued** signals
- Default wavelet is `"amor"` (not Morse like `cwt`)
- VoicesPerOctave must be **even**, range 10–48, default 32
- **Subtracts the signal mean** before analysis internally
- Supports `Boundary`: `"periodic"` (default), `"reflection"`, `"zeropad"`
### Inverse Transform
```matlab
xrec = iwsst(sst); % full reconstruction (approximate)
xrec = iwsst(sst, 'bump'); % specify wavelet (must match forward)
xrec = iwsst(sst, iridge); % mode extraction
xrec = iwsst(sst, iridge, NumFrequencyBins=16); % control bandwidth
xrec = iwsst(sst, f, [flo fhi]); % frequency-range reconstruction
```
- **Reconstruction is approximate** — uses Morlet single-integral formula (`2/Rpsi * real(sum(sst,1))`)
- Wavelet must match between `wsst` and `iwsst`
- Default NumFrequencyBins = 16 (half of default VoicesPerOctave=32)
- `wsst` subtracts the mean but `iwsst` does NOT add it back — user must add `mean(x)` if needed
### Ridge Extraction with wsstridge
```matlab
[fridge, iridge] = wsstridge(sst, penalty, f, NumRidges=2);
```
- `wsstridge` is `wsst`-specific — handles filter bank parameters and log-spaced frequency
- Penalty is the **2nd positional argument** (before `f`)
- Calls the same underlying engine as `tfridge`: `signalwavelet.internal.tfridge.extractRidges`
## Penalty Term for Ridge Extraction
### Why It's Needed
Without a penalty, the ridge extraction is purely greedy — it picks the bin with maximum energy at each time step. When a component's amplitude dips below competing energy (noise, another mode), the ridge **jumps** to the wrong frequency.
### When to Use
- **Multiple ridges** (`NumRidges > 1`) — almost always needed to prevent cross-assignment between modes
- **Single modulated component in noise** — prevents jumping to noise peaks during amplitude dips
- **FM signals** — prevents short-cutting across rapid frequency excursions
### How It Works
The penalty adds cost `penalty × (distance_in_bins)²` for changing frequency between adjacent time steps. This trades energy-maximization against trajectory smoothness.
**The penalty operates in bins, not Hz.** For `wsst` (log-spaced bins), the physical frequency change per bin varies with frequency. For `fsst` (linear bins), it's uniform.
### Value Selection
No automatic method exists. Start with penalty = 5 and adjust:
- Too low → ridge still jumps between modes
- Too high → over-smooths, can't track legitimate rapid frequency changes (FM content)
## Synchrosqueezing Can Rescue CWT's Constant-Q Limitation
CWT's constant-Q property means bandwidth grows with frequency — closely-spaced high-frequency tones get smeared together. `wsst` can **partially rescue** this by concentrating the smeared energy back toward the true instantaneous frequencies.
```matlab
% DTMF tones: CWT smears high-freq group, wsst sharpens them
[sst, f] = wsst(tones, Fs, 'bump');
```
**Decision hierarchy:**
1. Tones well-separated relative to bandwidth → raw `cwt` works
2. Tones moderately close → `wsst` sharpens enough to resolve
3. Tones within 2Δ of each other → synchrosqueezing also fails → use `stft`/`fsst`
## Resolvability Condition
For synchrosqueezing (both `fsst` and `wsst`) to resolve two modes:
`|φ₁'(t) - φ₂'(t)| > 2Δ`
where:
- `φ'(t)` = instantaneous frequency of each mode
- `Δ` = bandwidth of the analysis wavelet/window at that frequency
**Implications:**
- Parallel chirps with constant separation: resolvable if separation > 2Δ everywhere
- Crossing chirps: always unresolvable at the crossing point (IF difference = 0)
- For CWT/wsst (constant-Q): Δ grows with frequency → harder to resolve at high frequencies
- For STFT/fsst: Δ is fixed by window → uniform resolving ability
## Precision Sensitivity
The synchrosqueezing algorithm reassigns energy to the nearest frequency bin based on estimated instantaneous frequency. In single precision, rounding at bin boundaries causes off-by-one differences in reassignment.
**Affected scenarios:**
- **Code generation** (C/C++ via MATLAB Coder) — results may differ from MATLAB
- **GPU arrays** (Parallel Computing Toolbox) — floating-point order-of-operations differs from CPU
**Recommendation:** Use **double-precision** data with `fsst`/`wsst` when:
- Comparing results across MATLAB, codegen, and GPU
- Ridge extraction must be reproducible
- Mode reconstruction fidelity matters
## Complete Workflow: Mode Extraction
### STFT-based (fsst)
```matlab
% 1. Compute synchrosqueezed STFT
[sst, f, t] = fsst(x, fs, kaiser(256, 10));
% 2. Extract ridges with penalty
[fridge, iridge] = tfridge(sst, f, 5, NumRidges=2);
% 3. Reconstruct individual modes
xmode1 = ifsst(sst, kaiser(256, 10), iridge(:,1));
xmode2 = ifsst(sst, kaiser(256, 10), iridge(:,2));
```
### CWT-based (wsst)
```matlab
% 1. Compute synchrosqueezed CWT
[sst, f] = wsst(x, fs, 'bump');
% 2. Extract ridges with penalty
[fridge, iridge] = wsstridge(sst, 5, f, NumRidges=2);
% 3. Reconstruct individual modes
xrec = iwsst(sst, iridge);
xmode1 = xrec(:,1);
xmode2 = xrec(:,2);
```
## Common Mistakes
| Mistake | Why It's Wrong | Correct Approach |
|---------|---------------|-----------------|
| Using `stft` and expecting reassignment | `stft` has no reassignment option | Use `fsst` for invertible synchrosqueezing, or `spectrogram("reassigned")` for visualization |
| Omitting penalty with `NumRidges > 1` | Ridges jump between modes at energy crossings | Always use penalty ≥ 1 when extracting multiple ridges |
| Expecting `iwsst` to give exact reconstruction | `iwsst` uses Morlet single-integral (approximate) | Accept the approximation, or use `fsst`/`ifsst` for machine-precision reconstruction |
| Forgetting to add back the mean after `iwsst` | `wsst` internally subtracts `mean(x)` but `iwsst` doesn't restore it | Add `mean(x)` to the reconstruction if DC level matters |
| Using single precision with `fsst`/`wsst` | Off-by-one bin reassignment differences vs double | Use double precision for reproducible results across MATLAB/codegen/GPU |
| Expecting synchrosqueezing to resolve modes within 2Δ | Resolvability condition requires IF separation > 2× bandwidth | If modes are too close, switch to STFT with narrow window |
| Using `wsstridge(sst, f, penalty, ...)` | Penalty is the 2nd argument for `wsstridge`, before `f` | `wsstridge(sst, penalty, f, NumRidges=n)` |
| Using `tfridge(tfm, f)` without penalty for FM signals | FM components have time-varying frequency — greedy search jumps | Add penalty: `tfridge(tfm, f, penalty)` |
## Documentation References
| Topic | Link |
|-------|------|
| `fsst` reference | https://www.mathworks.com/help/signal/ref/fsst.html |
| `ifsst` reference | https://www.mathworks.com/help/signal/ref/ifsst.html |
| `tfridge` reference | https://www.mathworks.com/help/signal/ref/tfridge.html |
| `wsst` reference | https://www.mathworks.com/help/wavelet/ref/wsst.html |
| `iwsst` reference | https://www.mathworks.com/help/wavelet/ref/iwsst.html |
| `wsstridge` reference | https://www.mathworks.com/help/wavelet/ref/wsstridge.html |
| Time-frequency reassignment and mode extraction | https://www.mathworks.com/help/wavelet/ug/time-frequency-reassignment-and-mode-extraction-with-synchrosqueezing.html |
----
Copyright 2026 The MathWorks, Inc.
----
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |