Main Content

fileDatastore

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

このページをすべて展開する

説明

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

作成

構文

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

説明

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

例

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

入力引数

すべて展開する

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

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

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

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

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

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

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

フォルダーを指定する場合、データストアにはサポートされているファイル形式のファイルのみが含まれ、その他の形式のファイルは無視されます。データストアに含めるファイル拡張子のカスタム リストを指定するには、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 — 現在の読み取り処理で読み取るバイト数を指定します。

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

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

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

例: @customreader

データ型: function_handle

名前と値の引数

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

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

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

サブフォルダーを含めるかどうかのフラグ。"IncludeSubfolders" と、true、false、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 handle — FileDatastore 用のカスタム プレビュー関数と 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 の並列処理が必要です。

FileDatastore オブジェクトで関数 subset および shuffle を使用するには、"ReadMode" を "file" に設定しなければなりません。

データ型: char | string

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

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

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

  • ReadMode が "file" または "partialfile" の場合、FileDatastore は既定の BlockSize を inf に設定。

  • ReadMode が "bytes" の場合、FileDatastore は既定の BlockSize を 128 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 および関数 datastore の location 引数は、データストアの作成時に Files を定義します。

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

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

データ型: char | cell | string

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

データストアの作成に使用するフォルダー。文字ベクトルの cell 配列として返されます。cell 配列は列ベクトルとして方向付けされます。各文字ベクトルは、データ ファイルを含むフォルダーへのパスです。関数 fileDatastore および関数 datastore の location 引数は、データストアの作成時に Folders を定義します。

FileDatastore オブジェクトの Files プロパティを変更すると、Folders プロパティがリセットされます。

データ型: cell

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

@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

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

書き込みでサポートされる形式。string の行ベクトルとして返されます。このプロパティは、writeall を使用してデータストアから出力ファイルを書き込む際に使用可能な出力形式を指定します。

オブジェクト関数

hasdataデータが読み取り可能かどうかを判別
numpartitionsデータストアの区画数
partitionデータストアを分割する
previewデータストア内のデータのサブセットをプレビュー
readデータストアのデータの読み取り
readallデータストアのすべてのデータの読み取り
writeallファイルへのデータストアの書き込み
resetデータストアの初期状態へのリセット
transformデータストアの変換
combine複数のデータストアのデータを統合
isPartitionableデータストアが分割可能かどうかを判別
isSubsettableDetermine whether datastore is subsettable
isShuffleableデータストアがシャッフル可能かどうかを判別
shuffleデータストア内のすべてのデータをシャッフルする
subsetデータストアまたは FileSet のサブセットの作成

例

すべて折りたたむ

FileSet オブジェクトまたはファイル パスを使用して fileDatastore オブジェクトを作成します。

FileSet オブジェクトを作成します。fileDatastore オブジェクトを作成します。

fs = matlab.io.datastore.FileSet("airlinesmall.parquet");
fds = fileDatastore(fs,"ReadFcn",@load)
fds = FileDatastore with properties:
                       Files: {
                              ' ...\matlab\toolbox\matlab\demos\airlinesmall.parquet'
                              }
                     Folders: {
                              '...\matlab\toolbox\matlab\demos'
                              }
                 UniformRead: 0
                    ReadMode: 'file'
                   BlockSize: Inf
                  PreviewFcn: @load
      SupportedOutputFormats: ["txt"    "csv"    "xlsx"    "xls"    "parquet"    "parq"    "png"    "jpg"    "jpeg"    "tif"    "tiff"    "wav"    "flac"    "ogg"    "mp4"    "m4a"]
                     ReadFcn: @load
    AlternateFileSystemRoots: {}

代わりに、ファイル パスを使用して fileDatastore オブジェクトを作成することもできます。

fds = fileDatastore("airlinesmall.parquet","ReadFcn",@load);

ファイル データを読み取る関数 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 38 more
                              }
                     Folders: {
                              '...\matlab\toolbox\matlab\demos'
                              }
                 UniformRead: 0
                    ReadMode: 'file'
                   BlockSize: Inf
                  PreviewFcn: @load
      SupportedOutputFormats: ["txt"    "csv"    "xlsx"    "xls"    "parquet"    "parq"    "png"    "jpg"    "jpeg"    "tif"    "tiff"    "wav"    "flac"    "ogg"    "mp4"    "m4a"]
                     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 ファイルについても同様な結果が予測できます。

ヒント

  • FileDatastore オブジェクトで関数 subset および shuffle を使用するには、"ReadMode" を "file" に設定しなければなりません。

バージョン履歴

R2016a で導入

参考

|

トピック