cfdm.netcdf_flatten

cfdm.netcdf_flatten(input_ds, output_ds, strict=True, omit_data=False, write_chunksize=134217728)

Create a flattened version of a grouped netCDF dataset.

CF-netCDF coordinate variables

When a CF-netCDF coordinate variable in the input dataset is in a different group to its corresponding dimension, the same variable in the output flattened dataset will no longer be a CF-netCDF coordinate variable, as its name will be prefixed with a different group identifier than its dimension.

In such cases it is up to the user to apply the proximal and lateral search algorithms to the flattened dataset returned by netcdf_flatten, in conjunction with the mappings defined in the newly created global attributes _flattener_variable_map and _flattener_dimension_map, to find which netCDF variables are acting as CF coordinate variables in the flattened dataset. See https://cfconventions.org/cf-conventions/cf-conventions.html#groups for details.

For example, if an input dataset has dimension lat in the root group and coordinate variable lat(lat) in group /group1, then the flattened dataset will contain dimension lat and variable group1__lat(lat), both in its root group. In this case, the _flattener_variable_map global attribute of the flattened dataset will contain the mapping 'group1__lat: /group1/lat', and the _flattener_dimension_map global attribute will contain the mapping 'lat: /lat'.

New in version (cfdm): 1.11.2.0

Parameters

input_ds:

The dataset to be flattened, that has the same API as netCDF4.Dataset or h5netcdf.File.

output_ds: netCDF4.Dataset

A container for the flattened dataset.

strict: bool, optional

If True, the default, then failing to resolve a reference raises an exception. If False, a warning is issued and flattening is continued.

omit_data: bool, optional

If True then do not copy the data of any variables from input_ds to output_ds. This does not affect the amount of netCDF variables and dimensions that are written to the file, nor the netCDF variables’ attributes, but for all variables it does not create data on disk or in memory. The resulting dataset will be smaller than it otherwise would have been, and when the new dataset is accessed the data of these variables will be represented by an array of all missing data. If False, the default, then all data arrays are copied.

write_chunksize: int, optional

When omit_data is False, the copying of data is done piecewise to keep memory usage down. write_chunksize is the size in bytes of how much data is copied from input_ds to output_ds for each piece. Ignored if omit_data is True.