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/wf-align-channels.md

View on GitHub
# Workflow: align multi-rate / offset channels to a shared time base

> Functions used: `synchronize`, `retime`, `resample`, `finddelay`, `alignsignals`, `xcorr`

Several signals from different sources — different sample rates, different
start times, or an unknown lag between them — become one aligned, uniformly
sampled table.

> **Off-ramp.** If a single channel just has non-uniform / jittery timestamps
> (no second channel to align against), that is regularize, not align — see
> wf-uniform-rate.md.

## When to use this

Reach here when the inputs are **two or more** channels that need a common
time base:
- Different rates (100 Hz accelerometer + 50 Hz pressure).
- Different start times or offsets.
- An unknown lag to estimate and remove first.

The dominant mistake is **hand-orchestrating** the merge: retime channel B,
estimate the lag, shift B's row times, retime again, then build a timetable
by hand to concatenate.
That produces the correct result but in five steps.
`synchronize` does the bring-to-common-grid step in one call.

## Recipe

### Step 1 — Get each channel into a timetable

If the channels are numeric vectors with sample rates, wrap them:

```matlab
A = timetable(secondsA', chA, 'VariableNames', "accel");   % or SampleRate= form
B = timetable(secondsB', chB, 'VariableNames', "press");
```

Once they are timetables, the merge is one function — the rate difference is
handled by the adjust method, not by manual resampling per channel.

### Step 2 (only if there is an unknown lag) — estimate and remove it

If the channels are the *same* physical signal seen through different sensors
with an unknown delay, find the lag first.
Both `finddelay` and a normalized `xcorr` peak give it; they should agree.

```matlab
d = finddelay(a, b);              % integer-sample lag of b relative to a
b_aligned = alignsignals(a, b);   % or shift b's row times by d/fs
```

When you report the lag to the user, lead with the physical time in seconds — that is unambiguous across channels. `finddelay`/`xcorr` measure the lag in samples of the grid the two signals were compared on, so a raw sample count only means something once you say which rate it is at. Report the delay as seconds (`d/fsCommon`, where `fsCommon` is the shared/aligned rate), and if you also give a sample count, state the grid it refers to (e.g. "8 ms = 8 samples at the 1 kHz aligned rate"). Do not report a bare integer sample count for mismatched-rate channels — the same delay is a different count at each rate.

For sub-sample precision, refine the `xcorr` peak parabolically.
Skip this whole step when the channels are *different* signals sharing a
clock — there is no lag to estimate, only a rate/offset difference, which
step 3 handles directly.

### Step 3 — Merge onto a shared grid with `synchronize`

This is the one-shot primitive. Pick the common time basis and the adjust
method (full contract in fn-synchronize.md):

```matlab
% Put everything on A's row times, interpolate B linearly:
TT = synchronize(A, B, 'first', 'linear');

% Or a clean uniform output rate, regardless of either input's grid:
TT = synchronize(A, B, 'regular', 'linear', 'SampleRate', 100);

% Or keep only the overlapping span (drop non-overlapping tails):
TT = synchronize(A, B, 'commonrange', 'linear');
```

Choose the basis by intent:
- `'first'` / `'last'` — anchor to one channel's existing grid.
- `'regular'` + `SampleRate` — impose a clean uniform rate.
- `'commonrange'` — keep only where all channels have data.
- `'union'` (default) — keep every sample and NaN-fill the rest (see step 4).

**Anti-pattern.** Do not `retime` each channel separately and then build a
timetable by hand to stitch them. `synchronize` is exactly that operation,
done once, with the grid choice explicit.

```matlab
% Bad — hand-orchestrated merge:
Br = retime(B, A.Time, 'linear');
TT = timetable(A.Time, A.accel, Br.press);   % manual concat

% Good — one call:
TT = synchronize(A, B, 'first', 'linear');
```

### Step 4 — Handle the NaNs that alignment creates

At times where one channel has no sample and you used the default
(`'fillwithmissing'`, i.e. `synchronize(A,B)` with no method), or where
`'union'` introduced rows outside a channel's span, the output has `NaN`s.
Align typically **precedes fill**: decide whether those gaps are
interpolated, held, or left missing.
See wf-repair-missing.md for the fill step.

If you interpolated in step 3 (`'linear'` etc.), watch the endpoints:
`'linear'` extrapolates by default, so a channel that starts late gets
invented values before its first real sample. Pass `EndValues=NaN` to refuse
extrapolation, then fill deliberately.

Two mistakes are common at exactly this step, both on the `NaN`s alignment
just created:

- **Dropping the NaN rows** (`tt = tt(all(isfinite(tt{:,:}),2), :)`) to make
  the table finite. That silently truncates every channel to the *overlap*
  span and desynchronizes rows you meant to keep - it is not a fill, it is a
  crop. If you genuinely want only the overlap, ask `synchronize` for it up
  front with `'commonrange'`; do not post-hoc delete rows.
- **Treating the endpoint `NaN`s as ordinary interior gaps.** A late-starting
  channel's leading `NaN`s (and an early-ending channel's trailing `NaN`s) are
  *edge* gaps with data on one side only - the endpoint case in
  wf-repair-missing.md. Route them there; on an oscillatory channel the fill is
  `fillgaps`, not `fillmissing(..., EndValues=...)`.

## Aliasing guardrail — `resample` before `synchronize` when downsampling

`synchronize`/`retime` interpolation methods do **not** antialias, and they
alias **silently**. If a channel is being brought onto a grid **coarser** than
its own content bandwidth (any real downsampling), plain interpolation folds
high-frequency energy back into the band with no warning.

Rule: when the shared grid is coarser than a channel's native rate, `resample`
that channel to the target rate **first** (antialiased, `resample` applies the
FIR anti-alias filter), *then* `synchronize` onto the grid. Reserve bare
`synchronize`-linear for channels whose content is slow relative to the shared
rate — i.e. you are not reducing real bandwidth. See fn-resample.md and
wf-uniform-rate.md (the single-channel rate-change workflow).

## See also

- fn-synchronize.md — the merge primitive, basis and method contract.
- fn-retime.md — single-channel rate change (the piece `synchronize` generalizes).
- fn-resample.md — antialiased rate conversion.
- wf-repair-missing.md — fill the NaNs alignment creates.
- wf-uniform-rate.md — single-channel onto a uniform rate (regularize jitter or plain rate-change).

----

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