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

Запись числового массива в 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 константу для аргумента flags и 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 поддерживает аналогичные типы. Список этих отображений см. в таблице Mapping Between HDF5 Atomic Данных Types and Типов данных MATLAB.

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

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

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

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

Запись данных в HDF5 набор данных с помощью низкоуровневых функций MATLAB

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

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

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

Создайте новый файл HDF5 с именем my_file.h5 в папке system 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

Две переменные одинаковы.

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

Чтобы записать большой набор данных, необходимо использовать возможность chunking библиотеки 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); 

Сохраните правильное размещение своих данных

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