HDF5 ファイルのインポート

いくつかの方法で HDF5 ファイルからデータを読み取ることができます。プログラムによって行う場合は、MATLAB® の高水準の HDF5 関数、または低水準関数の HDF5 ライブラリの名前空間を使用できます。対話的に行う場合は、[データのインポート] ライブ エディター タスクまたはインポート ツール アプリ (MATLAB Online™ 内) を使用できます。

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

メモ

形式に互換性がなく、まったく異なる HDF4 ファイルのインポートの詳細については、高水準関数による HDF4 ファイルのインポートを参照してください。

高水準 HDF5 関数を使用したデータのインポート

MATLAB には、HDF5 ファイルの内容を調べ、そのファイルから MATLAB ワークスペースにデータをインポートするために使用できるいくつかの関数が備わっています。

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

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

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

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

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

HDF5 ファイルの内容の確認

HDF5 ファイルには "属性" と呼ばれるデータとメタデータを含めることができます。HDF5 ファイルでは、UNIX® ファイル システムのような階層構造にデータとメタデータが整理されます。

HDF5 ファイルにおいて、階層内のディレクトリは "グループ" と呼ばれます。グループには他のグループ、データセット、属性、リンク、およびデータ型を含めることができます。データセットは、多次元数値配列や文字列のようなデータの集まりです。属性は、データセットなど、他のエンティティと関連付けられている任意のデータです。リンクは、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'
                    Target:  'somevalue'
    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 = 

  struct with fields:

      Filename: 'matlabroot\matlab\toolbox\matlab\demos\example.h5'
          Name: '/'
        Groups: [4×1 struct]
      Datasets: []
     Datatypes: []
         Links: []
    Attributes: [2×1 struct]

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

level2 = info.Groups(2)

level2 = 

  struct with fields:

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

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

Schematic showing structure of HDF5 data in example.h5

名前、次元、データ型など、データセットの情報を取得するには、Datasets フィールドに返された構造体のいずれかに注目します。

dataset1 = level2.Datasets(1)

dataset1 = 

  struct with fields:

          Name: 'dset2.1'
      Datatype: [1×1 struct]
     Dataspace: [1×1 struct]
     ChunkSize: []
     FillValue: []
       Filters: []
    Attributes: []

HDF5 ファイルからのデータのインポート

HDF5 ファイルからデータまたはメタデータを読み取るには、関数 h5read を使用します。引数として HDF5 ファイルの名前とデータセットの名前を指定します。(属性の値を読み取るには h5readatt を使用しなければなりません。)

説明のために、この例ではデータセット /g2/dset2.1 を HDF5 サンプル ファイル example.h5 から読み取ります。

data = h5read("example.h5","/g2/dset2.1")

data =

  10×1 single column vector

    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 の出力

Bitfield

パックされた 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 ではこれが string 配列として返されます。

s = h5read("example.h5","/g3/string")

s = 

  2×1 string array

    "ab "
    "de "

Compound データ型は常に構造体として返されます。データセットの次元は構造体のフィールドで表されます。たとえば、データセット /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 ではこれが構造体として返されます。

data = h5read("example.h5","/g3/compound2D")

data = 

  struct with fields:

    a: [2×3 int8]
    b: [2×3 double]

低水準 HDF5 関数を使用したデータのインポート

MATLAB には、HDF5 ライブラリの関数に対応する低水準関数が備わっており、HDF5 ライブラリの多くの関数に直接アクセスできます。この方法により、HDF5 のサブセット化機能の使用や複素数データ型の書き込みなど、HDF5 ライブラリの機能に MATLAB からアクセスできます。詳細は、MATLAB の低水準 HDF5 関数を使用したデータのエクスポートを参照してください。

HDF5 ファイルからのデータの対話的な読み取り

ライブ スクリプトを開く

この例では、[データのインポート] タスクを使用して HDF5 ファイルの構造を調べ、ファイルからデータをインポートしてから、データを解析して可視化する方法を示します。

データの探索とインポート

この例に付属している HDF5 ファイルには、NASA の降水処理システム (PPS) が提供する降水確率推定の swath が含まれています。

[ライブ エディター] タブで [タスク]、[データのインポート] を選択して、ライブ エディターで [データのインポート] タスクを開きます。[ファイル] フィールドに、HDF5 ファイルの名前 nasa_pps.h5 を入力します。タスクを使用して、グループ、データセット、および属性を含むデータの構造を探索します。このファイルには、3 つのデータセットを含むグループ S1 が含まれています。probabilityOfPrecip データセットには特定の場所における降水確率の推定値が含まれており、Latitude データセットと Longitude データセットにはこれらの確率推定の場所が含まれています。probabilityOfPrecip データセットの属性には units が含まれ、その値は 'percent' です。

3 つのデータセットからデータと属性を選択してインポートします。

2023-12-07_09-19-16.png

このタスクにより生成されるコードを確認するには、タスク パラメーター エリアの下部にある [コードの表示] をクリックしてタスクの表示を展開します。

% Create a structure to store imported HDF5 data
nasa_pps = struct();

filename = "nasa_pps.h5";

nasa_pps.Groups(1).Name = "S1";

nasa_pps.Groups(1).Datasets(1).Name = "Latitude";
nasa_pps.Groups(1).Datasets(1).Value = h5read(filename, "/S1/Latitude");

nasa_pps.Groups(1).Datasets(2).Name = "Longitude";
nasa_pps.Groups(1).Datasets(2).Value = h5read(filename, "/S1/Longitude");

nasa_pps.Groups(1).Datasets(3).Name = "probabilityOfPrecip";
nasa_pps.Groups(1).Datasets(3).Value = h5read(filename, "/S1/probabilityOfPrecip");

nasa_pps.Groups(1).Datasets(1).Attributes(1).Name = "units";
nasa_pps.Groups(1).Datasets(1).Attributes(1).Value = h5readatt(filename, "/S1/Latitude", "units");

nasa_pps.Groups(1).Datasets(1).Attributes(2).Name = "DimensionNames";
nasa_pps.Groups(1).Datasets(1).Attributes(2).Value = h5readatt(filename, "/S1/Latitude", "DimensionNames");

nasa_pps.Groups(1).Datasets(1).Attributes(3).Name = "Units";
nasa_pps.Groups(1).Datasets(1).Attributes(3).Value = h5readatt(filename, "/S1/Latitude", "Units");

nasa_pps.Groups(1).Datasets(1).Attributes(4).Name = "_FillValue";
nasa_pps.Groups(1).Datasets(1).Attributes(4).Value = h5readatt(filename, "/S1/Latitude", "_FillValue");

nasa_pps.Groups(1).Datasets(1).Attributes(5).Name = "CodeMissingValue";
nasa_pps.Groups(1).Datasets(1).Attributes(5).Value = h5readatt(filename, "/S1/Latitude", "CodeMissingValue");

nasa_pps.Groups(1).Datasets(2).Attributes(1).Name = "units";
nasa_pps.Groups(1).Datasets(2).Attributes(1).Value = h5readatt(filename, "/S1/Longitude", "units");

nasa_pps.Groups(1).Datasets(2).Attributes(2).Name = "DimensionNames";
nasa_pps.Groups(1).Datasets(2).Attributes(2).Value = h5readatt(filename, "/S1/Longitude", "DimensionNames");

nasa_pps.Groups(1).Datasets(2).Attributes(3).Name = "Units";
nasa_pps.Groups(1).Datasets(2).Attributes(3).Value = h5readatt(filename, "/S1/Longitude", "Units");

nasa_pps.Groups(1).Datasets(2).Attributes(4).Name = "_FillValue";
nasa_pps.Groups(1).Datasets(2).Attributes(4).Value = h5readatt(filename, "/S1/Longitude", "_FillValue");

nasa_pps.Groups(1).Datasets(2).Attributes(5).Name = "CodeMissingValue";
nasa_pps.Groups(1).Datasets(2).Attributes(5).Value = h5readatt(filename, "/S1/Longitude", "CodeMissingValue");

nasa_pps.Groups(1).Datasets(3).Attributes(1).Name = "units";
nasa_pps.Groups(1).Datasets(3).Attributes(1).Value = h5readatt(filename, "/S1/probabilityOfPrecip", "units");

nasa_pps.Groups(1).Datasets(3).Attributes(2).Name = "_FillValue";
nasa_pps.Groups(1).Datasets(3).Attributes(2).Value = h5readatt(filename, "/S1/probabilityOfPrecip", "_FillValue");

nasa_pps.Groups(1).Datasets(3).Attributes(3).Name = "DimensionNames";
nasa_pps.Groups(1).Datasets(3).Attributes(3).Value = h5readatt(filename, "/S1/probabilityOfPrecip", "DimensionNames");

nasa_pps.Groups(1).Datasets(3).Attributes(4).Name = "CodeMissingValue";
nasa_pps.Groups(1).Datasets(3).Attributes(4).Value = h5readatt(filename, "/S1/probabilityOfPrecip", "CodeMissingValue");

nasa_pps.Groups(1).Datasets(3).Attributes(5).Name = "Units";
nasa_pps.Groups(1).Datasets(3).Attributes(5).Value = h5readatt(filename, "/S1/probabilityOfPrecip", "Units");

clear filename

データの整理と準備

コロン演算子 (:) を使用して、3 つのデータセットからデータを列ベクトルとして抽出します。

lats = nasa_pps.Groups.Datasets(1).Value(:);
lons = nasa_pps.Groups.Datasets(2).Value(:);
probs = nasa_pps.Groups.Datasets(3).Value(:);

プロットの準備としてデータをクリーンアップします。これらの 3 つのデータセットにおける有効なインデックスは、次の条件を満たします。

  • probs の値が区間 [0, 100] にある。

  • lats の値が区間 [–90, 90] にある。

  • lons の値が区間 [–180, 180] にある。

論理インデックス付けを使用して、3 つのデータセットにおける有効なインデックスの値のみを保持します。この手順により、無効な緯度と経度の値のほか、確率推定の無効なパーセント値が除外されます。

isValid = 0<=probs & probs<=100 & abs(lats)<=90 & abs(lons)<=180;

probs = probs(isValid);
lats = lats(isValid);
lons = lons(isValid);

データのプロット

データセット内の有効なデータの地理密度プロットを作成します。色が "暖色" であるほど降水確率が高くなります。

g = geodensityplot(lats,lons,probs,FaceColor="interp");
geobasemap grayland
geolimits([-80 80],[-180 -90])
title("Probability of Precipitation vs. Location")
colormap turbo

Figure contains an axes object with type geoaxes. The geoaxes object contains an object of type densityplot.

著作権表示

NASA の降水処理システムが提供する全球降水データ。NASA の Web サイト https://gpm.nasa.gov/data/directory から抜粋。

動的に読み込まれるフィルターを使用した 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 を参照してください。

参考

トピック