Skip to content

matlab/matlab-agentic-toolkit / skills-catalog/signal-processing/matlab-prepare-signal-data

matlab-prepare-signal-data

Verified

Use this skill when conditioning, loading, preparing, or labeling signal data for analysis or ML training. Covers: cleaning a single signal (fill gaps, remove drift, deoutlier, denoise, resample/align a time base) BEFORE analysis; building a `signalDatastore` pipeline; creating a `labeledSignalSet` for Signal Labeler; deriving labels (filename, folder, in-file, ROI, time-frequency ROI); stratified train/val/test splits; framing long signals; parallel processing; and shaping datastore output for `trainnet`. Triggers include "clean up this signal", "remove drift / detrend", "fill gaps", "remove spikes / outliers", "denoise", "resample to a uniform rate", "align channels", "labels from filenames", "stratified split", "prepare for Signal Labeler", and function names like `fillgaps`, `fillmissing`, `detrend`, `filloutliers`, `smoothdata`, `resample`, `synchronize`, `signalDatastore`, `labeledSignalSet`, `filenames2labels`, `folders2labels`, `splitlabels`, `framesig`, `framelbl`, `createDatastores`.

FileKindSize
SKILL.mdskill md9.5 KB
manifest.yamlconfig650 B
references/fn-countlabels.mdmarkdown2.1 KB
references/fn-detrend.mdmarkdown4.6 KB
references/fn-filenames2labels.mdmarkdown4.8 KB
references/fn-fillgaps.mdmarkdown3.3 KB
references/fn-fillmissing.mdmarkdown4.2 KB
references/fn-filloutliers.mdmarkdown5.0 KB
references/fn-folders2labels.mdmarkdown3.4 KB
references/fn-framelbl.mdmarkdown7.1 KB
references/fn-framesig.mdmarkdown4.1 KB
references/fn-hampel.mdmarkdown3.3 KB
references/fn-labeledsignalset.mdmarkdown9.1 KB
references/fn-labelspectrogramoptions.mdmarkdown4.6 KB
references/fn-medfilt1.mdmarkdown3.3 KB
references/fn-partition.mdmarkdown4.6 KB
references/fn-resample.mdmarkdown4.6 KB
references/fn-retime.mdmarkdown4.7 KB
references/fn-sgolayfilt.mdmarkdown3.5 KB
references/fn-signaldatastore.mdmarkdown11.9 KB
references/fn-signallabeldefinition.mdmarkdown5.9 KB
references/fn-signalmask-getmask.mdmarkdown8.6 KB
references/fn-smoothdata.mdmarkdown4.8 KB
references/fn-splitlabels.mdmarkdown5.3 KB
references/fn-subset.mdmarkdown3.9 KB
references/fn-synchronize.mdmarkdown4.7 KB
references/fn-wdenoise.mdmarkdown5.2 KB
references/wf-align-channels.mdmarkdown6.6 KB
references/wf-custom-readfcn.mdmarkdown5.0 KB
references/wf-denoise.mdmarkdown2.6 KB
references/wf-detrend-smooth-deoutlier.mdmarkdown6.6 KB
references/wf-envelope.mdmarkdown5.3 KB
references/wf-frame-and-label.mdmarkdown4.7 KB
references/wf-handoff-to-dl.mdmarkdown9.1 KB
references/wf-label-and-export.mdmarkdown8.7 KB
references/wf-load-and-split.mdmarkdown4.6 KB
references/wf-parallel-process.mdmarkdown4.8 KB
references/wf-repair-missing.mdmarkdown6.7 KB
references/wf-uniform-rate.mdmarkdown4.2 KB

references/fn-framelbl.md

View on GitHub
# Function: `framelbl`

> Used in: wf-frame-and-label.md
> Toolbox: Signal Processing Toolbox

Collapse a per-sample ROI label table into **per-frame** labels, using a
frame schedule that matches `framesig`. Replaces the hand-rolled
`containers.Map` accumulator and the most-prevalent voting loop.

## Signature

```matlab
frameLabels = framelbl(x, frameLength)
frameLabels = framelbl(x, frameLength, Name=Value, ...)
[frameLabels, fnlcond] = framelbl(___)               % final condition for streaming (overlap)
[frameLabels, fnlcond, fnlidx] = framelbl(___)       % + final index for streaming (underlap)
```

`x` is the input label sequence — accepts:
- **categorical** vector
- **string** array
- **numeric** array
- **logical** matrix (one column per category)
- **ROI table** (start/end limits + label per row — the most common form)

Output shape depends on `ConsolidationMethod`:

- **Consolidated** (`ConsolidationMethod` set to `"mode"` / `"priority"` /
  `"max"` / `"median"` / `"mean"`): returns a `1 × numFrames` row vector of
  per-frame consolidated labels, aligned with `framesig`'s column index.
- **Non-consolidated** (`ConsolidationMethod="none"`, the default): returns
  an `fl × numFrames` matrix for string / numeric / logical inputs (one
  column per frame, one row per sample within that frame). Categorical
  input returns the same per-sample-per-frame layout as a categorical
  matrix.

## Name-value arguments (all 11)

Valid combinations depend on input type — see the cross-table below.

| NV-pair | Default | Purpose |
|---|---|---|
| `InputLabelMode` | `"mask"` | `"mask"` = each element of `x` is a per-sample label; `"attribute"` = `x` is a single label that applies to every sample (requires `SignalLength`). |
| `SignalLength` | inferred from ROI / required for `"attribute"` | Length of the underlying signal in samples. Must exceed `frameLength`. For ROI tables, defaults to `max(ROILimits)`. |
| `SampleRate` | unset | Positive scalar; only valid when `x` is an ROI table. When set, ROI limits are interpreted in **seconds** and converted to sample indices (rounded to nearest integer). |
| `Categories` | inferred | String array naming logical-matrix columns. Only valid when `x` is a logical matrix. |
| `ConsolidationMethod` | `"none"` | How to collapse multiple labels in a frame: `"none"` (no collapse — return raw per-frame), `"mode"` (most-prevalent vote), `"priority"` (rank-based, requires `PriorityList`), `"max"` (numeric / ordinal categorical), `"median"` (numeric / ordinal), `"mean"` (numeric only). Type restrictions: categorical/string allow only `"mode"` / `"priority"` (or `"median"` / `"max"` for ordinal); numeric forbids `"priority"`. |
| `PriorityList` | inferred | Rank-ordered list of unique labels for `ConsolidationMethod="priority"` (or for ROI / logical inputs). Highest priority first. Defaults to lex-ordered for non-logical, or `Categories` for logical. |
| `OverlapLength` | `0` | Samples shared between adjacent frames. **Must match `framesig`**'s `OverlapLength`. Mutually exclusive with `UnderlapLength`. |
| `UnderlapLength` | `0` | Samples skipped between adjacent frames. Mutually exclusive with `OverlapLength`. |
| `InitialCondition` | `[]` | Stacks on top of `x` along the framing dimension. Must match `x`'s data type and shape. For ROI-table inputs, must also be an ROI table whose limits don't overlap the input. Forbidden when `InputLabelMode="attribute"`. |
| `InitialIndex` | `1` | Index of the first sample to start framing from. `InitialIndex - 1` samples at the start are discarded. |
| `IncompleteFrameRule` | `"drop"` | What to do with the trailing partial frame: `"drop"` discards it; `"padwithmissing"` pads with `<undefined>` / `<missing>` / `<false>` / `NaN` depending on label type. (Note: this is `"padwithmissing"`, not `"zeropad"` as in `framesig`.) |

> Setting both `OverlapLength` and `UnderlapLength` is an error — they are
> alternative scheduling modes, not stackable. **Don't pass both names even
> at default values** (e.g. `OverlapLength=0, UnderlapLength=4` errors too).
> Pass at most one.

## Canonical pattern

```matlab
% Frame the signal:
frames = framesig(x, 1024, OverlapLength=512);

% Frame the labels with the same schedule:
frameLabels = framelbl(rois, 1024, OverlapLength=512, ...
    ConsolidationMethod="mode");

% frames(:, k) and frameLabels(k) are aligned.
```

## `ConsolidationMethod` — the default surprises you

The default is `"none"`, which returns an **`fl × numFrames` matrix of raw
per-sample labels**, not the `1 × numFrames` row of one-label-per-frame a
training pipeline usually wants. Pass an explicit `ConsolidationMethod` (and
read it as a named arg so the choice is visible), e.g.:

```matlab
frameLabels = framelbl(rois, 1024, OverlapLength=512, ConsolidationMethod="mode");
```

Choosing *which* method - `"mode"` (most-prevalent vote) vs `"priority"` (when
labels nest), and the ROI-containment check that decides it - is the workflow
decision: see wf-frame-and-label.md ("Decision point — ConsolidationMethod").
The mechanism that forces `"priority"` when labels nest is the containment trap
below.

## Anti-pattern — hand-rolled most-prevalent voting

Don't accumulate per-sample labels into a `containers.Map` and pick the
most-prevalent — that has a containment trap.

```matlab
% Bad — hand-rolled voting buries the containment trap:
labelMap = containers.Map();
for k = 1:numFrames
    frameStart = (k-1)*hopSize + 1;
    frameEnd   = frameStart + frameLength - 1;
    % ... look up labels in [frameStart, frameEnd], count, pick max ...
end

% Good:
frameLabels = framelbl(rois, frameLength, OverlapLength=overlap, ...
    ConsolidationMethod="mode");
```

### The containment trap

If label A's ROI fully contains label B's ROI inside a frame, a
most-prevalent vote always picks A — label B never wins, even when B is
the more semantically important class (e.g. "voiced speech" inside
"speech"). When labels nest, **use `ConsolidationMethod="priority"` with
an explicit `PriorityList`**, not most-prevalent.

```matlab
% Containment-trap-safe — voiced wins inside speech:
frameLabels = framelbl(rois, 1024, OverlapLength=512, ...
    ConsolidationMethod="priority", ...
    PriorityList=["voiced", "unvoiced", "speech", "silence"]);
```

## Gotchas

- **`OverlapLength` must match `framesig`.** The two functions schedule
  frames independently; only matching parameters keep them aligned.
- **Output shape depends on `ConsolidationMethod`.** With a consolidation
  method set, the output is `1 × numFrames` — index with the same `k` you'd
  use into `framesig`'s column index. With the default `"none"`, the output
  is `fl × numFrames` (sample-within-frame down rows, frames across
  columns); index frame `k` as `out(:, k)`. *Don't* expect a row vector in
  the default case.
- **An ROI shorter than a hop can fall in zero frames** if the hop steps
  over it. Tighten the hop or pre-validate ROI durations.
- **An ROI longer than the signal** is silently clamped — no error.

## See also

- `fn-framesig.md` — the signal-side counterpart.
- `wf-frame-and-label.md` — joint recipe.
- `fn-signalmask-getmask.md` — for per-sample (not per-frame) labels.

----

Copyright 2026 The MathWorks, Inc.

----
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 322kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 322kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 322kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 198kUpdated Claude CodeCodexVerifiedInstall