ドキュメンテーション

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

fileDatastore

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

説明

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

作成

構文

fds = fileDatastore(location,'ReadFcn',@fcn)
fds = fileDatastore(location,Name,Value)

説明

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

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

入力引数

すべて展開する

データ ストアに含めるファイルまたはフォルダー。文字ベクトル、文字ベクトルの cell 配列、string スカラーまたは string 配列として指定します。ファイルが現在のフォルダーに存在しない場合、location は絶対パスまたは相対パスでなければなりません。指定したフォルダーのサブフォルダー内にあるファイルは、自動ではデータ ストアに含まれません。

location を指定するときにワイルドカード文字 (*) を使用できます。この文字は、一致するすべてのファイルや一致するフォルダー内のすべてのファイルをデータ ストアに含めることを示します。

ローカルで使用できないファイルについては、次の形式の IRI (国際化リソース識別子) を使用してファイルまたはフォルダーの絶対パスを指定しなければなりません。
hdfs:///path_to_file

Amazon S3™、Windows Azure® Blob Storage、および HDFS™ と共に datastore を使用する方法の詳細については、リモート データの操作を参照してください。

例: 'file1.ext'

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

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

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

データ型: char | cell | string

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

function data = customreader(filename)
..
end
複数の出力引数がある場合、データ ストアは最初の引数のみを使用し、残りは無視します。

@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

代替ファイル システムのルート パス。'AlternateFileSystemRoots' と string ベクトルまたは cell 配列で構成されるコンマ区切りのペアとして指定します。ローカル マシン上にデータ ストアを作成するが、別のマシン (異なるオペレーティング システムの可能性がある) 上でデータにアクセスして処理する必要がある場合は、'AlternateFileSystemRoots' を使用します。また、Parallel Computing Toolbox™ と MATLAB® Distributed Computing 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 オブジェクトに関連付けられているファイルを記述します。FileDatastore プロパティの値は、オブジェクトの作成時に名前と値のペアの引数を使用して指定できます。ただし、Files を除きます。オブジェクトの作成後にプロパティの表示または変更を行うには、ドット表記を使用します。

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

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

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

データ型: char | cell | string

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

function data = customreader(filename)
...
end
複数の出力引数がある場合、最初の出力引数のみが使用され、残りは無視されます。

例: @customreader

データ型: 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データ ストアの初期状態へのリセット

すべて折りたたむ

ファイル データを読み取る関数 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

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: {}

ヒント

  • FileDatastore オブジェクトは複数のファイルからデータを読み取るようにように設計されており、一度に 1 つのファイル全体を読み取ります。大きなファイルからデータのサブセットを読み取ったり、データ ストリームから読み取るには、独自のカスタム データ ストアを作成しなければなりません。詳細については、カスタム データ ストアの開発を参照してください。

代替方法

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

R2016a で導入