Документация

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

В этом примере создается массив, который затем записывается в файл HDF5.

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

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

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

Сопоставление типов данных HDF5 и типов данных MATLAB

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

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

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

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

Аналитика набора данных отчета

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

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

H5S.create_simple возвращает идентификатор пространства данных, dataspaceID. Обратите внимание, что другие программные программы, использующие упорядочение строк (например, H5DUMP из группы HDF) может сообщить размер набора данных как 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); 

Сохранение правильного макета данных

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