h5write

Write data to HDF5 dataset

Syntax

h5write(filename,ds,data)

h5write(filename,ds,data,start,count)

h5write(filename,ds,data,start,count,stride)

Description

h5write(filename,ds,data) writes data to an entire dataset, ds, in the specified HDF5 file. If the dataset is fixed in size, the amount of data to be written must match the size of the dataset.

h5write(filename,ds,data,start,count) writes a subset of data to a dataset, beginning at starting location start, and continuing for count elements. In a multidimensional dataset, count specifies a distance in each direction. h5write extends an extendable dataset along any unlimited dimensions, if necessary.

h5write(filename,ds,data,start,count,stride) specifies the spacing between elements, stride, along each dimension of the dataset.

Examples

Write to Entire Dataset

Create a 10-by-20 dataset named DS1.

h5create("myfile.h5","/DS1",[10 20])

Write a 10-by-20 array of random numbers to the dataset. Since the dimensions of DS1 are fixed, the amount of data to be written to it must match its size.

mydata = rand(10,20);
h5write("myfile.h5","/DS1",mydata)

Display the contents of the file.

h5disp("myfile.h5")

HDF5 myfile.h5 
Group '/' 
    Dataset 'DS1' 
        Size:  10x20
        MaxSize:  10x20
        Datatype:   H5T_IEEE_F64LE (double)
        ChunkSize:  []
        Filters:  none
        FillValue:  0.000000

Write to Block of Dataset

Create a 10-by-20 dataset named DS2.

h5create("myfile.h5","/DS2",[10 20])

Write a 5-by-7 subset of data to the last 5-by-7 block of the dataset. Specify count as [5 7] to match the size of the data you are writing. Specify start as [6 14], because moving count cells from this starting point will end in the last element of the dataset.

mydata = rand(5,7);
h5write("myfile.h5","/DS2",mydata,[6 14],[5 7])

Write Data to Unlimited Dataset

Write data to a dataset that has an unlimited dimension.

Create a dataset that is unlimited along the second dimension. ChunkSize must be specified to set any dimension of the dataset to Inf.

h5create("myfile.h5","/g2/DS2",[20 Inf],"Chunksize",[5 5]);

Write a 3-by-3 block of data to "/g2/DS2". Begin at the starting point [3 2] and write to the end of the block. You can write data of any size along the second dimension of the dataset, since it is unlimited.

data = rand(3);
start = [3 2];
count = [3 3];
h5write("myfile.h5","/g2/DS2",data,start,count);

Read all of the data from the dataset.

h5read("myfile.h5","/g2/DS2")

ans = 20×4

         0         0         0         0
         0         0         0         0
         0    0.8147    0.9134    0.2785
         0    0.9058    0.6324    0.5469
         0    0.1270    0.0975    0.9575
         0         0         0         0
         0         0         0         0
         0         0         0         0
         0         0         0         0
         0         0         0         0
      ⋮

Input Arguments

filename — Filename

string scalar | character vector

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	Specify the name of the file in filename. Example: "myFile.h5"
Other folders	If the file is not in the current folder or in a folder on the MATLAB® path, then specify the full or relative path in filename. Example: "C:\myFolder\myFile.h5" Example: "myFolder\myFile.h5"
Remote location	If the file is stored at a remote location, then filename 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™ s3 Windows Azure® Blob Storage wasb, wasbs For 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. For example, to use the Family driver with the two files family0.h5 and family1.h5, 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. 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, and multi-s.h5, specify filename as "multi".

ds — Dataset name

string scalar | character vector

Dataset name, specified as a string scalar or character vector containing the name of an existing dataset in the HDF5 file.

data — Data

numeric matrix | MATLAB string array

Data to be written to the HDF5 file. If a numeric datatype was specified in the corresponding call to h5create, then data is a numeric matrix containing floating-point or integer data. Data must be non sparse, and must be the same size as the HDF5 dataset if you do not specify start or count. If a dimension in the dataset is unlimited, then the data to be written can be any size along that dimension.

If "string" was specified as the datatype in the corresponding call to h5create, data is a MATLAB string array. The string array dimensions must match those specified in the call to h5create.

start — Start location

vector of ones (default) | numeric vector

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 of start correspond, in order, to the dataset dimensions. If any dimension of ds is unlimited, you must specify start.

If you do not specify start, then the h5write function starts writing to the dataset from the first index along each dimension.

count — Number of elements

vector of Infs (default) | numeric vector

Number of elements to write, 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 write to the dataset along each dimension. The elements of count correspond, in order, to the dataset dimensions. If any dimension of ds is unlimited, you must specify count.

stride — Spacing between elements

vector of ones (default) | numeric vector

Spacing between elements along each dimension of the dataset, specified as a numeric vector of integers. For an n-dimensional dataset, stride is a vector of length n. The elements of the stride vector correspond, in order, to the dataset dimensions. A value of 1 writes without skipping elements in the corresponding dimension, a value of 2 writes every other element, and so on.

If you do not specify stride, then the h5write function writes data without skipping along each dimension.

Limitations

• h5write does not support writing to files stored remotely in HDFS™.

Version History

Introduced in R2011a

R2020b: Write data to HDF5 files at a remote location

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

R2020b: Write data to HDF5 files with Unicode names

You can write data to HDF5 files whose names are encoded as Unicode characters.

R2020a: UTF-8 character encoding is the default setting

UTF-8 is now the default character encoding for h5write so that all Unicode code points can be represented in HDF5 files. Previously, the default encoding was ASCII.