Main Content

このページの内容は最新ではありません。最新版の英語を参照するには、ここをクリックします。

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 ワークスペースにデータをインポートするために使用できるいくつかの関数が備わっています。

  • h5disp — HDF5 ファイルの内容を表示する。

  • h5info — HDF5 ファイルを定義するすべてのメタデータを含む構造体を作成する。

  • h5read — HDF5 ファイルの変数からデータを読み取る。

  • h5readatt — HDF5 ファイルの変数と関連付けられている属性、またはファイル自体と関連付けられている属性 (グローバル属性) からデータを読み取る

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

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 つの属性が含まれていることがわかります。DatasetsDatatypes、および Links の各フィールドはすべて空で、ルート グループにはデータセット、データ型、リンクが一切含まれてないことが示されています。HDF5 サンプル ファイルの内容をさらに調べるには、Groups の構造体のいずれかを確認します。次の例では、このフィールドの 2 番目の構造体の内容が示されています。

level2 = info.Groups(2)

level2 = 

          Name: '/g2'
        Groups: []
      Datasets: [2x1 struct]
     Datatypes: []
         Links: []
    Attributes: []

サンプル ファイルにおいて、/g2 という名前のグループには 2 つのデータセットが含まれています。次の図は、HDF5 サンプル ファイルの構成のこの部分を図解したものです。

Schematic showing structure of HDF5 data in example.h5

名前、次元、データ型など、データセットの情報を取得するには、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 ビット整数の配列
Float64 ビット以下の場合は MATLAB の single 型および double 型
符号付きおよび符号なしの整数型符号付きおよび符号なしの、等価な MATLAB 整数型
Opaqueuint8 値の cell 配列
参照参照の値ではなく、参照によってポイントされる実際のデータの cell 配列
固定長および可変長の文字列string 配列
Enums各列挙値がそれに対応するメンバー名で置き換えられた、文字ベクトルの cell 配列
Compound1 行 1 列の構造体配列。データ セットの次元は構造体のフィールドで表されます。
ArraysHDF5 配列と同じデータ型を使用した値の配列。たとえば、配列が 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 に掲載されています。

ユーザー定義のサードパーティ製のフィルターを使用して書き込まれたデータ セットを読み取るには、次の手順に従います。

  1. HDF5 フィルター プラグインを共有ライブラリまたは DLL としてシステムにインストールします。

  2. プラグインのローカル インストール場所を指すように 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 を参照してください。

関連するトピック