カスタムラベル付け関数

信号ラベラーを使用すると、自動ラベル付けタスクを実行できます。[ピークラベラー] 以外にも、[ラベル] タブの [値の自動処理] ギャラリーには、自動的に信号にラベル付けするために使用できる関数が含まれています。

Automate Value gallery

カスタムラベル付け関数の作成

すべてのカスタム自動ラベル付け関数の最初の行は、次の形式の定義ステートメントで構成されています。

function [labelVals,labelLocs] = fx(x,t,parentLabelVal,parentLabelLoc,varargin)

定義ステートメントには、関数名と、必須およびオプションの引数のセットが含まれています。

最初の入力引数 x は、入力信号です。関数を記述する場合、x は各列にチャネルに対応するデータが含まれる行列であると想定します。チャネルの長さが異なる場合、x は列ベクトルの cell 配列であると想定します。
2 番目の入力引数 t は、時間値を格納します。関数を記述する場合、t は各列にチャネルに対応する時間情報が含まれる行列であると想定します。チャネルの長さが異なる場合、t は列ベクトルの cell 配列であると想定します。
メモ
- 単一チャネルメンバーの場合、カスタム自動ラベル付け関数は、データと時間値を倍精度のベクトルとして取得します。
- マルチチャネルメンバーの場合、カスタム自動ラベル付け関数は、データと時間値を行列または cell 配列として取得します。
- カスタム自動ラベル付け関数は、メンバーのすべてのチャネルを入力として取得しますが、すべてを処理する必要はありません。関数が処理するチャネルを選択できます。
3 番目の入力引数 parentLabelVal は、出力サブラベルに関連付けられた親ラベル値であり、数値、logical、または string スカラーが含まれます。この引数は、サブラベルのラベル付けを自動化する関数にのみ渡されます。関数が親ラベル用の場合は、parentLabelVal は空であると想定します。
4 番目の入力引数 parentLabelLoc には、以下が含まれます。
- 親ラベルが属性の場合は、空のベクトル
- 親ラベルが関心領域 (ROI) の場合は、ROI 範囲の 2 要素の数値行ベクトル
- 親ラベルが点の場合は、点の位置を表す数値スカラー
この引数は、サブラベルのラベル付けを自動化する関数にのみ渡されます。関数が親ラベル用の場合は、parentLabelLoc は空であると想定します。
メモ
- 親ラベルの場合、選択された各メンバーに対して自動ラベル付け関数が実行されます。
- サブラベルの場合、選択されたそれぞれのメンバーについて、一度に 1 つの親ラベルのインスタンスに対して、自動ラベル付け関数が実行されます。
追加の入力引数を指定するには、varargin を使用します。追加の入力引数がない場合は、varargin を省略できます。追加の引数は、[自動ラベル付け] ボタンをクリックすると表示されるダイアログボックスに順序付きのコンマ区切りリストとして入力します。
最初の出力引数 labelVals には、ラベル値が含まれます。labelVals は以下でなければなりません。
- 出力ラベルが属性の場合、数値、logical、または string スカラー
- 出力ラベルが ROI または点の場合、数値、logical、または string 値を持つ列ベクトル
2 番目の出力引数 labelLocs には、ラベルの位置が含まれます。labelLocs は以下でなければなりません。
- 出力ラベルが属性の場合は、空のベクトル
- 出力ラベルが ROI の場合は、ROI 範囲の 2 列の行列
- 出力ラベルが点の場合は、点の位置の列ベクトル
アルゴリズムを実装するために、MATLAB^® またはシステムにインストールされているいずれかのツールボックスの関数を使用できます。

詳細については、カスタム関数を使用した信号のラベル付けの自動化およびオーディオ信号内の発声された単語のラベル付けを参照してください。

例:平均 RMS 値

この関数は信号の平均 RMS 値を計算し、数値属性としてこの値を使用して信号にラベル付けします。メンバーに複数のチャネルがある場合、この関数は各チャネルの RMS 値を計算し、値を平均します。チャネルは異なる長さをもつことができます。

function [labelVals,labelLocs] = meanRMS(x,t,parentLabelVal,parentLabelLoc,varargin)
% Label signal with its mean RMS value as attribute

if iscell(x)
    labelVals = mean(cellfun(@rms,x))
else
    labelVals = mean(rms(x));
end
labelLocs = [];

end

例:ゼロクロッシング

この関数は、信号のゼロクロッシングを検出し、立ち上がり遷移の場合は "rising"、立ち下がり遷移の場合は "falling" としてラベル付けします。

function [labelVals,labelLocs] = transitions(x,t,parentLabelVal,parentLabelLoc,varargin)
% Label zero crossings as "rising" or "falling"

nchan = size(x,2);
tt = t(:,1);

labelVals = cell(nchan,1);
labelLocs = cell(nchan,1);

for kj = 1:nchan

    [rate,count,indices] = zerocrossrate(x,TransitionEdge="rising");
    rloc = tt(indices == 1);
    rval = repmat("rising",length(rloc),1);
    
    [rate,count,indices] = zerocrossrate(x,TransitionEdge="falling");
    floc = tt(indices == 1);
    fval = repmat("falling",length(floc),1);
    
    labelLocs{kj} = [rloc;floc];
    labelVals{kj} = [rval;fval];

end

labelVals = cat(1,labelVals{:});
labelLocs = cell2mat(labelLocs);

end

例:マルチチャネルラベル付け

この論理関数は、次のようなマルチチャネル信号の領域を true としてラベル付けします。

最初のチャネルの振幅が負である。
3 番目のチャネルの振幅が、ユーザー指定の値 mx よりも大きい。mx を指定しない場合は、既定値の 0.1 が使用されます。

function [labelVals,labelLocs] = greaterThan(x,t,parentLabelVal,parentLabelLoc,varargin)
% Label regions with negative first channel and third channel larger than a given value

if nargin<5
    mx = 0.1;
else
    mx = varargin{1};
end

xr = x(:,1);
xx = x(:,3);
tt = t(:,1);

ss = signalMask(xr < 0 & xx >= mx);
x = roimask(ss);

labelLocs = tt(x.ROILimits);
labelVals = logical(double(x.Value));

end

例:外部 API を使用した発声された単語の抽出

この関数は、IBM® Watson Speech to Text API と Audio Toolbox™ speech2text 拡張機能を使用して、オーディオファイルから発声された単語を抽出します。

function [labelVals,labelLocs] = stt(x,t,parentLabelVal,parentLabelLoc,varargin)

aspeechObjectIBM = speechClient("IBM",timestamps=true);

fs = 1/(t(2)-t(1));

tixt = speech2text(aspeechObjectIBM,x,fs);

unifiedTable = vertcat(tixt.TimeStamps{:});
numLabels = numel(unifiedTable,1);
labelVals = strings(numLabels,1);
labelLocs = zeros(numLabels,2);

for idx = 1:numLabels
    labelVals(idx) = unifiedTable{idx}{1};
    labelLocs(idx,1) = unifiedTable{idx}{2};
    labelLocs(idx,2) = unifiedTable{idx}{3};
end

end

ギャラリーへのカスタムラベル付け関数の追加

カスタム自動ラベル付け関数を追加するには、[値の自動処理] ギャラリーの隣にある矢印をクリックして、[カスタム関数の追加] を選択します。ダイアログボックスで、以下のフィールドを指定します。

名前 — 追加する関数の名前を指定します。
説明 — 関数の機能の簡単な説明を追加し、オプションの入力引数について説明します。
ラベルタイプ — 関数が生成するラベルのタイプを指定します。[属性] (既定の設定)、[ROI]、または [点] を選択します。
メモ
指定した [ラベルタイプ] に基づいて、信号ラベラーが [値の自動処理] ギャラリーの適切なカテゴリに関数を配置します。ラベル定義を選択すると、ギャラリーでは、その定義タイプで使用できる関数のみが有効になります。

関数を書き込み済みでその関数が現在のフォルダーまたは MATLAB パスにある場合、[信号ラベラー] はその関数をギャラリーに組み込みます。関数をまだ書き込んでいない場合、[信号ラベラー] はエディターで空白のテンプレートを開きます。

ギャラリーでのカスタムラベル付け関数の管理

必要に応じて、[値の自動処理] ギャラリーの [カスタム関数の管理] オプションを使用して、関数の編集、関数の説明の編集、または関数の削除ができます。

メモ

[カスタム関数の管理] オプションを使用すると、[値の自動処理] ギャラリーに表示される関数の説明のみが変更されます。関数を含むファイル内の説明を変更する場合は、ファイルを編集しなければなりません。