ncdata.utils package#

General user utility functions.

ncdata.utils.dataset_differences(dataset_or_path_1, dataset_or_path_2, check_names=False, check_dims_order=True, check_dims_unlimited=True, check_vars_order=True, check_attrs_order=True, check_groups_order=True, check_var_data=True, show_n_first_different=2, suppress_warnings=False)#

Compare two netcdf datasets.

Accepts paths, pathstrings, open netCDF4.Datasets or NcData objects. File paths are opened with the netCDF4 module.

Parameters:

  • dataset_or_path_1 (str or Path or netCDF4.Dataset or NcData) – First dataset to compare : either an open netCDF4.Dataset, a path to open one, or an NcData object.

  • dataset_or_path_2 (str or Path or netCDF4.Dataset or NcData) – Second dataset to compare : either an open netCDF4.Dataset, a path to open one, or an NcData object.

  • check_dims_order (bool, default True) – If False, no error results from the same dimensions appearing in a different order. However, unless suppress_warnings is True, the error string is issued as a warning.

  • check_vars_order (bool, default True) – If False, no error results from the same variables appearing in a different order. However unless suppress_warnings is True, the error string is issued as a warning.

  • check_attrs_order (bool, default True) – If False, no error results from the same attributes appearing in a different order. However unless suppress_warnings is True, the error string is issued as a warning.

  • check_groups_order (bool, default True) – If False, no error results from the same groups appearing in a different order. However unless suppress_warnings is True, the error string is issued as a warning.

  • check_names (bool, default False) – Whether to warn if the names of the top-level datasets are different

  • check_dims_unlimited (bool, default True) – Whether to compare the ‘unlimited’ status of dimensions

  • check_var_data (bool, default True) – If True, all variable data is also checked for equality. If False, only dtype and shape are compared. NOTE: comparison of arrays is done in-memory, so could be highly inefficient for large variable data.

  • show_n_first_different (int, default 2) – Number of value differences to display.

  • suppress_warnings (bool, default False) – When False (the default), report changes in content order as Warnings. When True, ignore changes in ordering. See also : Container ordering.

Returns:

errs – A list of “error” strings, describing differences between the inputs. If empty, no differences were found.

Return type:

list of str

ncdata.utils.ncdata_copy(ncdata)#

Return a copy of the data.

The operation makes fresh copies of all ncdata objects, but does not copy variable data arrays.

Parameters:

ncdata (NcData) – data to copy

Returns:

identical but distinct copy of input

Return type:

ncdata

ncdata.utils.save_errors(ncdata)#

Scan a dataset for it’s consistency and completeness.

Reports on anything that will make this fail to save. If there are any such problems, then an attempt to save the ncdata to a netcdf file will fail. If there are none, then a save should succeed.

The checks made are roughly the following

  1. check names in all components (dimensions, variables, attributes and groups):

  • all names are valid netcdf names

  • all element names match their key in the component, i.e. “component[key].name == key”

  1. check that all attribute values have netcdf-compatible dtypes. (E.G. no object or compound (recarray) dtypes).

  2. check that, for all contained variables :

  • it’s dimensions are all present in the enclosing dataset

  • it has an attached data array, of a netcdf-compatible dtype

  • the shape of it’s data matches the lengths of it’s dimensions

Parameters:

ncdata (NcData) – data to check

Returns:

A list of strings, error messages describing problems with the dataset. If no errors, returns an empty list.

Return type:

errors

ncdata.utils.variable_differences(v1, v2, check_attrs_order=True, check_var_data=True, show_n_first_different=2, suppress_warnings=False, _group_id_string=None)#

Compare variables.

Parameters:

  • v1 (NcVariable) – variables to compare

  • v2 (NcVariable) – variables to compare

  • check_attrs_order (bool, default True) – If False, no error results from the same contents in a different order, however unless suppress_warnings is True, the error string is issued as a warning.

  • check_var_data (bool, default True) – If True, all variable data is also checked for equality. If False, only dtype and shape are compared. NOTE: comparison of large arrays is done in-memory, so may be highly inefficient.

  • show_n_first_different (int, default 2) – Number of value differences to display.

  • suppress_warnings (bool, default False) – When False (the default), report changes in content order as Warnings. When True, ignore changes in ordering entirely.

  • _group_id_string (str) – (internal use only)

Returns:

errs – A list of “error” strings, describing differences between the inputs. If empty, no differences were found.

Return type:

list of str