Data types¶

zarr-matlab supports every Zarr v3 core data type plus the numpy extension types written by zarr-python.

Zarr data type	MATLAB type	Notes
`bool`	`logical`
`int8` … `int64`, `uint8` … `uint64`	same-named integer
`float32` / `float64`	`single` / `double`
`float16`	`single`	converted losslessly on read; rounds to-nearest-even on write
`complex64` / `complex128`	`single` / `double` complex
`string`	`string` array	variable-length UTF-8 (`vlen-utf8` codec)
`variable_length_bytes`	cell of `uint8` row vectors	`vlen-bytes` codec; create with `"bytes"`
`numpy.datetime64` / `numpy.timedelta64`	`int64` ticks	see below

zarr.create accepts either MATLAB class names ("double", "logical") or Zarr names ("float64", "bool").

store = zarr.stores.MemoryStore();

zc = zarr.create(store, 4, "complex128", Path="c");
zc(:) = [1+2i; 3-4i; complex(NaN, Inf); 0];
v = zc(:);
assert(v(2) == 3-4i && isnan(real(v(3))))

zh = zarr.create(store, 3, "float16", Path="h");
zh(:) = single([1.5; -2; 0.099976]);
assert(isa(zh(:), 'single'))

Strings¶

string arrays map to the Zarr string dtype with the vlen-utf8 codec — fully compatible with zarr-python string arrays, including empty strings and non-ASCII text. Compression codecs stack on top as usual.

labels = zarr.create(store, [2 2], "string", Path="labels", ...
    ChunkShape=[2 2], Codecs={zarr.codecs.GzipCodec(5)}, FillValue="?");
labels(1, :) = ["alpha" "beta"];
out = labels(:, :);
assert(out(1, 2) == "beta" && out(2, 1) == "?")

Raw byte strings use the "bytes" dtype and cell arrays of uint8:

raw = zarr.create(store, 3, "bytes", Path="raw");
raw(:) = {uint8([1 2 3]); uint8.empty(1, 0); uint8(255)};
out = raw(:);
assert(isequal(out{1}, uint8([1 2 3])) && isempty(out{2}))

Datetimes: exact by design¶

zarr-python (and pandas/xarray) commonly write numpy.datetime64[ns]. MATLAB's datetime stores milliseconds as a double, which cannot represent nanosecond timestamps exactly — a silent-corruption trap. zarr-matlab therefore exposes these types as exact int64 ticks, with the unit available in the metadata:

t = zarr.create(store, 4, "datetime64[ns]", Path="t");   % fill = NaT (intmin)
t(1) = int64(0);                                         % ns since epoch
t(2) = int64(1700000000123456789);                       % exact (scalar literal)
t(3) = int64(-1);
v = t(:);
assert(v(2) == int64(1700000000123456789))               % exact
assert(v(4) == intmin('int64'))                          % NaT
disp(t.meta.dataTypeConfig.unit)                         % "ns"

Convert to MATLAB datetime when (sub-microsecond) precision loss is acceptable:

dt = datetime(1970, 1, 1) + seconds(double(v(2)) * 1e-9);
assert(year(dt) == 2023)

timedelta64 works identically ("timedelta64[ms]" etc.); NaT is intmin('int64') in both.