cf.FieldAncillary.HDF_chunks

FieldAncillary.HDF_chunks(*chunksizes)

Specify HDF5 chunks for the data array.

Chunking refers to a storage layout where the data array is partitioned into fixed-size multi-dimensional chunks when written to a netCDF4 file on disk. Chunking is ignored if the data array is written to a netCDF3 format file.

A chunk has the same rank as the data array, but with fewer (or no more) elements along each axis. The chunk is defined by a dictionary in which the keys identify axes and the values are the chunk sizes for those axes.

If a given chunk size for an axis is larger than the axis size, then the size of the axis at the time of writing to disk will be used instead.

If chunk sizes have been specified for some but not all axes, then the each unspecified chunk size is assumed to be the full size of its axis.

If no chunk sizes have been set for any axes then the netCDF default chunk is used (http://www.unidata.ucar.edu/software/netcdf/docs/netcdf_perf_chunking.html).

A detailed discussion of HDF chunking and I/O performance is available at https://www.hdfgroup.org/HDF5/doc/H5.user/Chunking.html and http://www.unidata.ucar.edu/software/netcdf/workshops/2011/nc4chunking. Basically, you want the chunks for each dimension to match as closely as possible the size and shape of the data block that users will read from the file.

New in version 1.1.13.

Examples 1:

To define chunks which are the full size for each axis except for the first axis which is to have a chunk size of 12:

>>> old_chunks = f.HDF_chunks({0: 12})

Parameters:

chunksizes: dict or None, optional

Specify the chunk sizes for axes of the field ancillary. Axes are given by dictionary keys, with a chunk size for those axes as the dictionary values. A dictionary key may be an integer or a tuple of integers defining axes by position in the data array. In the special case of chunksizes being None, then chunking is set to the netCDF default.

Example:

To set the chunk size for first axes to 365: {0: 365}.

Example:

To set the chunk size for the first and third data array axes to 100: {0: 100, 2: 100}, or equivalently {(0, 2): 100}.

Example:

To set the chunk size for the second axis to 100 and for the third axis to 5: {1: 100, 2: 5}.

Example:

To set the chunking to the netCDF default: None.

Returns:

out: dict

The chunk sizes prior to the new setting, or the current current sizes if no new values are specified.