HDF5 ファイルへのエクスポート

概要

階層データ形式 Version 5 (HDF5) は科学データ保管のための、ハードウェアに依存しない汎用規格で、米国立スーパーコンピューター応用研究所 (National Center for Supercomputing Applications: NCSA) によって開発されました。HDF5 は、データ共有を目的とする標準のデータ保存方法が必要な工学および科学の諸分野で幅広く使用されています。HDF5 ファイル形式の詳細については、The HDF Group の Web サイト (https://www.hdfgroup.org) で入手できる HDF5 ドキュメンテーションを参照してください。

MATLAB^® には、HDF5 ファイルにデータをエクスポートする 2 つの方法が用意されています。

数値データセットを操作する場合にデータを簡単にエクスポートするための高水準関数
HDF5 C ライブラリのルーチンに対し MATLAB インターフェイスが利用できる低水準関数

メモ

互換性のない異なる形式の HDF4 ファイルへのエクスポートの詳細は、HDF4 ファイルへのエクスポートを参照してください。

MATLAB の高水準 HDF5 関数を使用したデータのエクスポート

MATLAB ワークスペースからデータまたはメタデータを HDF5 ファイルに書き込む最も簡単な方法は、以下の MATLAB 高水準関数を使用することです。

メモ

高水準関数では数値データしか扱えません。非数値データを書き込むには、低水準インターフェイスを使用しなければなりません。

h5create — HDF5 データセットを作成する。
h5write — HDF5 データセットにデータを書き込む。
h5writeatt — HDF5 属性にデータを書き込む。

これらの関数の使用方法についての詳細は、例が記載された各リファレンスページを参照してください。以下の節では、いくつかの一般的な用法シナリオについて説明します。

HDF5 データセットへの数値配列の書き込み

この例では配列を作成し、その配列を HDF5 ファイルに書き込みます。

ワークスペースに MATLAB 変数を作成します。この例では uint8 の値をもつ 5 行 5 列の配列が作成されます。
```
testdata = uint8(magic(5))
```
h5create を使用して、HDF5 ファイルとデータセットを作成します。
```
h5create('my_example_file.h5', '/dataset1', size(testdata))
```
データを HDF5 ファイルに書き込みます。
```
h5write('my_example_file.h5', '/dataset1', testdata)
```

MATLAB の低水準 HDF5 関数を使用したデータのエクスポート

MATLAB には、HDF5 ライブラリの関数に対応する "低水準" 関数が備わっており、HDF5 ライブラリの多くの関数に直接アクセスできます。この方法により、複素数データ型の読み取りと書き込みや HDF5 のサブセット化機能など、HDF5 ライブラリの機能に MATLAB からアクセスできます。

HDF5 ライブラリでは、ライブラリ関数が "インターフェイス" と呼ばれるコレクションの形で整理されています。たとえば、ファイルの開閉など、ファイルの取り扱いに関連するすべてのルーチンは H5F インターフェイスに含まれます。ここで F はファイルを表します。MATLAB では低水準の HDF5 関数を、それぞれの HDF5 インターフェイスに対応するクラスに分類します。たとえば、HDF5 ファイルインターフェイス (H5F) に対応する MATLAB 関数は、@H5F クラスフォルダーに入れられます。

以下の節では、MATLAB HDF5 低水準関数の使用方法について詳細を説明します。

メモ

このトピックでは、HDF5 ライブラリのすべての機能の説明や、基本的な HDF5 プログラミングの概念の説明は行いません。MATLAB の HDF5 低水準関数を効果的に使用するには、https://www.hdfgroup.org で入手できる公式 HDF5 ドキュメンテーションを参照してください。

HDF5 関数構文の MATLAB 関数構文へのマップ

多くの場合、MATLAB 低水準 HDF5 関数の構文は、対応する HDF5 ライブラリ関数の構文と同じです。たとえば、以下に示すのは HDF5 ライブラリにおける関数 H5Fopen の関数シグネチャです。HDF5 関数シグネチャにおいて、hid_t と herr_t は、オブジェクト識別子やエラーステータスの値を表す数値を返す HDF5 タイプです。

hid_t H5Fopen(const char *name, unsigned flags, hid_t access_id) /* C syntax */

MATLAB では、HDF5 インターフェイスの各関数は MATLAB クラスのメソッドです。次に示すのは、対応する MATLAB 関数のシグネチャです。クラスのメソッドであるため、MATLAB 関数を呼び出すには、ドット表記を使用して H5F.open としなければなりません。この MATLAB 関数は HDF5 関数と同じ 3 つの引数、すなわち名前を含む文字ベクトル、フラグ引数用の HDF5 定義の定数、HDF5 プロパティリスト ID を受け取ります。プロパティリストを使用して、さまざまな HDF5 オブジェクトの特性を指定します。ここでは、これはファイルアクセスプロパティリストです。HDF5 ドキュメンテーションを参照して、特定の関数にどのような定数を使用できるかを確認してください。また、MATLAB では定数は文字ベクトルとして渡されることに注意してください。

file_id = H5F.open(name,flags,plist_id)

ただし、一部の関数では、MATLAB 関数シグネチャがそれに対応する HDF5 ライブラリ関数と異なっています。一般に、MATLAB 低水準 HDF5 関数を使用する際は、以下の相違点に注意してください。

HDF5 出力パラメーターが MATLAB の戻り値になる — 一部の HDF5 ライブラリ関数は、関数パラメーターを使用してデータを返します。MATLAB 関数では複数の値を返すことができるため、これらの出力パラメーターは戻り値となります。具体例で説明すると、HDF5 の関数 H5Dread では buf パラメーターにデータを返します。
```
herr_t H5Dread(hid_t dataset_id,
		  hid_t mem_type_id,
		  hid_t mem_space_id, 
		  hid_t file_space_id, 
		  hid_t xfer_plist_id, 
		  void * buf )   /* C syntax */
```
対応する MATLAB 関数では、出力パラメーター buf が戻り値に変更されます。また、MATLAB 関数では、非ゼロまたは負値の herr_t 戻り値は MATLAB エラーとなります。MATLAB try-catch ステートメントを使用してエラーに対処してください。
```
buf = H5D.read(dataset_id,
		  mem_type_id,
 	 	mem_space_id,
 	       file_space_id,
 		 plist_id)
```
文字列の長さパラメーターは不要 — 一部の HDF5 ライブラリ関数で文字列パラメーターの長さの指定に使用される長さパラメーターは、対応する MATLAB 関数では不要となります。たとえば、HDF5 ライブラリの関数 H5Aget_name にはバッファーが出力パラメーターとして、バッファーのサイズが入力パラメーターとして含まれています。
```
ssize_t H5Aget_name(hid_t attr_id,
                    size_t buf_size,
                    char *buf ) /* C syntax */
```
対応する MATLAB 関数では、出力パラメーター buf が戻り値に変更され、buf_size パラメーターは切り捨てられます。
```
buf = H5A.get_name(attr_id)
```
空配列を使用して NULL を指定 — HDF5 ライブラリ関数で NULL 値が受け取られる場合は常に、MATLAB 関数では空配列 ([]) が使用されます。たとえば、HDF5 ライブラリの関数 H5Pset_fill_value では、指定された埋め込み値の代わりに NULL 値を受け取ります。
```
herr_t H5Pset_fill_value(hid_t plist_id,
                         hid_t type_id,
                         const void *value ) /* C syntax */
```
対応する MATLAB 関数を使用する際は、NULL の代わりに空配列 ([]) を指定できます。
cell 配列を使用して複数の定数を指定 — HDF5 ライブラリの一部の関数では、定数の配列を指定する必要があります。たとえば、関数 H5Screate_simple でデータ領域内の次元を制限なしにできるよう指定するには、maxdims の次元に定数 H5S_UNLIMITED を使用します。MATLAB では定数が文字ベクトルとして渡されるため、同じ結果を得るには文字ベクトルの cell 配列を使用しなければなりません。次のコード部分では、文字ベクトルの cell 配列を使用してこのデータ領域の各次元にこの定数を指定する例を示します。
```
ds_id = H5S.create_simple(2,[3 4],{'H5S_UNLIMITED' 'H5S_UNLIMITED'}); 
```

HDF5 データ型と MATLAB データ型間のマップ

HDF5 低水準関数によって HDF5 ファイルからデータを読み取るとき、または HDF5 ファイルにデータを書き込むとき、この関数によって HDF5 データ型は MATLAB データ型に自動的にマッピングされます。

数字 (整数と浮動小数点数) や文字 (ASCII) に一般的に使用されるバイナリ形式のような atomic データ型の場合、MATLAB で同様の型がサポートされているため、マッピングは通常は簡単です。これらのマッピングのリストは、表HDF5 atomic データ型と MATLAB データ型のマッピングを参照してください。

HDF5 atomic データ型と MATLAB データ型のマッピング

HDF5 atomic データ型	MATLAB データ型
Bit-field	パックされた 8 ビット整数の配列
Float	64 ビット以下の場合は MATLAB の single 型および double 型
符号付きおよび符号なしの整数型	符号付きおよび符号なしの、等価な MATLAB 整数型
Opaque	`uint8` 値の配列
Reference	`uint8` 値の配列
String	MATLAB string 配列

1 つ以上の atomic データ型を構造体、多次元配列、可変長データ型 (1 次元配列) などに集めた場合のような composite データ型では、HDF5 データ型に関してマッピングが不明確となる場合があります。HDF5 では、各要素に単一の uint8 値を含む 5 行 5 列のデータセットは、uint8 値の 5 行 5 列の配列を含む 1 行 1 列のデータセットと区別されます。前者において、データセットには単一値の 25 の観測が含まれます。後者では、データセットには 25 の値の単一の観測が含まれます。MATLAB では、これらのデータセットはいずれも 5 行 5 列の行列で表されます。

使用するデータが複雑なデータセットである場合は、HDF5 データ型を直接作成して、必要なマッピングが行われるようにしてください。既定のマッピングのリストは、表HDF5 composite データ型と MATLAB データ型のマッピングを参照してください。関数 H5Dwrite を使用すると、ファイルにデータを書き込む際にデータ型を指定できます。詳細は、HDF5 データ型インターフェイスドキュメンテーションを参照してください。

HDF5 composite データ型と MATLAB データ型のマッピング

HDF5 composite データ型	MATLAB データ型
Array	含まれるデータ型の次元を拡張します。たとえば、HDF5 における整数の配列は、MATLAB では 2 次元の整数の配列にマッピングされます。
Compound	MATLAB 構造体。メモ: MATLAB で HDF5 データを表す構造体はすべてスカラーです。
Enumeration	それぞれに関連付けられた名前のある整数の配列
Variable Length	MATLAB 1 次元 cell 配列

データセットの次元のレポート

MATLAB の低水準 HDF5 関数では、MATLAB 高水準関数とは異なった方法でデータセットの次元とデータセットの形状がレポートされます。使いやすいように、MATLAB 高水準関数では、データセットの次元を MATLAB の列優先のインデックスと矛盾のない形でレポートします。HDF5 ライブラリとの一貫性をもたせ、入れ子のデータセットと複雑なデータ型にも対応できるようにするため、MATLAB 低水準関数では C 言語の行優先の方向性を使用して配列の次元をレポートします。

MATLAB 低水準関数を使用する HDF5 データセットへのデータの書き込み

ライブスクリプトを開く

この例では、MATLAB® の HDF5 低水準関数を使用して HDF5 ファイルにデータセットを書き込み、そのファイルからデータセットを読み取る方法を示します。

HDF5 ファイルに書き込むデータの 2 行 3 列の配列を作成します。

testdata = [1 3 5; 2 4 6];

my_file.h5 という名前の新しい HDF5 ファイルをシステムの temp フォルダーに作成します。MATLAB 関数 H5F.create を使用してファイルを作成します。この MATLAB 関数は、HDF5 関数の H5Fcreate に相当します。引数として、ファイルに割り当てる名前、ファイルへのアクセスのタイプ (この場合は 'H5F_ACC_TRUNC') およびファイル作成プロパティリストやファイルアクセスプロパティリストによって指定されるオプションの追加特性を指定します。この場合、これらのプロパティリストには既定値を使用します ('H5P_DEFAULT')。C 定数を MATLAB 関数に文字ベクトルとして渡します。

filename = fullfile(tempdir,'my_file.h5');
fileID = H5F.create(filename,'H5F_ACC_TRUNC','H5P_DEFAULT','H5P_DEFAULT');

H5F.create は、HDF5 ファイルに対応するファイル識別子を返します。

MATLAB 変数を格納するためにファイルにデータセットを作成します。HDF5 のプログラミングモデルでは、データセットのデータ型と次元 (データ領域) を別々のエンティティとして定義しなければなりません。まず、関数 H5T.copy を使用して、データセットで使用されるデータ型、この場合は double を指定します。この MATLAB 関数は、HDF5 関数の H5Tcopy に相当します。

datatypeID = H5T.copy('H5T_NATIVE_DOUBLE');

H5T.copy はデータ型識別子を返します。

H5S.create_simple を使用してデータ領域を作成します。これは HDF5 関数の H5Screate_simple に相当します。最初の入力 2 は、データ領域のランクです。2 番目の入力は、データセットの各次元のサイズを指定する配列です。HDF5 ではデータが行優先の順序で保存され、MATLAB 配列は列優先の順序で構成されているため、データのレイアウトを維持するには、H5Screate_simple を使用する前に次元範囲の順序付けを逆にする必要があります。この目的で fliplr を使用できます。

dims = size(testdata);
dataspaceID = H5S.create_simple(2,fliplr(dims),[]);

H5S.create_simple は、データ領域識別子 dataspaceID を返します。行優先の順序を使用する他のソフトウェア (HDF Group の H5DUMP など) では、データセットのサイズが 2 行 3 列ではなく 3 行 2 列で記録される可能性があります。

H5D.create を使用してデータセットを作成します。これは HDF5 関数の H5Dcreate に相当します。ファイル識別子、データセットに割り当てる名前、データ型識別子、データ領域識別子、およびデータセット作成プロパティリスト識別子を引数として指定します。'H5P_DEFAULT' は、既定のプロパティリスト設定を指定します。

dsetname = 'my_dataset';  
datasetID = H5D.create(fileID,dsetname,datatypeID,dataspaceID,'H5P_DEFAULT');

H5D.create は、データセット識別子 datasetID を返します。

H5D.write を使用してデータをデータセットに書き込みます。これは HDF5 関数の H5Dwrite に相当します。入力引数は、データセット識別子、メモリデータ型識別子、メモリ空間識別子、データ領域識別子、転送プロパティリスト識別子およびデータセットに書き込む MATLAB 変数の名前です。定数 'H5ML_DEFAULT' は、HDF5 データ型への自動マッピングを指定します。定数 'H5S_ALL' は、H5D.write に対して、すべてのデータをファイルに書き込むことを指示します。

H5D.write(datasetID,'H5ML_DEFAULT','H5S_ALL','H5S_ALL', ...
    'H5P_DEFAULT',testdata);

データセット、データ領域、データ型、およびファイルのオブジェクトを閉じます。これらの識別子は、MATLAB 関数内で使用された場合は、スコープ外になると自動的に閉じられます。

H5D.close(datasetID);
H5S.close(dataspaceID);
H5T.close(datatypeID);
H5F.close(fileID);

書き込んだデータセットを読み取るために、HDF5 ファイルを開きます。H5F.open を使用してファイルを読み取り専用アクセスで開きます。この MATLAB 関数は、HDF5 関数の H5Fopen に相当します。

fileID = H5F.open(filename,'H5F_ACC_RDONLY','H5P_DEFAULT');

H5D.open を使用して、読み取るデータセットを開きます。これは HDF5 関数の H5Dopen に相当します。ファイル識別子および先に例で定義したデータセット名を、引数として指定します。

datasetID = H5D.open(fileID,dsetname);

H5D.read を使用して、データを MATLAB ワークスペースに読み取ります。これは HDF5 関数の H5Dread に相当します。入力引数は、データセット識別子、メモリデータ型識別子、メモリ空間識別子、データ領域識別子および転送プロパティリスト識別子です。

returned_data = H5D.read(datasetID,'H5ML_DEFAULT', ...
    'H5S_ALL','H5S_ALL','H5P_DEFAULT');

元の MATLAB 変数 testdata を、作成したばかりの変数 returned_data と比較します。

isequal(testdata,returned_data)

ans = logical
   1

2 つの変数は同じです。

大規模なデータセットの書き込み

大規模なデータセットを書き込むには、HDF5 ライブラリのチャンク化機能を使用しなければなりません。プロパティリストを作成し、関数 H5P.set_chunk を使用してプロパティリストにチャンクのサイズを設定します。データセットの次元が [2^16 2^16] で、チャンクサイズが 1,024 行 1,024 列だとします。データセット作成関数 H5D.create に、H5P_DEFAULT 値の代わりにプロパティリストを、最後の引数として渡します。

dims = [2^16 2^16];
plistID = H5P.create('H5P_DATASET_CREATE'); % create property list

chunk_size = min([1024 1024], dims); % define chunk size 
H5P.set_chunk(plistID, fliplr(chunk_size)); % set chunk size in property list

datasetID = H5D.create(fileID, dsetname, datatypeID, dataspaceID, plistID);

データの正しいレイアウトの維持

以下のようなデータ領域を扱う関数を使用する場合は、データの正しいレイアウトを維持するために次元範囲を反転する必要があります。

H5D.set_extent
H5P.get_chunk
H5P.set_chunk
H5S.create_simple
H5S.get_simple_extent_dims
H5S.select_hyperslab
H5T.array_create
H5T.get_array_dims

動的に読み込まれるフィルターを使用した HDF5 データセットの書き込み

MATLAB では、動的に読み込まれるフィルターを使用した HDF5 データセットの読み取りと書き込みをサポートしています。The HDF Group の登録済みフィルターのリストは、The HDF Group の Web サイトの Filters に掲載されています。

サードパーティ製のフィルターを使用してデータセットを書き込むには、次の手順に従います。

HDF5 フィルタープラグインを共有ライブラリまたは DLL としてシステムにインストールします。
登録済みフィルターのリストから、フィルタープラグインに The HDF Group によって割り当てられた一意のフィルター識別子を取得します。
プラグインのローカルインストール場所を指すように HDF5_PLUGIN_PATH 環境変数を設定し、MATLAB を起動します。
- Windows^® の場合 — [システムのプロパティ]、[詳細設定]、[環境変数] を使用して環境変数を設定し、MATLAB を起動します。
- Linux^® および Mac の場合 — ターミナルから環境変数を設定し、同じターミナルから MATLAB を起動します。

これらの手順を完了すると、MATLAB の高水準または低水準の HDF5 関数を使用して、一意のフィルター識別子で指定されたサードパーティ製のフィルターを使用したデータセットの作成と書き込みが可能になります。詳細については、HDF5 Dynamically Loaded Filters を参照してください。

Linux ユーザーのみ: MATLAB HDF5 共有ライブラリを使用したフィルタープラグインのリビルド

R2021b 以降では、フィルタープラグインでコアの HDF5 ライブラリ関数へのコールバックを使用している場合、Linux ユーザーは付属の MATLAB HDF5 共有ライブラリ /matlab/bin/glnxa64/libhdf5.so.x.x.x を使用してプラグインをリビルドする必要があります。このバージョンの共有ライブラリを使用してプラグインをリビルドしないと、未定義の動作からクラッシュまで、何らかの問題が発生する可能性があります。詳細については、Build HDF5 Filter Plugins on Linux Using MATLAB HDF5 Shared Library or GNU Export Map を参照してください。