Main Content

このページの翻訳は最新ではありません。ここをクリックして、英語の最新版を参照してください。

signalDatastore

信号コレクションのデータストア

説明

signalDatastore オブジェクトを使用して、インメモリのデータまたは信号ファイルのコレクションを管理します。個々のファイルはメモリに収まっても、コレクション全体が収まるとは限らない場合に使用します。

作成

説明

sds = signalDatastore(data) は、data に含まれるインメモリ入力信号をもつ信号データストアを作成します。

sds = signalDatastore(location) は、location にある MAT ファイルのコレクションに基づいて信号データストアを作成します。

sds = signalDatastore(___,Name,Value) は、1 つ以上の名前と値のペアの引数を使用して追加プロパティを指定します。

入力引数

すべて展開する

インメモリ入力データ。ベクトル、行列、timetable または cell 配列として指定します。data の各要素は、read の呼び出しごとにデータストアによって出力されたメンバーです。

例: {randn(100,1); randn(120,3); randn(135,2); randn(100,1)}

データストアに含まれるファイルまたはフォルダー。パスまたは DsFileSet オブジェクトとして指定します。

  • パス — パスを文字ベクトル、文字ベクトルの cell 配列、string スカラーまたは string 配列として指定します。ローカルまたはリモートのファイルまたはフォルダーの位置を含みます。

    • ローカルのファイルまたはフォルダー — location をファイルまたはフォルダーへのローカル パスとして指定します。ファイルが現在のフォルダーに存在しない場合、ローカル パスは絶対パスまたは相対パスを指定しなければなりません。指定されたフォルダーのサブフォルダー内のファイルは、自動的にはデータストアに含まれません。ローカル パスを指定する際、ワイルドカード文字 (*) を使用できます。この文字は、すべての一致するファイル、または一致するフォルダー内のすべてのファイルがデータストアに含まれることを指定します。

    • リモートのファイルまたはフォルダー — ファイルまたはフォルダーの絶対パスとなる locationhdfs:///path_to_file 形式のユニフォーム リソース ロケータ (URL) として指定します。詳細については、リモート データの操作を参照してください。

  • DsFileSet オブジェクト — locationDsFileSet オブジェクトとして指定することもできます。詳細については、matlab.io.datastore.DsFileSet を参照してください。

location がフォルダーを表す場合、データストアにはサポートされているファイル形式のみが含まれ、他の形式は無視されます。データストアに含めるファイル拡張子のカスタム リストを指定するには、FileExtensions プロパティを参照してください。

例: 'whale.mat'

例: '../dir/data/signal.mat'

データ型: char | string | cell

名前と値のペアの引数

オプションの引数 Name,Value のコンマ区切りペアを指定します。Name は引数名で、Value は対応する値です。Name は引用符で囲まなければなりません。Name1,Value1,...,NameN,ValueN のように、複数の名前と値のペアの引数を、任意の順番で指定できます。

例: sds = signalDatastore('C:\dir\signaldata','FileExtensions','.csv')

サブフォルダー包含フラグ。'IncludeSubfolders'true または false からなるコンマ区切りのペアとして指定します。すべてのファイルとサブフォルダーを各フォルダー内に含める場合は true を、ファイルのみを各フォルダー内に含める場合は false を指定します。

例: 'IncludeSubfolders',true

データ型: logical | double

信号ファイル拡張子。'FileExtensions' と、string スカラー、string 配列、文字ベクトル、または文字ベクトルの cell 配列で構成されるコンマ区切りのペアとして指定します。

読み取り関数を指定しない場合、'FileExtensions'.mat が MAT ファイルを読み取る、または .csv が CSV ファイルを読み取るようにのみ設定できます。'FileExtensions' を省略した場合、指定した場所に MAT ファイルがあれば既定値は .mat になり、指定した場所に CSV ファイルがあれば 'FileExtensions' の既定値は .csv になります。

MAT ファイルと CSV ファイルがどちらも存在しない場合、signalDatastore は既定の関数 read でエラーとなります。関数 ReadFcn を使用してカスタム関数 read を指定することにより、他のタイプのファイルを読み取ります。

ファイル拡張子を指定しない場合、signalDatastore は、既定で読み取る拡張子を決定するためにファイルを解析する必要があります。解析時間が発生しないように拡張子を指定します。

例: 'FileExtensions','.csv'

データ型: string | char | cell

これらの名前と値のペアに加え、このページの任意のプロパティ (Files プロパティを除く) を名前と値のペアとして指定することもできます。

プロパティ

すべて展開する

インメモリ データ

メンバー名。cell 配列として指定します。入力データのメンバー名の長さは、data cell 配列の長さと等しくなければなりません。このプロパティは、データストアがインメモリ データを含む場合にのみ適用されます。

信号メンバー データ。string スカラーまたは string 配列として指定します。入力データのメンバー名の長さは、data cell 配列の長さと等しくなければなりません。このプロパティは、データストアがインメモリ データを含む場合にのみ適用されます。

ファイル データ

データストアに含まれるファイル。string または文字ベクトルの cell 配列として指定します。cell 配列内の各文字ベクトルは、ファイルへの絶対パスを表します。signalDatastore 内の引数 location は、データストア作成時に Files を定義します。このプロパティは、データストアがファイル データを含む場合にのみ適用されます。

データ型: string | char | cell

データを読み取る関数。関数ハンドルとして指定します。この関数は、入力としてファイル名を取得した後、対応するデータを出力しなければなりません。たとえば、customreader がデータを読み取るために指定された関数である場合、この関数は次のようなシグネチャをもたなければなりません。

function [data,info] = customreader(filename)
...
end

信号データは変数 data に出力されます。変数 info は、時間情報およびファイルからの他の関連情報を含む構造体です。

例: @customreader

データ型: function_handle

代替ファイル システムのルート パス。'AlternateFileSystemRoots' と、string ベクトルまたは cell 配列から構成されるコンマ区切りのペアとして指定します。データストアはローカル マシンに作成するが、(オペレーティング システムが異なる可能性のある) 別のマシン上のデータにアクセスして処理する必要がある場合、'AlternateFileSystemRoots' を使用します。Parallel Computing Toolbox™ と MATLAB® Parallel Server™ を使用してデータを処理する場合、およびデータをローカル マシンに保存するのに加えて、そのデータのコピーを異なるプラットフォームのクラウドやクラスター マシンで利用できるようにする場合も、'AlternateFileSystemRoots' を使用してルート パスを関連付けなければなりません。

  • 互いに等価なルート パスのセットを関連付けるには、'AlternateFileSystemRoots' を string ベクトルとして指定します。次に例を示します。

    ["Z:\datasets","/mynetwork/datasets"]

  • データストアに対して等価なルート パスの複数のセットを関連付けるには、各行が等価なルート パスのセットを表す複数の行を含んだ cell 配列として 'AlternateFileSystemRoots' を指定します。cell 配列の各行を、string ベクトル、または文字ベクトルの cell 配列のいずれかとして指定します。次に例を示します。

    • 'AlternateFileSystemRoots' を string ベクトルの cell 配列として指定します。

      {["Z:\datasets", "/mynetwork/datasets"];...
       ["Y:\datasets", "/mynetwork2/datasets","S:\datasets"]}

    • または、'AlternateFileSystemRoots' を文字ベクトルの cell 配列の cell 配列として指定します。

      {{'Z:\datasets','/mynetwork/datasets'};...
       {'Y:\datasets', '/mynetwork2/datasets','S:\datasets'}}

'AlternateFileSystemRoots' の値は次の条件を満たさなければなりません。

  • 1 つ以上の行を含む。各行は等価なルート パスのセットを指定する。

  • 各行は複数のルート パスを指定する。各ルート パスは少なくとも 2 文字を含まなければならない。

  • ルート パスは一意であり、互いのサブフォルダーではない。

  • ファイルの場所を指すルート パス エントリを少なくとも 1 つ含む。

詳細については、異なるマシンまたはクラスターで処理するためのデータ ストアの設定を参照してください。

例: ["Z:\datasets","/mynetwork/datasets"]

データ型: string | cell

信号ファイル内の変数名。一意の名前をもつ string のスカラーまたはベクトルとして指定します。ファイルに複数の変数が含まれ、読み取る信号データを保持する変数の名前を指定する場合に、このプロパティを使用します。

  • このプロパティ値が string スカラーの場合、signalDatastore は指定した変数に含まれるデータを返します。

  • このプロパティ値が string ベクトルの場合、signalDatastore は指定した変数に含まれるデータをもつ cell 配列を返します。

メモ

ファイルの最初の変数名を決めるために、signalDatastore は以下の手順に従います。

  • MAT ファイルの場合:

    s = load(fileName);
    varNames = fieldnames(s);
    firstVar = s.(varNames{1});

  • CSV ファイルの場合:

    opts = detectImportOptions(fileName,'PreserveVariableNames',true);
    varNames = opts.VariableNames;
    firstVar = string(varNames{1});

このプロパティは、データストアがファイル データを含み、既定の読み取り関数が使用されている場合にのみ適用されます。

サンプル レートを保持する変数名。string スカラーとして指定します。このプロパティは、データストアがファイル データを含む場合にのみ適用されます。

サンプル時間値を保持する変数名。string スカラーとして指定します。このプロパティは、データストアがファイル データを含む場合にのみ適用されます。

時間値ベクトルを保持する変数名。string スカラーとして指定します。このプロパティは、データストアがファイル データを含む場合にのみ適用されます。

メモ

'SampleRateVariableName''SampleTimeVariableName' および 'TimeValuesVariableName' は互いに排他的です。信号データの時間情報を保持する変数がファイルに含まれる場合、これらのプロパティを使用します。指定しない場合、signalDatastore は信号データが時間情報をもたないものと仮定します。カスタム関数 read を指定した場合、これらのプロパティは無効になります。

インメモリ データとファイル データ

サンプル レート値。正の実数スカラーまたはベクトルとして指定します。

  • signalDatastore 内のすべての信号に同じサンプル レートを指定するには、SampleRate の値をスカラーに設定します。

  • signalDatastore 内の各信号に異なるサンプル レートを指定するには、SampleRate の値をベクトルに設定します。

ベクトル内の要素数は、signalDatastore 内の要素数と等しくなければなりません。

サンプル時間値。正のスカラー、ベクトル、duration スカラー、または duration ベクトルとして指定します。

  • signalDatastore 内のすべての信号に同じサンプル時間を指定するには、SampleTime の値をスカラーに設定します。

  • signalDatastore 内の各信号に異なるサンプル時間を指定するには、SampleTime の値をベクトルに設定します。

ベクトル内の要素数は、signalDatastore 内の要素数と等しくなければなりません。

時間値。ベクトル、duration ベクトル、行列、または cell 配列として指定します。

  • signalDatastore 内のすべての信号に同じ時間値を指定するには、TimeValues を数値ベクトルまたは duration ベクトルに設定します。ベクトルはセット内のすべての信号と同じ長さでなければなりません。

  • signalDatastore の各信号が同じ時間値の信号をもち、信号ごとに時間値が異なることを指定するには、TimeValues を数値行列、duration 行列、cell 配列のいずれかに設定します。

    • TimeValues が行列の場合は、列数が signalDatastore のメンバー数と等しくなければなりません。データストア内のすべての信号は、長さが行列の行数と等しくなければなりません。

    • TimeValues が cell 配列の場合は、ベクトル数が signalDatastore のメンバー数と等しくなります。メンバー内のすべての信号は、長さが cell 配列内の対応するベクトルの要素数と等しくなければなりません。

read によって返される信号ファイルの最大数。正の実数スカラーとして指定します。ReadSize プロパティを n に設定した場合 (n > 1)、関数 read が呼び出されるたびに関数は以下を読み取ります。

  • sds にファイル データが含まれている場合における、最初の n ファイルの最初の変数

  • sds にインメモリ データが含まれている場合における、最初の n メンバー

read の出力は、ReadSize > 1 のとき、信号データの cell 配列となります。

オブジェクト関数

read次の連続信号観測値の読み取り
readallデータストアのすべての信号の読み取り
previewプレビューを目的としたデータストアの最初の信号観測値の読み取り
shuffle信号データストアの信号のシャッフル
subset信号のサブセットをもつデータストアの作成
partition信号データストアの分割、および分割した部分の返却
numpartitions並列処理を目的とした妥当な区画数の推定の返却
resetデータ ストアの初期状態へのリセット
progress 読み取ったデータ量の判定
hasdataデータが読み取り可能かどうかを判別
transformデータ ストアの変換
combine複数のデータストアのデータの結合
isPartitionableデータストアが分割可能かどうかを判別
isShuffleableデータストアがシャッフル可能かどうかを判別

メモ

isPartitionable および isShuffleable は、既定では signalDatastore に対し true を返します。combine および transform の出力が分割可能またはシャッフル可能かどうかは、この 2 つの関数を使用してテストできます。

すべて折りたたむ

信号データストアを作成して、信号データのインメモリ cell 配列の要素を反復します。データは正弦波変調された線形チャープ、凹二次チャープ、および電圧制御発振器で構成されます。信号は、3000 Hz でサンプリングされます。

fs = 3000;
t = 0:1/fs:3-1/fs;
data = {chirp(t,300,t(end),800).*exp(2j*pi*10*cos(2*pi*2*t)); ...
        2*chirp(t,200,t(end),1000,'quadratic',[],'concave'); ...
        vco(sin(2*pi*t),[0.1 0.4]*fs,fs)};
sds = signalDatastore(data,'SampleRate',fs);

データストアにデータがある場合は、信号データストアから各観測値を読み取り、短時間フーリエ変換をプロットします。

plotID = 1;
while hasdata(sds)
    [dataOut,info] = read(sds);
    subplot(3,1,plotID)
    stft(dataOut,info.SampleRate)
    plotID = plotID + 1;
end

Signal Processing Toolbox™ に含まれるサンプル信号へのパスを指定します。

folder = fullfile(matlabroot,'examples','signal','data');

指定したフォルダーを示す信号データストアを作成および表示します。

sds = signalDatastore(folder)
sds = 
  signalDatastore with properties:

                       Files:{
                             ' .../devel/bat/Bdoc20b/build/matlab/examples/signal/data/GANModel.mat';
                             ' .../devel/bat/Bdoc20b/build/matlab/examples/signal/data/HeartRates.mat';
                             ' .../devel/bat/Bdoc20b/build/matlab/examples/signal/data/Hello.mat'
                              ... and 26 more
                             }
    AlternateFileSystemRoots: [0x0 string]
                    ReadSize: 1

Signal Processing Toolbox™ に含まれる信号サンプルへのファイル パスを指定します。

folder = fullfile(matlabroot,'examples','signal','data');

指定したフォルダー内の .csv ファイルを示す信号データストアを作成します。

sds = signalDatastore(folder,'FileExtensions','.csv')
sds = 
  signalDatastore with properties:

                       Files:{
                             ' .../devel/bat/Bdoc20b/build/matlab/examples/signal/data/tremor.csv'
                             }
    AlternateFileSystemRoots: [0x0 string]
                    ReadSize: 1

Signal Processing Toolbox™ に含まれる 4 つのサンプル ファイルへのパスを指定します。

folder = fullfile(matlabroot,'examples','signal','data', ...
         ["INR.mat","relatedsig.mat","spots_num.mat","voice.mat"]);    

2 つのファイルから同時にデータを読み取るには、ReadSize プロパティを 2 に設定します。各 read では、最初の cell が最初に読み取ったファイルの最初の変数を含み、2 番目の cell が 2 番目のファイルの最初の変数を含む cell 配列が返されます。データストアにデータがある場合、各 read で読み取った変数の名前を表示します。

sds = signalDatastore(folder,'ReadSize',2);
while hasdata(sds)
    [data,info] = read(sds);
    fprintf('Variable Name:\t%s\n',info.SignalVariableNames)
end
Variable Name:	Date
Variable Name:	s1
Variable Name:	year
Variable Name:	fs

Signal Processing Toolbox™ に含まれる 3 つの信号へのパスを指定します。

  • strong.mat ファイルには、her、him および fs という 3 つの変数が格納されています。

  • slogan.mat ファイルには、hotwordphrase および fs という 3 つの変数が格納されています。

  • Ring.mat ファイルには、y および Fs という 2 つの変数が格納されています。

fld = ["strong.mat","slogan.mat","Ring.mat"];
folder = fullfile(matlabroot,'examples','signal','data',fld);

指定したフォルダーを示す信号データストアを作成します。各ファイルには、名前の異なる複数の変数が格納されています。各ファイル内のスカラーは、サンプル レートを表します。カスタム読み取り関数を定義します。この関数は、ファイル内のすべての変数を構造体として読み取り、dataOut 内の変数および infoOut 内の変数の情報を返します。infoOutSampleRate フィールドには各ファイルに含まれるスカラーが含まれ、dataOut には各ファイルから読み取った変数が含まれます。

function [dataOut,infoOut] =   MyCustomRead(filename)
    fText = importdata(filename);
    value = struct2cell(fText);
    dataOut = {};
    for i = 1:length(value)
        if isscalar(value{i}) == 1
            infoOut.SampleRate = value{i};
        else
            dataOut{end+1} = value{i};
        end
    end
end
sds = signalDatastore(folder,'ReadFcn',@MyCustomRead);

データストアに読み取られていないファイルがある場合、データストアから読み取って、信号の短時間フーリエ変換を計算します。

while hasdata(sds)
    [data,infoOut] = read(sds);
    fs = infoOut.SampleRate;
    figure
    for i = 1:length(data)
        if length(data)>1
        subplot(2,1,i)
        end
        stft(data{i},fs)   
    end
end

Signal Processing Toolbox™ に含まれるサンプル ファイルへのパスを指定します。各ファイルには、2 つの信号と 3000 ~ 4000 Hz の範囲のランダム サンプル レート fs が含まれます。

  • 最初の信号 x1 は、振動する振幅の領域および増加傾向で変動する周波数の領域によって分離された、持続時間が減少していく一連のパルスで構成されています。

  • 2 番目の信号 x2 は、正弦関数的に変化する周波数成分をもつチャープです。

folder = fullfile(matlabroot,'examples','signal','data','dataset');

指定したフォルダーを示す信号データストアを作成し、信号変数名とサンプル レートを設定します。データストアにデータがある場合は、各観測値を読み取り、そのスペクトログラムを可視化します。

sds = signalDatastore(folder,'SignalVariableNames',['x1';'x2'],'SampleRateVariableName','fs');
plotID = 1;
while hasdata(sds) 
    [data,info] = read(sds);
    subplot(2,2,plotID)
    pspectrum(data{1},info.SampleRate,'OverlapPercent',50,'Leakage',1,'TwoSided',true,'spectrogram')
    subplot(2,2,plotID+1)
    pspectrum(data{2},info.SampleRate,'OverlapPercent',90,'Leakage',0.4,'TwoSided',true,'spectrogram')
    plotID = plotID + 2;
end

R2020a で導入