cfdm.Field.equals

Field.equals(other, rtol=None, atol=None, verbose=None, ignore_data_type=False, ignore_fill_value=False, ignore_properties=(), ignore_compression=True, ignore_type=False)[source]

Whether two field constructs are the same.

Equality is strict by default. This means that for two field constructs to be considered equal they must have corresponding metadata constructs and for each pair of constructs:

  • the same descriptive properties must be present, with the same values and data types, and vector-valued properties must also have same the size and be element-wise equal (see the ignore_properties and ignore_data_type parameters), and

  • if there are data arrays then they must have same shape and data type, the same missing data mask, and be element-wise equal (see the ignore_data_type parameter).

Two real numbers x and y are considered equal if |x-y|<=atol+rtol|y|, where atol (the tolerance on absolute differences) and rtol (the tolerance on relative differences) are positive, typically very small numbers. See the atol and rtol parameters.

Any compression is ignored by default, with only the the arrays in their uncompressed forms being compared. See the ignore_compression parameter.

Any type of object may be tested but, in general, equality is only possible with another field construct, or a subclass of one. See the ignore_type parameter.

NetCDF elements, such as netCDF variable and dimension names, do not constitute part of the CF data model and so are not checked on any construct.

New in version 1.7.0.

Parameters
other:

The object to compare for equality.

atol: float, optional

The tolerance on absolute differences between real numbers. The default value is set by the cfdm.atol function.

rtol: float, optional

The tolerance on relative differences between real numbers. The default value is set by the cfdm.rtol function.

ignore_fill_value: bool, optional

If True then the _FillValue and missing_value properties are omitted from the comparison, for the field construct and metadata constructs.

verbose: int or str or None, optional

If an integer from -1 to 3, or an equivalent string equal ignoring case to one of:

  • 'DISABLE' (0)

  • 'WARNING' (1)

  • 'INFO' (2)

  • 'DETAIL' (3)

  • 'DEBUG' (-1)

set for the duration of the method call only as the minimum cut-off for the verboseness level of displayed output (log) messages, regardless of the globally-configured cfdm.log_level. Note that increasing numerical value corresponds to increasing verbosity, with the exception of -1 as a special case of maximal and extreme verbosity.

Otherwise, if None (the default value), output messages will be shown according to the value of the cfdm.log_level setting.

Overall, the higher a non-negative integer or equivalent string that is set (up to a maximum of 3/'DETAIL') for increasing verbosity, the more description that is printed to convey information about differences that lead to inequality.

ignore_properties: sequence of str, optional

The names of properties of the field construct (not the metadata constructs) to omit from the comparison. Note that the Conventions property is always omitted by default.

ignore_data_type: bool, optional

If True then ignore the data types in all numerical comparisons. By default different numerical data types imply inequality, regardless of whether the elements are within the tolerance for equality.

ignore_compression: bool, optional

If False then the compression type and, if applicable, the underlying compressed arrays must be the same, as well as the arrays in their uncompressed forms. By default only the arrays in their uncompressed forms are compared.

ignore_type: bool, optional

Any type of object may be tested but, in general, equality is only possible with another field construct, or a subclass of one. If ignore_type is True then Field(source=other) is tested, rather than the other defined by the other parameter.

Returns
bool

Whether the two field constructs are equal.

Examples:

>>> f.equals(f)
True
>>> f.equals(f.copy())
True
>>> f.equals(f[...])
True
>>> f.equals('not a Field instance')
False
>>> g = f.copy()
>>> g.set_property('foo', 'bar')
>>> f.equals(g)
False
>>> f.equals(g, verbose=3)
Field: Non-common property name: foo
Field: Different properties
False