Extract Signal Features

Extract Signal Features

Per-frame feature extraction for 1D signals using the three Signal Processing Toolbox extractor objects. Picks the right extractor, configures it with real parameters only, and adds a GPU code path when one is available.

When to Use

• The user has a 1D signal and wants per-frame features for analysis or ML.
• The user names specific features from any of the three extractor domains (time, frequency, time-frequency).
• The user asks for a feature table or feature matrix to feed fitcecoc, fitcnet, or any classifier / regressor.
• The user asks for per-frame statistics over a windowed signal.

When NOT to Use

• Filter design or signal preprocessing — out of scope. Filtering before feature extraction is a separate concern.
• Audio-specific features (MFCC, mel-spectrogram, pitch, chroma, gammatone). Audio Toolbox's audioFeatureExtractor covers those — out of scope here.
• Batch / dataset orchestration — signalDatastore, labeledSignalSet, tall arrays. The per-file extraction is in scope; building the pipeline around it is not.
• 2D, image, or multivariate features — out of scope by signal-type boundary.

Workflow

0. (Recommended) Run a quick preliminary analysis. Check spectral stationarity — does the frequency content drift over time? — on a representative subset using Signal Processing Toolbox alone: a pspectrum(x, fs, "spectrogram") look plus a per-frame MeanFrequency drift ratio (no Econometrics Toolbox needed; adftest/kpsstest are an optional supplement only). Use the verdict to pick the primary extractor — non-stationary signals favour signalTimeFrequencyFeatureExtractor; spectrally stationary signals lean on the frequency extractor. See references/preliminary-analysis.md. Then write down a ranked candidate feature list, spanning more than one domain for a classifier/regressor feature table, with one-line justifications tying each feature to an observed signal characteristic, before configuring the extractors. The verdict picks the primary extractor, not the only one — a set that collapses onto a single extractor is the most common cause of a weak downstream classifier. Example: "MeanFrequency — stationary harmonic, energy localized at known frequencies." See references/feature-ranking.md.
1. Pick the extractor based on what the user wants. See "Choosing the right extractor" below.
2. Configure with SampleRate, FrameSize, and either FrameRate or FrameOverlapLength (not both). Enable feature flags as name-value pairs.
3. (Optional) Set per-feature or per-transform parameters via setExtractorParameters for features/transforms that have them. Only signalFrequencyFeatureExtractor and signalTimeFrequencyFeatureExtractor support this method. The second argument can be a feature name OR a transform name. Before writing any setExtractorParameters call, open the matching reference file and copy the parameter name verbatim. Parameter names are not what you'd guess. The references are the source of truth.
4. (Optional) Move to GPU using the guard pattern in references/gpu-patterns.md.
5. Run extract(sFE, x) on the signal. Output shape depends on FeatureFormat (matrix or table). src may also be a signalDatastore / audioDatastore, in which case extract returns one result per file (a cell array) and accepts UseParallel=true to process files on a parallel pool — use it whenever extracting over many files. For the input contract, the per-extractor output shape, datastore/parallel extraction, and how to combine outputs across extractors, see references/extract-function.md.
6. Decide output shape. Do NOT aggregate per-frame results by default. The per-frame table is a valid final output. Aggregate (mean/std across frames) only if the user's downstream model requires one fixed-length vector per signal (e.g., fitcecoc, fitcsvm, tree ensembles). If the model consumes sequences (LSTM, 1-D CNN, transformer), keep the per-frame table as-is. If the user has variable-length signals and the downstream task is unclear, ask rather than assuming aggregation. See references/post-extraction-patterns.md.

Stop and check the matching per-extractor reference before:

• Enabling any feature on signalTimeFrequencyFeatureExtractor — each Transform supports a different subset.
• Calling setExtractorParameters — parameter names differ per feature and per transform.
• Using any feature flag, parameter, or Transform value not already shown in this file's patterns. If it isn't in the per-extractor reference, it doesn't exist on the object.

Choosing the right extractor