h5read - Read data from HDF5 dataset - MATLAB (original) (raw)

Read data from HDF5 dataset

Syntax

Description

data = h5read([filename](#bsvev%5F7-1%5Fsep%5Fmw%5Fe4513247-6fae-4c5b-a232-6f7a408596c0),[ds](#mw%5F9c41c823-2969-4855-a112-6be571bcb7fa)) reads all the data from the dataset ds contained in the HDF5 filefilename.

example

data = h5read([filename](#bsvev%5F7-1%5Fsep%5Fmw%5Fe4513247-6fae-4c5b-a232-6f7a408596c0),[ds](#mw%5F9c41c823-2969-4855-a112-6be571bcb7fa),[start](#mw%5F205027c6-55b6-49f3-a29d-b394d30a0ff4),[count](#mw%5F81bd7404-41be-4ab6-b990-5addedebf126)) reads a subset of data from the dataset beginning at the location specified instart. The count argument specifies the number of elements to read along each dimension.

example

data = h5read([filename](#bsvev%5F7-1%5Fsep%5Fmw%5Fe4513247-6fae-4c5b-a232-6f7a408596c0),[ds](#mw%5F9c41c823-2969-4855-a112-6be571bcb7fa),[start](#mw%5F205027c6-55b6-49f3-a29d-b394d30a0ff4),[count](#mw%5F81bd7404-41be-4ab6-b990-5addedebf126),[stride](#mw%5Fe88549c9-f572-40ee-a021-615b886b2cdc)) returns a subset of data with the interval between the indices of each dimension of the dataset specified by stride.

example

Examples

collapse all

Get the metadata for a dataset from the HDF5 file and then read the dataset.

Display the metadata for a dataset /g4/lat from the HDF5 file example.h5.

h5disp('example.h5','/g4/lat')

HDF5 example.h5 Dataset 'lat' Size: 19 MaxSize: 19 Datatype: H5T_IEEE_F64LE (double) ChunkSize: [] Filters: none FillValue: 0.000000 Attributes: 'units': 'degrees_north' 'CLASS': 'DIMENSION_SCALE' 'NAME': 'lat'

Read the dataset.

data = h5read('example.h5','/g4/lat')

data = 19×1

-90 -80 -70 -60 -50 -40 -30 -20 -10 0 10 20 30 40 50 ⋮

Get the metadata for a dataset from the HDF5 file and then read a subset of the dataset.

Display the metadata for a dataset /g4/world from the HDF5 file example.h5.

h5disp('example.h5','/g4/world')

HDF5 example.h5 Dataset 'world' Size: 36x19 MaxSize: 36x19 Datatype: H5T_IEEE_F64LE (double) ChunkSize: [] Filters: none FillValue: 0.000000

Starting from the beginning of data, read a 5-by-3 subset of the data from the dataset.

start = [1 1]; count = [5 3]; data = h5read('example.h5','/g4/world',start,count)

data = 5×3

 0     0     0
 0     0     0
 0     0     0
 0     0     0
 0     0     0

Read data from a dataset, where the data is sampled at a specified spacing between the dataset indices along each dimension.

First, display the metadata for a dataset /g4/lon from the HDF5 file example.h5. The variable in the dataset has one dimension with 36 elements.

h5disp('example.h5','/g4/lon')

HDF5 example.h5 Dataset 'lon' Size: 36 MaxSize: 36 Datatype: H5T_IEEE_F64LE (double) ChunkSize: [] Filters: none FillValue: 0.000000 Attributes: 'units': 'degrees_east' 'CLASS': 'DIMENSION_SCALE' 'NAME': 'lon'

Start reading from the location in startLoc and read variable data at intervals specified in stride. A value of 1 in stride accesses adjacent values in the corresponding dimension, whereas a value of 2 accesses every other value in the corresponding dimension, and so on.

startLoc = 1; count = 18; stride = 2; subsetData = h5read('example.h5','/g4/lon',startLoc,count,stride);

Examine the output variable subsetData.

Name Size Bytes Class Attributes

subsetData 18x1 144 double

Input Arguments

collapse all

Filename of an existing HDF5 file, specified as a string scalar or character vector.

Depending on the location of your file, filename can take one of these forms.

Location	Form
Current folder or folder on the MATLAB® path	If the file is in the current folder or in a folder on the MATLAB path, then specify the name of the file infilename.Example: "myFile.h5"
Other folders	If the file is neither in the current folder nor in a folder on the MATLAB path, then specify the full or relative path infilename.Example: "C:\myFolder\myFile.h5"Example: "myFolder\myFile.h5"
Uniform resource locator (URL) (since R2024b)	If the file is located by an internet URL, thenfilename must contain the protocol type, such as http://. For more information, see Work with Remote Data.Example: "http://my\_hostname/my\_path/my\_file.h5"
Remote location	If the file is stored at a remote location, thenfilename must contain the full path of the file specified as a uniform resource locator (URL) of the form:scheme_name://path_to_file/_filename_Based on your remote location,scheme_name can be one of the values in this table. Remote Location_scheme_name_Amazon S3™s3Windows Azure® Blob Storagewasb,wasbsHDFS™hdfsFor more information, see Work with Remote Data.Example: "s3://myBucket/myFolder/myFile.h5"

If your file consists of several physical files using the Family driver, specify filename using a format specifier. If these physical files are not in your current folder, then specify them using their full or relative path. For example, to use the Family driver with the two filesfamily0.h5 and family1.h5 in your current folder, specify filename as"family%d.h5".
If your file consists of several physical files using the Multi driver or the Split driver, specify filename as the leading prefix of the names of the physical files. If these physical files are not in your current folder, then specify them using their full or relative path. For example, to use the Multi driver with the six files multi-b.h5,multi-g.h5, multi-l.h5,multi-o.h5, multi-r.h5, andmulti-s.h5 in your current folder, specifyfilename as "multi".

Dataset name, specified as a character vector or string scalar containing the name of the dataset in the HDF5 file. An HDF5 dataset is a multidimensional array of data elements, together with supporting metadata.

Starting location, specified as a numeric vector of positive integers. For an_N_-dimensional dataset, start is a vector of length N containing 1-based indices. The elements ofstart correspond, in order, to the variable dimensions.

If you do not specify start, then the h5read function starts reading the dataset from the first index along each dimension.

Number of elements to read, specified as a numeric vector of positive integers. For an _N_-dimensional dataset, count is a vector of length N, specifying the number of elements to read along each dimension. The elements of count correspond, in order, to the variable dimensions. If any element of count isInf, then h5read reads until the end of the corresponding dimension.

If you do not specify count, then the h5read function reads data until the end of each dimension.

Space between the indices along each dimension of the dataset, specified as a numeric vector of integers. For an N-dimensional variable in the dataset, stride is a vector of lengthN. The elements of the stride vector correspond, in order, to the variable dimensions. A value of 1 accesses adjacent values of the variable in the corresponding dimension, a value of2 accesses every other value of the variable in the corresponding dimension, and so on.

If you do not specify stride, then the h5read function reads the data with a default spacing of 1 along each dimension.

Limitations

h5read does not support reading references to groups.
MATLAB does not support internet URLs that require authentication.
MATLAB Online™ supports internet URLs associated with Microsoft® OneDrive™ files and folders, while the installed version of MATLAB supports only local OneDrive files.
The h5read function issues an error for datasets that fail file integrity checks. To read data in such situations, use the H5P.set_relax_file_integrity_checks function and the low-level HDF5 interface. (since R2024b)

Version History

Introduced in R2011a

expand all

The h5read function now issues an error for datasets that fail file integrity checks. Previously, this function did not issue an error for such datasets. To read data in such situations, use the H5P.set_relax_file_integrity_checks function and the low-level HDF5 interface. This table shows how to update your code to use the low-level HDF5 interface.

R2024a and Earlier	Starting in R2024b
myData = h5read("myFilename.h5","myDatasetName");	fapl = H5P.create("H5P_FILE_ACCESS"); H5P.set_relax_file_integrity_checks(fapl,"H5F_RFIC_UNUSUAL_NUM_UNUSED_NUMERIC_BITS") fid = H5F.open("myFilename.h5","H5F_ACC_RDONLY",fapl); dset_id = H5D.open(fid,"myDatasetName"); myData = H5D.read(dset_id); H5D.close(dset_id) H5F.close(fid) H5P.close(fapl)

You can read data from HDF5 files stored in primary online sources by using theh5read function with an internet URL.

You can read data from HDF5 files in remote locations, such as Amazon S3, Windows Azure Blob Storage, and HDFS.

You can read data from HDF5 files whose names are encoded as Unicode characters.

h5read returns HDF5 string arrays as MATLAB string arrays rather than cell arrays of character vectors. Single (scalar) HDF5 strings are returned as MATLAB character vectors.