signalDatastore

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

R2020a 以降

説明

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

作成

構文

sds = signalDatastore(data)

sds = signalDatastore(location)

sds = signalDatastore(___,Name,Value)

説明

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

sds = signalDatastore(location) は、location にある MAT ファイルまたは CSV ファイルのいずれかのコレクションに基づいて信号データストアを作成します。location に MAT ファイルと CSV ファイルが混在している場合、sds には MAT ファイルが含まれます。

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

入力引数

data — インメモリ入力データ

ベクトルの cell 配列 | 行列の cell 配列 | timetable の cell 配列 | cell 配列の cell 配列

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

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

location — データストアに含めるファイルまたはフォルダー

FileSet オブジェクト | パス | DsFileSet オブジェクト

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

• FileSet オブジェクト — location を FileSet オブジェクトとして指定できます。場所を FileSet オブジェクトとして指定すると、パスまたは DsFileSet オブジェクトを指定するよりもデータストアの構築時間が短縮されます。詳細については、matlab.io.datastore.FileSet を参照してください。

• ファイル パス — 単一のファイル パスを文字ベクトルまたは string スカラーとして指定できます。複数のファイル パスを文字ベクトルの cell 配列または string 配列として指定できます。

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

ファイルまたはフォルダーはローカルでもリモートでも構いません。

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

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

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

例: 'whale.mat'

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

データ型: char | string | cell

名前と値の引数

オプションの引数のペアを Name1=Value1,...,NameN=ValueN として指定します。ここで、Name は引数名で、Value は対応する値です。名前と値の引数は他の引数の後に指定しなければなりませんが、ペアの順序は重要ではありません。

R2021a より前では、コンマを使用して名前と値をそれぞれ区切り、Name を引用符で囲みます。

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

IncludeSubfolders — サブフォルダー包含フラグ

false または 0 (既定値) | true または 1

サブフォルダー包含フラグ。true または false として指定します。すべてのファイルとサブフォルダーを各フォルダー内に含める場合は true を、ファイルのみを各フォルダー内に含める場合は false を指定します。

例: 'IncludeSubfolders',true

データ型: logical | double

FileExtensions — 信号ファイル拡張子

文字ベクトル | 文字ベクトルの cell 配列 | string スカラー | string 配列

信号ファイル拡張子。string スカラー、string 配列、文字ベクトル、または文字ベクトルの cell 配列として指定します。

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

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

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

例: 'FileExtensions','.csv'

データ型: string | char | cell

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

プロパティ

インメモリ データ

Members — メンバー名

cell 配列

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

MemberNames — 信号メンバー データ

["Member1"..."MemberN"] (既定値) | string スカラー | string 配列

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

ファイル データ

Files — データストアに含まれるファイル

string の cell 配列 | 文字ベクトルの cell 配列

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

データ型: string | char | cell

ReadFcn — カスタム読み取り関数

read (既定値) | 関数ハンドル

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

function data = customreader(filename)
...
end

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

信号データは変数 data に出力されます。変数 info は、ファイルのユーザー定義情報を含むユーザー定義の構造体でなければなりません。追加の引数が必要な場合は、引数 filename の後に追加できます。signalDatastore は、ファイル名を含むフィールドを info 構造体に追加します。

例: @customreader

データ型: function_handle

AlternateFileSystemRoots — 代替ファイル システムのルート パス

string ベクトル | cell 配列

代替ファイル システムのルート パス。"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

SignalVariableNames — 信号ファイル内の変数名

最初の変数名 (既定値) | string スカラー | string ベクトル

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

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

• このプロパティ値が string ベクトルの場合、signalDatastore は指定した変数に含まれるデータをもつ cell 配列を返します。この場合、ReadOutputOrientation プロパティを使用して、出力 cell 配列の向きを列または行として指定できます。

このプロパティを指定しない場合、signalDatastore は各ファイルの変数リストの最初の変数を読み取ります。

メモ

ファイルの最初の変数名を決めるために、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});

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

ReadOutputOrientation — 出力信号データの cell 配列の向き

'column' (既定値) | 'row'

出力信号データの cell 配列の向き。'column' または 'row' として指定します。SignalVariableNames に複数の信号名が含まれている場合、このプロパティは関数 read を呼び出した後に出力信号データの cell 配列の向きをどのように決めるかを指定します。ReadOutputOrientation は、SignalVariableNames に要素が 1 つしか含まれていない場合は効果がなく、SignalVariableNames が指定されていない場合は適用されません。

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

例:出力 cell 配列の向き

信号データストア内のファイルから複数の変数を読み取るの例では、data は既定の出力方向をもつ 2 行 1 列の列配列になっています。

    {1×4941 double}
    {1×4941 double}

ReadOutputOrientation に 'row' を指定した場合、data は 1 行 2 列の行配列になります。

    {1×4941 double}    {1×4941 double}

SampleRateVariableName — サンプル レートを保持する変数名

string スカラー

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

SampleTimeVariableName — サンプル時間値を保持する変数名

string スカラー

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

TimeValuesVariableName — 時間値ベクトルを保持する変数名

string スカラー

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

メモ

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

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

SampleRate — サンプル レート値

正のスカラー | 正のベクトル

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

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

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

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

SampleTime — サンプル時間値

正のスカラー | ベクトル | duration スカラー | duration ベクトル

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

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

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

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

TimeValues — 時間値

ベクトル | duration ベクトル | 行列 | cell 配列

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

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

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

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

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

ReadSize — read によって返される信号ファイルの最大数

1 (既定値) | 正の実数のスカラー

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

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

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

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

オブジェクト関数

read	次の連続信号観測値の読み取り
readall	データストアのすべての信号の読み取り
writeall	Write datastore to files
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

信号データストアの作成

フォルダー dataset には、Signal Processing Toolbox™ に含まれる信号サンプルが格納されています。フォルダーを示す信号データストアを作成し、サンプル レート変数の名前を設定します。

folder = "dataset";
sds = signalDatastore(folder,SampleRateVariableName="fs");

データストア内の最初のファイルを読み取り、スペクトログラムをプロットします。

[data,info] = read(sds);
pspectrum(data,info.SampleRate,"spectrogram")

信号データストアに含めるファイル拡張子の指定

Signal Processing Toolbox™ に含まれる信号サンプルが格納されているフォルダーを指定します。信号は .csv ファイル、.dat ファイル、および .mat ファイルに保存されています。

folder = "healthdata";

指定したフォルダー内の .csv ファイルを示す信号データストアを作成します。信号の短時間フーリエ変換をプロットします。

sds = signalDatastore(folder,FileExtensions=".csv",SignalVariableNames=["tx" "x"]);
data = read(sds);
stft(data{2})

信号データストアでの複数ファイルの読み取り

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

files = ["INR.mat","relatedsig.mat","spots_num.mat","voice.mat"];    

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

sds = signalDatastore(files,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 ファイルには、hotword、phrase および fs という 3 つの変数が格納されています。

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

各ファイルには、名前の異なる複数の変数が格納されています。各ファイル内のスカラーは、サンプル レートを表します。カスタム読み取り関数を定義します。この関数は、ファイル内のすべての変数を構造体として読み取り、dataOut 内の変数および infoOut 内の変数の情報を返します。infoOut の SampleRate フィールドには各ファイルに含まれるスカラーが含まれ、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

files = ["strong.mat","slogan.mat","Ring.mat"];
sds = signalDatastore(files,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

信号データストア内のファイルから複数の変数を読み取る

dataset フォルダーには、Signal Processing Toolbox™ に含まれるサンプル ファイルが格納されています。各ファイルには、2 つの信号と 3000 ～ 4000 Hz の範囲のランダム サンプル レート fs が含まれます。

• 最初の信号 x1 は、凸 2 次チャープです。

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

folder = "dataset";

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

sds = signalDatastore(folder,SignalVariableNames=["x1";"x2"],SampleRateVariableName="fs");

tiledlayout flow
while hasdata(sds) 
    [data,info] = read(sds);
    nexttile
    pspectrum(data{1},info.SampleRate,"spectrogram",TwoSided=true)
    nexttile
    pspectrum(data{2},info.SampleRate,"spectrogram",TwoSided=true)
end

バージョン履歴

R2020a で導入

参考

datastore | mapreduce | tall

トピック

• 深層学習を使用した波形セグメンテーション
• 領域固有の深層学習用途のためのデータの前処理 (Deep Learning Toolbox)
• Manage Data Sets for Machine Learning and Deep Learning Workflows