matlab-extract-signal-features

Signal の特徴量を抽出する

3 つの Signal Processing Toolbox 抽出器オブジェクトを使用して、1D 信号からフレームごとの特徴量を抽出します。適切な抽出器を選び、実際のパラメーターのみで設定し、利用可能な場合は GPU 用のコードパスを追加します。

使用する場合

• ユーザーが 1D 信号を持っており、解析や ML 用にフレームごとの特徴量を求めている場合。
• ユーザーが 3 つの抽出器ドメイン（時間、周波数、時間-周波数）のいずれかに属する特定の特徴量を指定している場合。
• ユーザーが 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 を参照してください。その後、抽出器を設定する前に、分類器／回帰器用の特徴量テーブルに向けて、複数の領域にまたがる候補特徴量を優先順位順に並べ、各特徴量について、観測された信号の特性との関連を説明する1行の理由を記載します。判定結果で選ぶのは主に使う抽出器であり、それだけに限定するわけではありません。特徴量が単一の抽出器に偏ることが、後続の分類器の性能低下を招く最も一般的な原因です。例：「MeanFrequency — 定常的な高調波で、既知の周波数にエネルギーが局在している。」 references/feature-ranking.md を参照してください。
1. ユーザーの要望に基づいて抽出器を選択します。詳しくは、下記の「適切な抽出器の選び方」を参照してください。
2. SampleRate、FrameSize、および FrameRate または FrameOverlapLength のどちらか一方（両方は指定しない）を使って設定します。名前と値のペアとして特徴量フラグを有効にします。
3. （任意） パラメーターが用意されている特徴量／変換について、setExtractorParameters を使って特徴量ごとまたは変換ごとのパラメーターを設定します。このメソッドをサポートしているのは signalFrequencyFeatureExtractor と signalTimeFrequencyFeatureExtractor のみです。第2引数には特徴量名または変換名を指定できます。setExtractorParameters の呼び出しを書く前に、該当するリファレンスファイルを開き、パラメーター名をそのままコピーしてください。 パラメーター名は推測できるとは限りません。正しい情報はリファレンスに記載されています。
4. （任意） references/gpu-patterns.md にあるガードパターンを使って GPU に移行します。
5. 信号に対して extract(sFE, x) を実行します。出力の形状は FeatureFormat（行列またはテーブル）によって異なります。src には signalDatastore／audioDatastore も指定できます。その場合、extract はファイルごとに1つの結果（セル配列）を返し、並列プール上でファイルを処理するための UseParallel=true を受け付けます。多数のファイルを対象に抽出する場合は、必ず使用してください。入力の仕様、抽出器ごとの出力形状、データストア／並列抽出、および複数の抽出器の出力を結合する方法については、references/extract-function.md を参照してください。
6. 出力形状を決定します。デフォルトでは、フレームごとの結果を集約しないでください。フレームごとのテーブルを最終出力として使用できます。ユーザーの後続モデルが信号ごとに固定長のベクトルを1つ必要とする場合（例：fitcecoc、fitcsvm、アンサンブル木）のみ、フレーム間の平均／標準偏差を集約します。モデルがシーケンスを処理する場合（LSTM、1-D CNN、トランスフォーマー）は、フレームごとのテーブルをそのまま使用します。信号の長さが可変で、後続タスクが不明な場合は、集約する前にユーザーに確認してください。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

extract への gpuArray 入力が各抽出器で利用可能になったバージョン： signalTimeFeatureExtractor は R2023a、signalFrequencyFeatureExtractor は R2023a、signalTimeFrequencyFeatureExtractor は R2024b（オブジェクト本体より 1 リリース後）です。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 が Power ではなく RelativeAmplitude を取る点に注意）については、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 以降）： 単一の抽出器で、異なる特徴量を異なる変換に振り分けられます。抽出器を複数用意する必要はありません。特徴量ごとのプロパティ（例：SpectralKurtosis="synchrosqueezedspectrogram"、SpectralEntropy="spectrogram"）を指定して timeFrequencyFeatureTransformOptions を使用してください。詳しい例と有効な変換の表については、references/signal-time-frequency-feature-extractor.md を参照してください。

GPU アクセラレーションによる抽出

ツールボックスに関する注意： GPU パス（gpuArray）と UseParallel=true のデータストアパスは、どちらも Parallel Computing Toolbox が必要です。コア機能の抽出には 必要ありません。canUseGPU() ガードが GPU 分岐をスキップし、UseParallel のデフォルト値が false であるため、このスキルは Parallel Computing Toolbox がなくても 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 の列が含まれる場合があります。後続のコード（ML のトレーニングやプロットなど）では、そのまま受け入れられることがよくあります。gather を呼び出すのは、特定の処理で必要な場合に限ってください（例：.mat への save、CSV への writetable）。

canUseGPU ガードが必要な理由と、無条件に gpuArray を呼び出すべきでない理由については、references/gpu-patterns.md を参照してください。GPU パスが予期せず CPU にフォールバックする場合や、gpuArray でエラーが発生する場合は、matlab-setup-gpu スキルで GPU の利用可能性に関する問題（PCT のライセンスがない、ドライバーが古い、計算モードなど）を診断できます。

抽出後：集約と再現性

ユーザーのワークフローで信号ごとに 1 つの特徴ベクトルが明示的に必要とされない限り、集約しないでください。デフォルトの出力はフレームごとのテーブルです。extract の後に実行する、次の 2 つの任意のパターンがあります。

• フレームごとから信号ごとへの集約 — 下流のモデルでサンプルごとに固定長ベクトルが必要な場合（木アンサンブル、SVM など）に限ります。先に FrameStartTime / FrameEndTime を削除してから、varfun(@mean, ...) / varfun(@std, ...) でまとめます。フレーム系列を直接処理する系列モデル（LSTM、1-D CNN）では集約を省略してください。ベクトル値特徴量のスカラー要約には、抽出時に setScalarizationMethods を使用してください。
• 抽出器とデータカードを保存 — dataCard に SampleRate、FrameSize、FrameOverlapLength、class(sFE)、version("-release") を記録し、save("featureConfig.mat", "sFE", "dataCard") を実行します。新しいデータで抽出を再現するために最低限必要なサイドカーです。

実行例のコードブロックとエッジケース（ベクトル値の列、ラベル列の処理、別のスカラー化方法）については、references/post-extraction-patterns.md を参照してください。

規則（3 つの抽出器すべてに適用）

• 必ず 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 と組み合わせて使え、コード生成パスもあります。
FrameSize=N ではなく FrameLength=N を指定する	3 つすべての抽出器で、プロパティは FrameSize です。
FrameRate と FrameOverlapLength の両方を設定する	どちらか一方を選んでください。
canUseGPU() ガードなしで gpuArray(x) を呼び出す	CPU のみのマシンでは重大なエラーになります。if canUseGPU(); x = gpuArray(x); end で囲んでください。

抽出器固有の落とし穴（例：時間抽出器での Skewness=true、EMD 以外の変換に対する MeanEnvelopeEnergy、特徴量名から推測した RelativeAmplitude ではなく PowerBandwidth パラメーターを指定すること）については、各抽出器のリファレンスを参照してください。

参考資料

• references/preliminary-analysis.md — 信号処理のみで行うスペクトル定常性チェック（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 — 3 つの *ScalarFeatureOptions オブジェクトと setScalarizationMethods API について説明します。ベクトル値特徴量にスカラー要約列を追加する場合にお読みください。
• references/gpu-patterns.md — canUseGPU ガードパターンとその理由について説明します。ユーザーが GPU に言及した場合にお読みください。

---

Copyright 2026 The MathWorks, Inc.

---