matlab-extract-signal-features

提取信号特征

使用 Signal Processing Toolbox 的 3 个特征提取器对象，按帧提取 1D 信号特征。选择合适的提取器，仅使用真实参数进行配置，并在可用时添加 GPU 代码路径。

适用场景

• 用户有一个 1D 信号，并希望提取逐帧特征以用于分析或机器学习。
• 用户提到了三个提取器领域（时域、频域、时频域）中的特定特征。
• 用户需要将特征表或特征矩阵输入 fitcecoc、fitcnet 或任何分类器／回归器。
• 用户需要对加窗信号按帧进行统计。

不适用场景

• 滤波器设计或信号预处理 — 不在范围内。特征提取前的滤波属于独立事项。
• 音频专用特征（MFCC、梅尔频谱图、音高、色度、伽马音调）。Audio Toolbox 的 audioFeatureExtractor 可提取这些特征，但不在此处的范围内。
• 批处理／数据集编排 — signalDatastore、labeledSignalSet、tall 数组。逐文件提取在范围内，但围绕它构建的管线不在范围内。
• 2D、图像或多变量特征 — 根据信号类型边界，不在范围内。

工作流

0. （推荐）快速进行初步分析。 仅使用 Signal Processing Toolbox，在有代表性的子集上检查频谱平稳性——频率成分是否随时间漂移？——查看 pspectrum(x, fs, "spectrogram")，并计算逐帧 MeanFrequency 漂移比（无需 Econometrics Toolbox；adftest/kpsstest 仅作为可选补充）。根据判断选择主要提取器：非平稳信号倾向于使用 signalTimeFrequencyFeatureExtractor；频谱平稳的信号则倾向于使用频率提取器。请参阅 references/preliminary-analysis.md。然后，在配置提取器之前，先列出一个排序后的候选特征清单，其中应涵盖多个领域，以用于分类器／回归器特征表，并为每个特征写一句理由，将其与观察到的信号特征联系起来。判断结果决定主要提取器，而非唯一提取器——特征集只依赖单个提取器，是下游分类器效果不佳的最常见原因。示例：“MeanFrequency——平稳的谐波，能量集中在已知频率上。” 请参阅 references/feature-ranking.md。
1. 选择提取器，依据用户需求决定。请参阅下文“选择合适的提取器”。
2. 使用 SampleRate、FrameSize，以及 FrameRate 或 FrameOverlapLength（不可同时使用二者）进行配置。以名称-值对形式启用特征标志。
3. （可选）通过 setExtractorParameters 设置每项特征或每种变换的参数，用于支持参数设置的特征／变换。只有 signalFrequencyFeatureExtractor 和 signalTimeFrequencyFeatureExtractor 支持此方法。第二个参数可以是特征名称，也可以是变换名称。编写任何 setExtractorParameters 调用之前，请先打开对应的参考文件，并逐字复制参数名称。 参数名称并非凭直觉就能猜对。参考文件是权威依据。
4. （可选）使用 references/gpu-patterns.md 中的保护模式切换到 GPU。
5. 对信号运行 extract(sFE, x)。输出形状取决于 FeatureFormat（矩阵或表格）。src 也可以是 signalDatastore／audioDatastore，此时 extract 会为每个文件返回一个结果（元胞数组），并接受 UseParallel=true，以便在并行池上处理文件——对大量文件进行提取时应使用此选项。有关输入约定、各提取器的输出形状、数据存储／并行提取，以及如何合并不同提取器的输出，请参阅 references/extract-function.md。
6. 确定输出形状。 默认情况下，请勿汇总逐帧结果。逐帧表格本身就是有效的最终输出。只有在用户的下游模型要求每个信号对应一个定长向量时（例如 fitcecoc、fitcsvm、树集成模型），才按帧计算均值／标准差进行汇总。如果模型接受序列（LSTM、1-D CNN、transformer），则保持逐帧表格原样。如果用户的信号长度不定，且下游任务不明确，应先询问，而非擅自假定需要汇总。请参阅 references/post-extraction-patterns.md。

以下情况请暂停，并查看对应的各提取器参考文件：

• 在 signalTimeFrequencyFeatureExtractor 上启用任何特征——不同的 Transform 支持的特征子集各不相同。
• 调用 setExtractorParameters——不同特征和变换的参数名称各不相同。
• 使用本文件中的模式尚未展示的任何特征标志、参数或 Transform 值。如果各提取器参考文件中没有该项，则该对象不支持它。

选择合适的提取器

用户需求	使用
时域特征（振幅、能量、形状因子）	signalTimeFeatureExtractor
频域特征（频谱位置、功率、带宽、PSD）	signalFrequencyFeatureExtractor
时频特征（频谱形状、瞬时特征、脊线、小波、基于 EMD 的特征）	signalTimeFrequencyFeatureExtractor
以上多种特征	使用多个提取器；拼接生成的表格

对于时频提取器，Transform 属性决定哪些特征有效。请参见 references/signal-time-frequency-feature-extractor.md 中的兼容性矩阵。

主要函数

函数	用途	工具箱	起始版本
signalTimeFeatureExtractor	时域特征提取器对象	Signal Processing Toolbox	R2021a
signalFrequencyFeatureExtractor	频域特征提取器对象	Signal Processing Toolbox	R2021b
signalTimeFrequencyFeatureExtractor	时频特征提取器对象	Signal Processing Toolbox	R2024a
extract	对信号运行已配置的提取器	Signal Processing Toolbox	R2021a
getExtractorParameters / setExtractorParameters	读取/写入每个特征或每种变换的参数（仅限频域和时频域）	Signal Processing Toolbox	R2021b
timeFrequencyFeatureTransformOptions	为 signalTimeFrequencyFeatureExtractor 创建变换选项对象（取代字符串 Transform=）	Signal Processing Toolbox	R2026a
generateMATLABFunction	从提取器生成兼容代码生成的 MATLAB 函数	Signal Processing Toolbox	R2021a
canUseGPU、gather	GPU 可用性检查和数据传输（MATLAB 核心功能，无需工具箱）	MATLAB	R2020b
gpuArray	将数组移至 GPU 内存	Parallel Computing Toolbox	R2012a

将 gpuArray 输入 extract 的支持版本：signalTimeFeatureExtractor 从 R2023a 起支持，signalFrequencyFeatureExtractor 从 R2023a 起支持，signalTimeFrequencyFeatureExtractor 从 R2024b 起支持（比对象本身晚一个版本）。需要 Parallel Computing Toolbox。有关各变换的限制，请参见 references/gpu-patterns.md。

generateMATLABFunction 适用于代码生成工作流。相关时请提及；完整的代码生成指南不在本技能的范围内。

模式

按帧提取时域特征

function featureTable = extractTimeFeaturesExample(x, fs)
%extractTimeFeaturesExample Per-frame time-domain features as a table.
    arguments
        x  (:, 1) double {mustBeFinite}
        fs (1, 1) double {mustBePositive}
    end

    sFE = signalTimeFeatureExtractor( ...
        SampleRate=fs, ...
        FrameSize=round(0.1 * fs), ...
        FrameOverlapLength=round(0.05 * fs), ...
        RMS=true, ...
        CrestFactor=true, ...
        PeakValue=true, ...
        FeatureFormat="table");

    featureTable = extract(sFE, x);
end

有关有效的时域特征标志，请参见 references/signal-time-feature-extractor.md。

使用逐特征参数提取频域特征

function featureTable = extractBandPowerExample(x, fs)
%extractBandPowerExample Band power and occupied bandwidth per frame.
    arguments
        x  (:, 1) double {mustBeFinite}
        fs (1, 1) double {mustBePositive}
    end

    sFE = signalFrequencyFeatureExtractor( ...
        SampleRate=fs, ...
        FrameSize=round(0.1 * fs), ...
        FrameOverlapLength=round(0.05 * fs), ...
        BandPower=true, ...
        OccupiedBandwidth=true, ...
        FeatureFormat="table");

    setExtractorParameters(sFE, "OccupiedBandwidth", Percentage=95);

    featureTable = extract(sFE, x);
end

有关逐特征参数表（包括 PowerBandwidth 使用 RelativeAmplitude 而非 Power 的注意事项），请参见 references/signal-frequency-feature-extractor.md。

提取时频特征（频谱图变换）

function featureTable = extractTFFeaturesExample(x, fs)
%extractTFFeaturesExample Spectral entropy and instantaneous frequency per frame.
    arguments
        x  (:, 1) double {mustBeFinite}
        fs (1, 1) double {mustBePositive}
    end

    % R2026a+ (preferred): use timeFrequencyFeatureTransformOptions.
    % Constructor is name-value only, keyed by FEATURE name -> transform.
    % There is no positional-string form: timeFrequencyFeatureTransformOptions("spectrogram") errors.
    tfOpts = timeFrequencyFeatureTransformOptions( ...
        SpectralEntropy="spectrogram", ...
        InstantaneousFrequency="spectrogram");
    sFE = signalTimeFrequencyFeatureExtractor( ...
        Transform=tfOpts, ...
        SampleRate=fs, ...
        FrameSize=256, ...
        FrameOverlapLength=128, ...
        SpectralEntropy=true, ...
        InstantaneousFrequency=true, ...
        FeatureFormat="table");

    % R2024a–R2025b: use string directly (deprecated from R2026a)
    % sFE = signalTimeFrequencyFeatureExtractor( ...
    %     Transform="spectrogram", ...
    %     SampleRate=fs, ...
    %     FrameSize=256, ...
    %     FrameOverlapLength=128, ...
    %     SpectralEntropy=true, ...
    %     InstantaneousFrequency=true, ...
    %     FeatureFormat="table");

    setExtractorParameters(sFE, "spectrogram", Leakage=0.9, OverlapPercent=85);

    featureTable = extract(sFE, x);
end

每种 Transform 支持的特征子集不同，逐特征参数也取决于 (transform, feature)。启用特征或调用 setExtractorParameters 前，务必先查看 references/signal-time-frequency-feature-extractor.md。

**多变换路由（R2026a+）：**单个提取器可以将不同特征路由到不同变换，无需使用多个提取器。使用 timeFrequencyFeatureTransformOptions 设置逐特征属性（例如，SpectralKurtosis="synchrosqueezedspectrogram"、SpectralEntropy="spectrogram"）。请参见 references/signal-time-frequency-feature-extractor.md 中的完整示例和有效变换表。

GPU 加速提取

工具箱说明： GPU 路径（gpuArray）和 UseParallel=true 数据存储路径都需要 Parallel Computing Toolbox。核心特征提取并不需要它——由于 canUseGPU() 守卫会跳过 GPU 分支，且 UseParallel 默认为 false，因此此技能无需该工具箱也能完全在 CPU 上运行。仅当已安装 Parallel Computing Toolbox 时才启用这些路径。

function featureTable = extractWithGPU(x, fs)
%extractWithGPU Run feature extraction on GPU when available, CPU otherwise.
    arguments
        x  (:, 1) double {mustBeFinite}
        fs (1, 1) double {mustBePositive}
    end

    sFE = signalTimeFeatureExtractor( ...
        SampleRate=fs, ...
        FrameSize=round(0.1 * fs), ...
        FrameOverlapLength=round(0.05 * fs), ...
        RMS=true, ...
        StandardDeviation=true, ...
        FeatureFormat="table");

    if canUseGPU()
        x = gpuArray(x);
    end
    featureTable = extract(sFE, x);
end

特征表可能包含 gpuArray 列。下游代码（机器学习训练、绘图）通常可以直接接受这些列。只有特定使用方需要时才调用 gather（例如，使用 save 保存为 .mat 文件，或使用 writetable 写入 CSV）。

请参阅 references/gpu-patterns.md，了解 canUseGPU 守卫的设计原因，以及为什么无条件调用 gpuArray 是错误的。如果 GPU 路径意外回退到 CPU，或 gpuArray 报错，matlab-setup-gpu 技能可诊断 GPU 可用性问题（PCT 未获许可、驱动程序过时、计算模式）。

提取后：聚合与可复现性

除非用户的工作流明确要求每个信号对应一个特征向量，否则不要进行聚合。默认输出为逐帧表。extract 之后有两种可选模式：

• 逐帧 → 逐信号聚合 — 仅当下游模型要求每个样本对应定长向量时使用（树集成、SVM 等）。先删除 FrameStartTime / FrameEndTime，再使用 varfun(@mean, ...) / varfun(@std, ...) 进行汇总。对于直接处理帧序列的序列模型（LSTM、1-D CNN），跳过聚合。若要对向量值特征进行标量汇总，请改为在提取时使用 setScalarizationMethods。
• 保存提取器和数据卡 — 使用 save("featureConfig.mat", "sFE", "dataCard")，其中 dataCard 记录 SampleRate、FrameSize、FrameOverlapLength、class(sFE) 和 version("-release")。这是在新数据上复现提取所需的最简配套文件。

请参阅 references/post-extraction-patterns.md，了解示例代码块和边界情况（向量值列、标签列处理、替代的标量化方式）。

约定（适用于所有三个提取器）

• 始终设置 SampleRate。 若省略 SampleRate，频率相关特征会将信号视为 fs = 1。
• 选择 FrameRate 或 FrameOverlapLength，不要同时设置。 两者只是用不同方式控制同一属性。同时设置会报错。
• FrameOverlapLength 必须小于 FrameSize。
• 以样本数而非秒数设置 FrameSize 和 FrameOverlapLength。 换算方式：FrameSize = round(durationSeconds * fs)。
• 当提取器生成标量和向量特征的混合结果时，优先使用 FeatureFormat="table"。
• **FrameStartTime / FrameEndTime 是从 1 开始计数的样本位置，**不是秒。换算方式：tSec = (T.FrameStartTime - 1) / fs。训练分类器前应删除这些列。
• 向量值特征列在逐帧长度固定时为数值矩阵，长度不固定时为单元格。 索引前请使用 iscell(T.(colName)) 检查。
• 不要猜测特征名称或参数。 请阅读对应提取器的参考文档。参考文档中没有的内容，在对象上也不存在。

常见的跨场景问题

尝试的做法	修正方法
对加窗信号手动编写逐帧统计代码（例如，对缓冲信号循环计算 RMS / 峰值因数）	使用提取器对象——它可与 extract 组合使用，并支持代码生成路径。
使用 FrameLength=N 而不是 FrameSize=N	三个提取器的属性名称都是 FrameSize。
同时设置 FrameRate 和 FrameOverlapLength	二选一。
不使用 canUseGPU() 守卫就调用 gpuArray(x)	仅 CPU 的计算机上会直接报错。请将其包装在 if canUseGPU(); x = gpuArray(x); end 中。

有关提取器特有的问题（例如，在时域提取器上设置 Skewness=true、在非 EMD 变换上使用 MeanEnvelopeEnergy，以及 PowerBandwidth 参数实际为 RelativeAmplitude，而不是根据特征名称猜测的值），请参阅各提取器的参考文档。

参考资料

• references/preliminary-analysis.md — 仅使用 Signal Processing 进行谱平稳性检查（pspectrum 谱图 + 每帧 MeanFrequency 漂移比）、可选的 Econometrics adftest/kpsstest 补充检查，以及结论→提取器的决策规则。信号特征不明确时，在选择提取器前阅读。
• references/feature-ranking.md — 先验候选特征列表模式，以及信号特征→特征映射。用户要求提供起始特征集或排序列表时阅读。
• references/extract-function.md — extract 的输入/输出约定、各提取器的输出特征、多提取器行对齐，以及常见错误模式。调试形状或对齐问题时阅读。
• references/signal-time-feature-extractor.md — 时间提取器的完整属性和特征标志说明。核实时间特征名称或属性时阅读。
• references/signal-frequency-feature-extractor.md — 完整属性说明，以及各特征的参数表（OccupiedBandwidth、PowerBandwidth、WelchPSD、峰值参数）。配置频率特征时阅读。
• references/signal-time-frequency-feature-extractor.md — 变换×特征兼容性矩阵及各变换的参数表。在时频提取器上启用任何特征前，先阅读此文档。
• references/scalarization-options.md — 三种 *ScalarFeatureOptions 对象和 setScalarizationMethods API。为向量值特征添加标量汇总列时阅读。
• references/gpu-patterns.md — canUseGPU 防护模式及其原理。用户提到 GPU 时阅读。

---

版权所有 2026 The MathWorks, Inc.

---