ドキュメンテーション

最新のリリースでは、このページがまだ翻訳されていません。 このページの最新版は英語でご覧になれます。

fileDatastore

カスタム ファイル リーダーを使用するデータ ストア

説明

カスタム形式ファイルの大規模な集合 (集合が必ずしもメモリに収まるとは限らない場合や、大規模なカスタム形式ファイルがメモリに収まらない場合) を管理するには、FileDatastore オブジェクトを使用します。関数 fileDatastore を使用して FileDatastore オブジェクトを作成し、そのプロパティを指定すると、オブジェクト関数を使用してデータのインポートおよび処理ができます。

作成

説明

fds = fileDatastore(location,'ReadFcn',@fcn) は、location で指定されたファイルのコレクションからデータ ストアを作成し、関数 fcn を使用してファイルからデータを読み取ります。

fds = fileDatastore(location,'ReadFcn',@fcn,Name,Value) は、1 つ以上の名前と値のペアの引数を使用して、fds の追加のパラメーターとプロパティを指定します。たとえば、fileDatastore(location,'ReadFcn',@customreader,'FileExtensions',{'.exts','.extx'}) を使用して、ファイルの拡張子に従ってデータ ストアに含めるファイルを指定できます。

入力引数

すべて展開する

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

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

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

    • リモートのファイルまたはフォルダー — locationhdfs:///path_to_file の形式の国際化リソース識別子 (IRI) として、ファイルまたはフォルダーの絶対パスに指定します。詳細については、リモート データの操作を参照してください。

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

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

例: 'file1.ext'

例: '../dir/data/file1.ext'

例: {'C:\dir\data\file1.exts','C:\dir\data\file2.extx'}

例: 'C:\dir\data\*.ext'

ファイル データを読み取る関数。関数ハンドルとして指定します。

関数ハンドル @fcn で表される関数のシグネチャは、指定した ReadMode の値によって決まります。ファイル データを読み取る関数は、次のシグネチャのいずれかに確定されなければなりません。

ReadMode

ReadFcn のシグネチャ

'file' (既定)

関数には次のシグネチャが必要です。

function data = MyReadFcn(filename)
...
end

filename — 読み取るファイルの名前

data — 対応するファイル データ

'partialfile'

関数には次のシグネチャが必要です。

function [data,userdata,done] = MyReadFcn(filename,userdata)
...
end

userdata — 複数の FileDatastore 読み取り呼び出し間でデータを持続するように userdata のフィールドを設定して読み取ります。

done — この logical 引数を true または false に設定します。

  • false — 現在のファイルの読み取りを続行します。

  • true — 現在のファイル読み取りを終了して次のファイルを読み取ります。

data — ファイル データの部分

'byte'

関数には次のシグネチャが必要です。

function data = MyReadFcn(filename,offset,size)
...
end

offset — ファイルの最初のバイトからのバイト オフセットを指定します。

size — 現在の読み取り処理で読み取るバイト数を指定します。

dataBlockSize で指定されたサイズをもつ、ファイル データの部分

FileDatastore は、BlockSize で指定された値に基づいて offsetsize の両方の入力をインクリメントします。

@fcn で指定された値は、ReadFcn プロパティの値を設定します。

例: @customreader

データ型: function_handle

名前と値のペアの引数

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

例: fds = fileDatastore('C:\dir\data','FileExtensions',{'.exts','.extx'})

サブフォルダーを含めるかどうかのフラグ。'IncludeSubfolders' と、truefalse、0、1 のいずれかで構成されるコンマ区切りのペアとして指定します。各フォルダー内のすべてのファイルとサブフォルダーを含めるには true を指定し、各フォルダー内のファイルのみを含めるには false を指定します。

'IncludeSubfolders' を指定しない場合、既定値は false です。

例: 'IncludeSubfolders',true

データ型: logical | double

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

ファイル拡張子を指定すると、関数 fileDatastore は指定された拡張子をもつファイルについてのみ datastore オブジェクトを作成します。'FileExtensions' を空の文字ベクトル '' として指定することで、拡張子のないファイルのデータ ストアを作成することもできます。'FileExtensions' を指定しない場合、fileDatastore は自動的にフォルダー内のすべてのファイルを含めます。

例: 'FileExtensions',''

例: 'FileExtensions','.ext'

例: 'FileExtensions',{'.exts','.extx'}

データ型: char | cell | string

入力データをプレビューする関数。関数ハンドルとして指定します。

プレビュー関数を指定しない場合、FileDatastore@ReadFcn で指定された値を既定のプレビュー関数として使用します。あるいは、データ用に独自のカスタム プレビュー関数を指定することもできます。

  • @ReadFcn (既定) — ReadFcn を使用して FileDatastore データをサンプリングします。このオプションにより、tall 構成のパフォーマンスが遅くなることがあります。

  • Function handleFileDatastore 用のカスタム プレビュー関数と tall 構成を使用して入力データをサンプリングします。PreviewFcn を使用して、プレビューと tall 構成用に入力データの必要最小限の部分のみを読み取る関数を指定します。

PreviewFcn で指定される関数は、ReadFcn が返すものと同じデータ型の値を返さなければなりません。

データ型: function_handle

読み取るファイルの部分。'file''partialfile'、または 'bytes' として指定します。

'file' (既定)

ReadFcn で指定されたカスタム関数が一度の読み取り処理でファイル全体を読み取る場合は、読み取りモード 'file' を使用します。

カスタム読み取り関数に基づき、ファイル データ ストアは read の呼び出しごとにファイル全体を読み取ります。並列化の単位はファイル全体です。

'partialfile'

'partialfile' で指定されたカスタムのファイル読み取り関数が、読み取り処理ごとにファイルの一部のみを読み取る場合は、読み取りモード ReadFcn を使用します。

カスタム読み取り関数に基づき、ファイル データ ストアは関数 read の呼び出しのたびにファイルの一部のみを読み取ります。

読み取りモード 'partialfile' では、並列化の単位はファイル全体です。ファイル全体を読み取るには、連続した複数回の read 処理が必要です。

'bytes'

ReadFcn で指定されたカスタム関数が読み取り処理ごとにサイズ BlockSize のファイル部分を読み取る場合は、読み取りモード 'bytes' を使用します。

FileDatastore は、並列化の単位を、BlockSize で指定されたバイト数をもつファイルのブロックに設定します。

カスタム読み取り関数に基づき、ファイル データ ストアは読み取り関数の呼び出しのたびにサイズ BlockSize のファイル部分を読み取ります。ファイル全体を読み取るには、複数の read の並列処理が必要です。

データ型: char | string

read 処理ごとに読み取るバイト数。正の整数として指定します。

ファイルの複数ブロックを複数の並列 MATLAB® ワーカー間に確実に分散させるには、BlockSize131072 バイト (128 KB) より大きい正の整数として指定します。

BlockSize 値の指定または変更を行うには、まず ReadMode'bytes' に設定しなければなりません。FileDatastoreReadMode で指定された値に基づいて BlockSize の既定値を設定します。

  • ReadMode'file' または 'partialfile' の場合、FileDatastore は既定の BlockSizeinf に設定。

  • ReadMode'bytes' の場合、FileDatastore は既定の BlockSize128 MB に設定。

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

  • 相互に対応する 1 組のルート パスを関連付けるには、'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 行以上の行を含み、各行は 1 組の対応するルート パスを指定する。

  • 各行は複数のルート パスを指定し、各ルート パスは 2 文字以上を含まなければならない。

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

  • ファイルの場所を指す 1 つ以上のルート パス エントリを含む。

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

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

データ型: string | cell

プロパティ

すべて展開する

FileDatastore プロパティは、FileDatastore オブジェクトに関連付けられているファイルを記述します。Files プロパティを除く FileDatastore プロパティの値を、名前と値のペアの引数を使用して指定できます。オブジェクトの作成後にプロパティの表示または変更を行うには、ドット表記を使用します。

データ ストアに含まれるファイル。文字ベクトル、文字ベクトルの cell 配列、string スカラーまたは string 配列として解決されます。個々の文字ベクトルまたは string はファイルへの絶対パスです。関数 fileDatastore および関数 datastorelocation 引数は、データ ストアの作成時に Files を定義します。

例: {'C:\dir\data\file1.ext';'C:\dir\data\file2.ext'}

例: 'hdfs:///data/*.mat'

データ型: char | cell | string

ファイル データを読み取る関数。関数ハンドルとして指定します。

@fcn で指定される値により、ReadFcn プロパティの値が設定されます。

例: @MyCustomFileReader

データ型: function_handle

このプロパティは読み取り専用です。

垂直方向に連結可能のフラグ。logical true または logical false として指定します。このプロパティ値は、FileDatastore オブジェクトを初めて作成するときに指定します。

true

FileDatastore オブジェクトの複数回の読み取りで、垂直方向に連結可能な一様のデータが返されます。

UniformRead プロパティ値が true である場合:

  • 関数 ReadFcn は垂直方向に連結可能なデータを返さなければなりません。そうでない場合、readall メソッドはエラーを返します。

  • 関数 tall の出力の基となるデータ型は、ReadFcn の出力のデータ型と同じです。

false (既定)

FileDatastore オブジェクトの複数回の読み取りで、垂直方向に連結可能な一様のデータは返されません。

UniformRead プロパティ値が false である場合:

  • readall は cell 配列を返します。

  • tall は tall cell 配列を返します。

例: fds = fileDatastore(location,'ReadFcn',@load,'UniformRead',true)

データ型: logical | double

オブジェクト関数

hasdataデータが読み取り可能かどうかを判別
numpartitionsデータ ストアの区画数
partitionデータ ストアを分割する
previewデータ ストア内のデータのサブセット
readデータ ストアのデータの読み取り
readallデータ ストアのすべてのデータの読み取り
resetデータ ストアの初期状態へのリセット
transformデータ ストアの変換
combine複数のデータ ストアのデータを統合

すべて折りたたむ

MATLAB® demos フォルダー内にあり、拡張子が .mat のファイルのデータ ストアを作成します。

fds = fileDatastore(fullfile(matlabroot,'toolbox','matlab','demos'),'ReadFcn',@load,'FileExtensions','.mat')
fds = 

  FileDatastore with properties:

                       Files: {
                              ' ...\matlab\toolbox\matlab\demos\accidents.mat';
                              ' ...\matlab\toolbox\matlab\demos\airfoil.mat';
                              ' ...\matlab\toolbox\matlab\demos\airlineResults.mat'
                               ... and 37 more
                              }
                 UniformRead: 0
                     ReadFcn: @load
    AlternateFileSystemRoots: {}

ファイル データを読み取る関数 load を指定して、MATLAB® demos フォルダー内のすべての .mat ファイルを含むデータ ストアを作成します。

fds = fileDatastore(fullfile(matlabroot,'toolbox','matlab','demos'),'ReadFcn',@load,'FileExtensions','.mat')
fds = 

  FileDatastore with properties:

                       Files: {
                              ' ...\matlab\toolbox\matlab\demos\accidents.mat';
                              ' ...\matlab\toolbox\matlab\demos\airfoil.mat';
                              ' ...\matlab\toolbox\matlab\demos\airlineResults.mat'
                               ... and 37 more
                              }
                 UniformRead: 0
                     ReadFcn: @load
    AlternateFileSystemRoots: {}

データ ストア内の最初のファイルを読み取り、次に 2 番目のファイルを読み取ります。

data1 = read(fds);
data2 = read(fds);

データ ストア内のすべてのファイルを一度に読み取ります。

readall(fds);

データおよびカウンター i を保持するように cell 配列を初期化します。

dataarray = cell(numel(fds.Files), 1);
i = 1;

データ ストアを最初のファイルにリセットし、データが残らなくなるまでファイルを一度に 1 つずつ読み取ります。データを配列 dataarray に割り当てます。

reset(fds);
while hasdata(fds)
    dataarray{i} = read(fds);
    i = i+1;
end

メモリに必ずしも収まらない大規模な MAT ファイルから読み取るためのデータ ストアを作成することができます。使用できるメモリに大規模な MAT ファイルの各配列が収まると仮定して、データを読み取って処理するためのデータ ストアを 3 つの手順で作成します。

  1. MAT ファイルから配列を一度に 1 つずつ読み取るカスタムの読み取り関数を作成します。

  2. データ ストア関数に部分読み取りを実行するパラメーターを設定します。

  3. MAT ファイルから配列を一度に 1 つずつ読み取ります。

MAT ファイルから配列を一度に 1 つずつ読み取るカスタム関数を作成します。この関数には、FileDatastore の引数 @ReadFcn で説明されているように、シグネチャが必要です。このファイルを、作業フォルダーまたは MATLAB® パス上のフォルダーに保存します。この例では、カスタム関数 load_variable はここに含められます。

type load_variable.m
function [data,variables,done] = load_variable(filename,variables)
    
    % If variable list is empty, 
    % create list of variables from the file
    if isempty(variables) 
        variables = who('-file', filename);
    end
    
    % Load a variable from the list of variables
    data = load(filename, variables{1});
    
    % Remove the newly-read variable from the list
    variables(1) = []; 
    
    % Move on to the next file if this file is done reading.
    done = isempty(variables); 
    
end

accidents.mat を含む FileDatastore を作成して設定します。'partialfile' を読み取りモードで使用し、load_variable をカスタム読み取り関数として使用するようにデータ ストア パラメーターを指定します。

fds = fileDatastore('accidents.mat','ReadMode','partialfile','ReadFcn',@load_variable);

データ ストアを使用して、ファイルから最初の 3 つの変数を読み取ります。ファイル accidents.mat には 9 つの変数があり、read を呼び出すたびに 1 つの変数が返されます。したがって、最初の 3 つの変数を取得するには、読み取り関数を 3 回呼び出します。

data = read(fds)
data = struct with fields:
    datasources: {3x1 cell}

data = read(fds)
data = struct with fields:
    hwycols: 17

data = read(fds)
data = struct with fields:
    hwydata: [51x17 double]

サンプル ファイル accidents.mat は小さくてメモリに収まりますが、メモリに収まらない大規模な MAT ファイルについても同様な結果が予測できます。

代替方法

関数 datastore を使用して、FileDatastore オブジェクトを作成することもできます。たとえば、ds = datastore(location,'Type','file','ReadFcn',@fcn) は、location で指定されたファイルの集合からデータ ストアを作成します。

R2016a で導入