このページの内容は最新ではありません。最新版の英語を参照するには、ここをクリックします。
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 ライブラリのルーチンへのアクセスにより、インポート処理をさらに制御できるようにする低水準関数
メモ
互換性のない異なる形式の HDF4 ファイルへのインポートの詳細は、プログラムによる HDF4 ファイルのインポートを参照してください。
高水準 HDF5 関数を使用したデータのインポート
MATLAB には、HDF5 ファイルの内容を調べ、そのファイルから MATLAB ワークスペースにデータをインポートするために使用できるいくつかの関数が備わっています。
これらの関数の使用方法についての詳細は、例が記載された各リファレンス ページを参照してください。以下の節では、いくつかの一般的な用法シナリオについて説明します。
HDF5 ファイルの内容の確認
HDF5 ファイルには "属性 (Attribute)" と呼ばれるデータとメタデータを含めることができます。HDF5 ファイルでは、UNIX® ファイル システムのような階層構造にデータとメタデータが整理されます。
HDF5 ファイルにおいて、階層内のディレクトリは "グループ (Group)" と呼ばれます。グループには他のグループ、データセット、属性、リンク、およびデータ型を含めることができます。データセットは、多次元数値配列や文字列のようなデータの集まりです。属性は、データセットなど、他のエンティティと関連付けられている任意のデータです。リンクは、UNIX ファイル システムのシンボリック リンクと似ています。リンクは、オブジェクトのコピーを作らずにオブジェクトを参照する方法です。
データ型は、データセットまたは属性におけるデータの説明となります。データ型によってデータセット内のデータを解釈する方法がわかります。
HDF5 ファイルの内容を簡単に表示するには、関数 h5disp
を使用します。
h5disp('example.h5') HDF5 example.h5 Group '/' Attributes: 'attr1': 97 98 99 100 101 102 103 104 105 0 'attr2': 2x2 H5T_INTEGER Group '/g1' Group '/g1/g1.1' Dataset 'dset1.1.1' Size: 10x10 MaxSize: 10x10 Datatype: H5T_STD_I32BE (int32) ChunkSize: [] Filters: none Attributes: 'attr1': 49 115 116 32 97 116 116 114 105 ... 'attr2': 50 110 100 32 97 116 116 114 105 ... Dataset 'dset1.1.2' Size: 20 MaxSize: 20 Datatype: H5T_STD_I32BE (int32) ChunkSize: [] Filters: none Group '/g1/g1.2' Group '/g1/g1.2/g1.2.1' Link 'slink' Type: soft link Group '/g2' Dataset 'dset2.1' Size: 10 MaxSize: 10 Datatype: H5T_IEEE_F32BE (single) ChunkSize: [] Filters: none Dataset 'dset2.2' Size: 5x3 MaxSize: 5x3 Datatype: H5T_IEEE_F32BE (single) ChunkSize: [] Filters: none . . .
HDF5 ファイルの階層構成を調べるには、関数 h5info
を使用します。h5info
は、ファイル名など、HDF5 ファイルについてのさまざまな情報を含む構造体を返します。
info = h5info('example.h5') info = Filename: 'matlabroot\matlab\toolbox\matlab\demos\example.h5' Name: '/' Groups: [4x1 struct] Datasets: [] Datatypes: [] Links: [] Attributes: [2x1 struct]
Groups
および Attributes
のフィールドを見ると、ファイルには 4 つのグループと 2 つの属性が含まれていることがわかります。Datasets
、Datatypes
、および Links
の各フィールドはすべて空で、ルート グループにはデータセット、データ型、リンクが一切含まれてないことが示されています。HDF5 サンプル ファイルの内容をさらに調べるには、Groups
の構造体のいずれかを確認します。次の例では、このフィールドの 2 番目の構造体の内容が示されています。
level2 = info.Groups(2) level2 = Name: '/g2' Groups: [] Datasets: [2x1 struct] Datatypes: [] Links: [] Attributes: []
サンプル ファイルにおいて、/g2
という名前のグループには 2 つのデータセットが含まれています。次の図は、HDF5 サンプル ファイルの構成のこの部分を図解したものです。
名前、次元、データ型など、データセットの情報を取得するには、Datasets
フィールドに返された構造体のいずれかに注目します。
dataset1 = level2.Datasets(1) dataset1 = Filename: 'matlabroot\example.h5' Name: '/g2/dset2.1' Rank: 1 Datatype: [1x1 struct] Dims: 10 MaxDims: 10 Layout: 'contiguous' Attributes: [] Links: [] Chunksize: [] Fillvalue: []
HDF5 ファイルからのデータのインポート
HDF5 ファイルからデータまたはメタデータを読み取るには、関数 h5read
を使用します。引数として HDF5 ファイルの名前とデータセットの名前を指定します (属性の値を読み取るには h5readatt
を使用しなければなりません)。
説明のために、この例ではデータセット /g2/dset2.1
を HDF5 サンプル ファイル example.h5
から読み取ります。
data = h5read('example.h5','/g2/dset2.1') data = 1.0000 1.1000 1.2000 1.3000 1.4000 1.5000 1.6000 1.7000 1.8000 1.9000
HDF5 データ型の MATLAB データ型へのマッピング
関数 h5read
によって HDF5 ファイルのデータを MATLAB ワークスペースに読み取る際は、次の表に示すように、HDF5 データ型から MATLAB データ型へのマッピングが行われます。
HDF5 データ型 | h5read により返されるデータ型 |
---|---|
Bit-field | パックされた 8 ビット整数の配列 |
Float | 64 ビット以下の場合は MATLAB の single 型および double 型 |
符号付きおよび符号なしの整数型 | 符号付きおよび符号なしの、等価な MATLAB 整数型 |
Opaque | uint8 値の cell 配列 |
参照 | 参照の値ではなく、参照によってポイントされる実際のデータの cell 配列 |
固定長および可変長の文字列 | string 配列 |
Enums | 各列挙値がそれに対応するメンバー名で置き換えられた、文字ベクトルの cell 配列 |
Compound | 1 行 1 列の構造体配列。データ セットの次元は構造体のフィールドで表されます。 |
Arrays | HDF5 配列と同じデータ型を使用した値の配列。たとえば、配列が 32 ビットの符号付き整数からなる場合、MATLAB 配列は int32 型となります。 |
MATLAB に付属する HDF5 サンプル ファイルには、これらのデータ型すべての例が含まれています。
たとえば、データセット /g3/string
は文字列です。
h5disp('example.h5','/g3/string') HDF5 example.h5 Dataset 'string' Size: 2 MaxSize: 2 Datatype: H5T_STRING String Length: 3 Padding: H5T_STR_NULLTERM Character Set: H5T_CSET_ASCII Character Type: H5T_C_S1 ChunkSize: [] Filters: none FillValue: ''
ここで、ファイルからこのデータを読み取ると、MATLAB ではこれが文字ベクトルの cell 配列として返されます。
s = h5read('example.h5','/g3/string') s = 'ab ' 'de ' >> whos s Name Size Bytes Class Attributes s 2x1 236 cell
Compound データ型は常に 1 行 1 列の構造体として返されます。データ セットの次元は構造体のフィールドで表されます。たとえば、データ セット /g3/compound2D
は Compound データ型です。
h5disp('example.h5','/g3/compound2D') HDF5 example.h5 Dataset 'compound2D' Size: 2x3 MaxSize: 2x3 Datatype: H5T_COMPOUND Member 'a': H5T_STD_I8LE (int8) Member 'b': H5T_IEEE_F64LE (double) ChunkSize: [] Filters: none FillValue: H5T_COMPOUND
ここでファイルからこのデータを読み取ると、MATLAB ではこれを 1 行 1 列の構造体として返します。
data = h5read('example.h5','/g3/compound2D') data = a: [2x3 int8] b: [2x3 double]
低水準 HDF5 関数を使用したデータのインポート
MATLAB には、HDF5 ライブラリの関数に対応する "低水準" 関数が備わっており、HDF5 ライブラリの多くの関数に直接アクセスできます。この方法により、複素数データ型の読み取りと書き込みや HDF5 のサブセット化機能など、HDF5 ライブラリの機能に MATLAB からアクセスできます。詳細は、MATLAB の低水準 HDF5 関数を使用したデータのエクスポートを参照してください。
動的に読み込まれるフィルターを使用した HDF5 データ セットの読み取り
MATLAB では、動的に読み込まれるフィルターを使用した HDF5 データ セットの読み取りと書き込みをサポートしています。The HDF Group の登録済みフィルターのリストは、The HDF Group の Web サイトの Filters に掲載されています。
ユーザー定義のサードパーティ製のフィルターを使用して書き込まれたデータ セットを読み取るには、次の手順に従います。
HDF5 フィルター プラグインを共有ライブラリまたは DLL としてシステムにインストールします。
プラグインのローカル インストール場所を指すように
HDF5_PLUGIN_PATH
環境変数を設定し、MATLAB を起動します。Windows® の場合 — [システムのプロパティ]、[詳細設定]、[環境変数] を使用して環境変数を設定し、MATLAB を起動します。
Linux® および Mac の場合 — ターミナルから環境変数を設定し、同じターミナルから MATLAB を起動します。
これらの手順を完了すると、MATLAB の高水準または低水準の HDF5 関数を使用して、サードパーティ製のフィルターを使用して圧縮されたデータ セットの読み取りとアクセスが可能になります。詳細については、The HDF Group の Web サイトの 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 を参照してください。