Экспорт в файлы HDF5

Панорама

Иерархический Формат данных, Версия 5, (HDF5) является машинно-независимым стандартом общего назначения для того, чтобы хранить научные данные в файлах, разработанных Национальным центром суперкомпьютерных приложений (NCSA). HDF5 используется широким спектром технических и научных полей, которые хотят стандартный способ хранить данные так, чтобы это могло быть совместно использовано. Для получения дополнительной информации о формате файла HDF5, считайте документацию HDF5, доступную на веб-сайте HDF (https://www.hdfgroup.org).

MATLAB® предоставляет два метода, чтобы экспортировать данные в файл HDF5:

  • Высокоуровневые функции, которые упрощают процесс экспортирования данных при работе с числовыми наборами данных

  • Низкоуровневые функции, которые обеспечивают интерфейс MATLAB к стандартным программам в библиотеке HDF5 C

Примечание

Для получения информации об экспорте в файлы HDF4, которые имеют отдельный и несовместимый формат, смотрите Экспорт в Файлы HDF4.

Используя Высокоуровневые функции HDF5 MATLAB, чтобы экспортировать данные

Самый легкий способ записать данные или метаданные от рабочего пространства MATLAB до файла HDF5 состоит в том, чтобы использовать эти высокоуровневые функции MATLAB.

Примечание

Можно использовать высокоуровневые функции только с числовыми данными. Чтобы записать нечисловые данные, необходимо использовать низкоуровневый интерфейс.

  • h5create — Создайте набор данных HDF5

  • h5write — Запишите данные к набору данных HDF5

  • h5writeatt — Запишите данные к атрибуту HDF5

Для получения дополнительной информации о том, как использовать эти функции, смотрите их страницы с описанием, которые включают примеры. Следующие разделы иллюстрируют некоторые сценарии общего использования.

Запись числового массива к набору данных HDF5

Этот пример создает массив и затем пишет массив в файл HDF5.

  1. Создайте переменную MATLAB в рабочей области. Этот пример создает массив 5 на 5 uint8 значения.

    testdata = uint8(magic(5))
  2. Создайте файл HDF5 и набор данных, с помощью h5create.

    h5create('my_example_file.h5', '/dataset1', size(testdata))
  3. Запишите данные в файл HDF5.

    h5write('my_example_file.h5', '/dataset1', testdata)

Используя низкоуровневые HDF5 функции MATLAB, чтобы экспортировать данные

MATLAB обеспечивает прямой доступ к десяткам функций в библиотеке HDF5 с низкоуровневыми функциями, которые соответствуют функциям в библиотеке HDF5. Таким образом можно получить доступ к функциям библиотеки HDF5 из MATLAB, таким как чтение и запись сложных типов данных и использование возможностей подмножества HDF5.

Библиотека HDF5 организует библиотечные функции в наборы, названные интерфейсами. Например, все стандартные программы, связанные с работой с файлами, такими как открытие и закрытие, находятся в интерфейсе H5F, где F обозначает файл. MATLAB организует низкоуровневые HDF5 функции в классы, которые соответствуют каждому интерфейсу HDF5. Например, функции MATLAB, которые соответствуют файловому интерфейсу HDF5 (H5F), находятся в @H5F папке класса.

Следующие разделы обеспечивают больше детали о том, как использовать низкоуровневые функции MATLAB HDF5.

Примечание

Этот раздел не описывает все функции библиотеки HDF5 или объясняет основные концепции программирования HDF5. Чтобы использовать низкоуровневые функции MATLAB HDF5 эффективно, обратитесь к официальной документации HDF5, доступной в https://www.hdfgroup.org.

Карта HDF5 Синтаксис функций к синтаксису функции MATLAB

В большинстве случаев синтаксис низкоуровневых HDF5 функций MATLAB совпадает с синтаксисом соответствующих библиотечных функций HDF5. Например, следующее является функциональной подписью H5Fopen функция в библиотеке HDF5. В подписях функции 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: вектор символов, содержащий имя, HDF5-заданную константу для аргумента флагов и ID списка свойств HDF5. Вы используете списки свойств, чтобы задать характеристики многих различных объектов HDF5. В этом случае это - список свойств доступа к файлу. Обратитесь к документации HDF5, чтобы видеть, какие константы могут использоваться с конкретной функцией и отметить, что в MATLAB константы передаются как векторы символов.

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

Существуют, однако, некоторые функции, где подпись функции MATLAB отличается, чем соответствующая библиотечная функция HDF5. Следующее описывает некоторые общие различия, которые необходимо иметь в виду при использовании низкоуровневых HDF5 функций MATLAB.

  • Выходные параметры 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. Например, H5Aget_name функция в библиотеке HDF5 включает буфер как выходной параметр и размер буфера как входной параметр.

    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 использует пустые массивы ([]). Например, H5Dfill функция в библиотеке HDF5 принимает значение NULL вместо заданного значения заливки.

    herr_t H5Dfill(const void *fill,
                   hid_t fill_type_id, void *buf, 
                   hid_t buf_type_id, 
                   hid_t space_id ) /* C syntax */

    При использовании соответствующей функции MATLAB можно задать пустой массив ([]) вместо NULL.

  • Используйте массивы ячеек, чтобы задать несколько констант — Некоторые функции в библиотеке HDF5 требуют, чтобы вы задали массив констант. Например, в H5Screate_simple функция, чтобы указать, что размерность в пространстве данных может быть неограниченной, вы используете постоянный H5S_UNLIMITED для размерности в maxdims. В MATLAB, потому что вы передаете константы как векторы символов, необходимо использовать массив ячеек из символьных векторов, чтобы достигнуть того же результата. Следующий фрагмент кода обеспечивает пример использования массива ячеек из символьных векторов, чтобы задать эту константу для каждой размерности этого пространства данных.

    ds_id = H5S.create_simple(2,[3 4],{'H5S_UNLIMITED' 'H5S_UNLIMITED'}); 
    

Отображение между типами данных HDF5 и типами данных MATLAB

Когда низкоуровневые функции HDF5 считывают данные из файла HDF5 или записывают данные к файлу HDF5, типам данных карты HDF5 функций к типам данных MATLAB автоматически.

Для атомарных типов данных, таких как обычно используемые двоичные форматы для чисел (целые числа и плавающая точка) и символы (ASCII), отображение является обычно прямым, потому что MATLAB поддерживает подобные типы. См. таблицу Mapping Between HDF5 Atomic Data Types и MATLAB Data Types для списка этих отображений.

Отображение между атомарными типами данных HDF5 и типами данных MATLAB

HDF5 атомарный тип данныхТип данных MATLAB
Битовое полеМассив упакованных 8-битных целых чисел
ПлаваниеОдин и двойные типы MATLAB, при условии, что они занимают 64 бита или меньше
Целочисленные типы, подписанные и без знакаЭквивалентные целочисленные типы MATLAB, подписанные и без знака
НепрозрачныйМассив uint8 значения
СсылкаМассив uint8 значения
СтрокаСимвольные массивы MATLAB

Для составных типов данных, таких как агрегации одного или нескольких атомарных типов данных в структуры, многомерные массивы и типы данных переменной длины (одномерные массивы), отображение иногда неоднозначно со ссылкой на тип данных HDF5. В HDF5, набор данных 5 на 5, содержащий один uint8 значение в каждом элементе отлично от набора данных 1 на 1, содержащего массив 5 на 5 uint8 значения. В первом случае набор данных содержит 25 наблюдений за одним значением. Во втором случае набор данных содержит одно наблюдение с 25 значениями. В MATLAB оба из этих наборов данных представлены матрицей 5 на 5.

Если ваши данные являются набором комплексных данных, вы можете должны быть создать типы данных HDF5 непосредственно, чтобы убедиться, что у вас есть отображение, вы предназначаете. См. таблицу Mapping Between HDF5 Composite Data Types и MATLAB Data Types для списка отображений по умолчанию. Можно задать тип данных, когда вы записываете данные к файлу с помощью H5Dwrite функция. Смотрите, что тип данных HDF5 соединяет интерфейсом с документацией для получения дополнительной информации.

Отображение между типами данных составного объекта HDF5 и типами данных MATLAB

Тип данных составного объекта HDF5Тип данных MATLAB
МассивРасширяет размерность типа данных, который она содержит. Например, массив целых чисел в HDF5 сопоставил бы на двумерную матрицу целых чисел в MATLAB.
Составной объектСтруктура MATLAB. Примечание: Все структуры, представляющие данные HDF5 в MATLAB, являются скаляром.
ПеречислениеМассив целых чисел, которые у каждого есть связанное имя
Переменная длинаMATLAB 1D массивы ячеек

Создание отчетов о размерностях набора данных

Низкоуровневые HDF5 функции MATLAB сообщают о размерностях набора данных и форме наборов данных по-другому, чем высокоуровневые функции MATLAB. Для простоты использования высокоуровневые функции MATLAB сообщают о размерностях набора данных, сопоставимых с MATLAB упорядоченная по столбцам индексация. Чтобы быть сопоставимыми с библиотекой HDF5 и поддержать возможность вложенных наборов данных и сложных типов данных, низкоуровневые функции MATLAB сообщают об измерениях массива с помощью упорядоченной по строкам ориентации C.

Запись данных к набору данных HDF5 Используя низкоуровневые функции MATLAB

В этом примере показано, как использовать низкоуровневые функции MATLAB® HDF5, чтобы записать набор данных в файл HDF5 и затем считать набор данных из файла.

Создайте массив 2х3 данных, чтобы записать в файл HDF5.

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

Создайте новый файл с именем HDF5 my_file.h5 в системной папке временного файла. Используйте H5F.create MATLAB функция, чтобы создать файл. Эта функция 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, ранг пространства данных. Второй вход является массивом, задающим размер каждой размерности набора данных. Поскольку HDF5 хранит данные в упорядоченном по строкам порядке, и массив MATLAB организован в порядке развертывания по столбцам, необходимо инвертировать упорядоченное расположение степеней размерности перед использованием H5Screate_simple сохранить размещение данных. Можно использовать fliplr с этой целью.

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

H5S.create_simple возвращает идентификатор пространства данных, dataspaceID. Обратите внимание на то, что другие программы, которые используют упорядоченное по строкам упорядоченное расположение (такое как H5DUMP от HDF Group), может сообщить размер набора данных быть 3 2 вместо 2 3.

Создайте набор данных с помощью 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);

Считайте данные в рабочее пространство MATLAB с помощью H5D.read, который соответствует функции 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

Эти две переменные являются тем же самым.

Запись большого набора данных

Чтобы записать большой набор данных, необходимо использовать большую возможность библиотеки HDF5. Для этого создайте список свойств и используйте H5P.set_chunk функционируйте, чтобы установить размер фрагмента в списке свойств. Предположим, что размерностями вашего набора данных является [2^16 2^16] и размер фрагмента 1024 1024. Вы затем передаете список свойств в качестве последнего аргумента к функции создания набора данных, 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

Для просмотра документации необходимо авторизоваться на сайте