cf.Field.nc_set_dataset_chunksizes¶
- Field.nc_set_dataset_chunksizes(chunksizes, ignore=False, constructs=False, **filter_kwargs)[source]¶
Set the dataset chunking strategy.
Added in version (cfdm): 1.12.2.0
- Parameters:
- chunksizes:
None
orstr
orint
orfloat
ordict
or a sequence Set the chunking strategy for writing to a netCDF4 file. One of:
None
: No dataset chunking strategy has been defined. The chunking strategy will be determined at write time bycf.write
.'contiguous'
The data will be written to the file contiguously, i.e. no chunking.
-
The size in bytes of the dataset chunks. A floating point value is rounded down to the nearest integer, and a string represents a quantity of byte units. “Square-like” chunk shapes are preferred, maximising the amount of chunks that are completely filled with data values (see the
cf.write
dataset_chunks parameter for details). For instance a chunksize of 1024 bytes may be specified with any of1024
,1024.9
,'1024'
,'1024.9'
,'1024 B'
,'1 KiB'
,'0.0009765625 MiB'
, etc. Recognised byte units are (case insensitive):B
,KiB
,MiB
,GiB
,TiB
,PiB
,KB
,MB
,GB
,TB
, andPB
. Spaces in strings are optional. -
The maximum number of array elements in a chunk along each data axis, provided in the same order as the data axes. Values are automatically limited to the full size of their corresponding data axis, but the special values
None
or-1
may be used to indicate the full axis size. This chunking strategy may get automatically modified by methods that change the data shape (such asinsert_dimension
). -
The maximum number of array elements in a chunk along the axes specified by the dictionary keys. Integer values are automatically limited to the full size of their corresponding data axis, and the special values
None
or-1
may be used to indicate the full axis size. The chunk size for an unspecified axis defaults to an existing chunk size for that axis, if there is one, or else the axis size. This chunking strategy may get automatically modified by methods that change the data shape (such asinsert_dimension
).Each dictionary key,
k
, specifies the unique axis that would be identified byf.domain_axis(k, **filter_kwargs)
, and it is allowed to specify a domain axis that is not spanned by the data array. Seedomain_axis
for details.
- constructs:
dict
orbool
, optional Also apply the dataset chunking strategy of the field construct data to the applicable axes of selected metadata constructs. The chunking strategies of unselected metadata constructs are unchanged.
If constructs is a
dict
then the selected metadata constructs are those that would be returned byf.constructs.filter(**constructs, filter_by_data=True)
. Note that an empty dictionary will therefore select all metadata constructs that have data. Seefilter
for details.For constructs being anything other than a dictionary, if it evaluates to True then all metadata constructs that have data are selected, and if it evaluates to False (the default) then no metadata constructs selected.
- ignore:
bool
, optional If True and chunksizes is a
dict
then ignore any dictionary keys that do not identify a unique axis of the field construct’s data. If False, the default, then an exception will be raised when such keys are encountered.- filter_kwargs: optional
When chunksizes is a
dict
, provide additional keyword arguments todomain_axis
to customise axis selection criteria.
- chunksizes:
- Returns:
Examples
>>> f = cf.example_field(0) >>> print(f) Field: specific_humidity (ncvar%q) ---------------------------------- Data : specific_humidity(latitude(5), longitude(8)) 1 Cell methods : area: mean Dimension coords: latitude(5) = [-75.0, ..., 75.0] degrees_north : longitude(8) = [22.5, ..., 337.5] degrees_east : time(1) = [2019-01-01 00:00:00] >>> f.shape (5, 8) >>> print(f.nc_dataset_chunksizes()) None >>> f.nc_set_dataset_chunksizes({'latitude': 1}) >>> f.nc_dataset_chunksizes() (1, 8) >>> f.nc_set_dataset_chunksizes({'longitude': 7}) >>> f.nc_dataset_chunksizes() (1, 7) >>> f.nc_set_dataset_chunksizes({'latitude': 4, 'longitude': 2}) >>> f.nc_dataset_chunksizes() (4, 2) >>> f.nc_set_dataset_chunksizes([1, 7]) >>> f.nc_dataset_chunksizes() (1, 7) >>> f.nc_set_dataset_chunksizes(64) >>> f.nc_dataset_chunksizes() 64 >>> f.nc_set_dataset_chunksizes('128 B') >>> f.nc_dataset_chunksizes() 128 >>> f.nc_set_dataset_chunksizes('contiguous') >>> f.nc_dataset_chunksizes() 'contiguous' >>> f.nc_set_dataset_chunksizes(None) >>> print(f.nc_dataset_chunksizes()) None
>>> f.nc_set_dataset_chunksizes([-1, None]) >>> f.nc_dataset_chunksizes() (5, 8) >>> f.nc_set_dataset_chunksizes({'latitude': 999}) >>> f.nc_dataset_chunksizes() (5, 8)
>>> f.nc_set_dataset_chunksizes({'latitude': 4, 'time': 1}) >>> f.nc_dataset_chunksizes() (4, 8) >>> print(f.dimension_coordinate('time').nc_dataset_chunksizes()) None >>> print(f.dimension_coordinate('latitude').nc_dataset_chunksizes()) None >>> print(f.dimension_coordinate('longitude').nc_dataset_chunksizes()) None
>>> f.nc_set_dataset_chunksizes({'latitude': 4, 'time': 1}, constructs=True) >>> f.dimension_coordinate('time').nc_dataset_chunksizes() (1,) >>> f.dimension_coordinate('latitude').nc_dataset_chunksizes() (4,) >>> f.dimension_coordinate('longitude').nc_dataset_chunksizes() (8,) >>> f.nc_set_dataset_chunksizes('contiguous', constructs={'filter_by_axis': ('longitude',)}) >>> f.nc_dataset_chunksizes() 'contiguous' >>> f.dimension_coordinate('time').nc_dataset_chunksizes() (1,) >>> f.dimension_coordinate('latitude').nc_dataset_chunksizes() (4,) >>> f.dimension_coordinate('longitude').nc_dataset_chunksizes() 'contiguous'
>>> f.nc_set_dataset_chunksizes({'height': 19, 'latitude': 3}) Traceback ... ValueError: Can't find unique 'height' axis. Consider setting ignore=True >>> f.nc_set_dataset_chunksizes({'height': 19, 'latitude': 3}, ignore=True) >>> f.nc_dataset_chunksizes(todict=True) {'time': 1, 'latitude': 3, 'longitude': 8}