i7aof.io

Utilities for writing NetCDF and related I/O helpers. See i7aof.io, i7aof.io_zarr and i7aof.download for developer details.

i7aof.io.ensure_cf_time_encoding(ds: Dataset, time_source: Dataset | None = None) → None
Parameters:

  • ds (xarray.Dataset) – Dataset whose encodings will be updated in-place.

  • time_source (xarray.Dataset, optional) – If provided, use its time variables to replace those from ds.

Returns:

The same dataset instance with encodings updated.

Return type:

xarray.Dataset

i7aof.io.read_dataset(path, **kwargs) → Dataset

Open a dataset with package defaults and normalize time metadata.

  • Ensures cftime decoding for robust non-standard calendars.

  • If both time and time_bnds are present, propagate the same units/calendar into time_bnds attributes (not encoding) so that both variables serialize consistently. This avoids placing units/calendar in encodings, which recent backends reject.

Any extra keyword arguments are passed through to xarray.open_dataset. By default, this function sets decode_times=CFDatetimeCoder(use_cftime=True) unless explicitly overridden, ensuring decoded CF-time coordinates backed by cftime objects for predictable behavior across calendars.

i7aof.io.write_netcdf(ds: Dataset, filename: str | Path, fillvalues: Dict[str, Any] | None = None, format: Literal['NETCDF4', 'NETCDF4_CLASSIC', 'NETCDF3_64BIT', 'NETCDF3_64BIT_DATA', 'NETCDF3_CLASSIC'] | None = None, engine: Literal['netcdf4', 'scipy', 'h5netcdf'] | None = None, progress_bar: bool = False, has_fill_values: bool | List[str] | None = None, compression: bool | List[str] | None = None, compression_opts: Dict[str, Any] | None = None) → None

Write an xarray.Dataset to a file with NetCDF4 fill values

Parameters:

  • ds (xarray.Dataset) – The dataset to save

  • filename (str) – The path for the NetCDF file to write

  • fillvalues (dict, optional) – A dictionary of fill values for different NetCDF types. Default is netCDF4.default_fillvals

  • format ({'NETCDF4', 'NETCDF4_CLASSIC', 'NETCDF3_64BIT', 'NETCDF3_64BIT_DATA', 'NETCDF3_CLASSIC'}, optional) – The NetCDF file format to use, the default is ‘NETCDF4’

  • engine ({'netcdf4', 'scipy', 'h5netcdf'}, optional) – The library to use for NetCDF output, the default is ‘h5netcdf’ if compression is specified, otherwise ‘netcdf4’.

  • has_fill_values (bool | list, optional) –

    Controls whether to apply _FillValue per variable without scanning data:

    • bool: apply to all variables (True adds, False omits)

    • list: the list of variable names to which to apply fill values.

    If omitted (None), the function determines necessity by checking for NaNs using xarray’s lazy operations (var.isnull().any().compute()), which is safe for chunked datasets. For unchunked datasets, the scan may load data into memory; callers can avoid this by opening datasets with Dask chunks.

  • compression (bool | list, optional) –

    Controls variable compression. Accepted forms mirror has_fill_values semantics:

    • bool: enable/disable default compression for all variables

    • list: the list of variable names to compress.

    If omitted (None), no compression is enabled by default; callers can enable it selectively. Note that support and available options depend on the chosen engine (for example, scipy does not support compression; netcdf4/h5netcdf do).

  • compression_opts (dict, optional) – Default compression options to apply when compression is requested via a boolean directive. Example: {'zlib': True, 'complevel': 4}. These defaults are merged with any per-variable dicts specified in compression.