cfdm.datum

Classes

Datum([parameters, source, copy])

A datum component of a CF data model coordinate reference.
class cfdm.datum.Datum(parameters=None, source=None, copy=True)[source]

Bases: Parameters, NetCDFVariable, Files, Datum

A datum component of a CF data model coordinate reference.

A datum is a complete or partial definition of the zeroes of the dimension and auxiliary coordinate constructs which define a coordinate system.

The datum may contain the definition of a geophysical surface which corresponds to the zero of a vertical coordinate construct, and this may be required for both horizontal and vertical coordinate systems.

Elements of the datum not specified may be implied by the properties of the dimension and auxiliary coordinate constructs referenced by the CoordinateReference instance that contains the datum.

NetCDF interface

The netCDF variable name may be accessed with the nc_set_variable, nc_get_variable, nc_del_variable, and nc_has_variable methods.

The netCDF variable group structure may be accessed with the nc_set_variable, nc_get_variable, nc_variable_groups, nc_clear_variable_groups, and nc_set_variable_groups methods.

Added in version (cfdm): 1.7.0

Initialisation

Parameters:
parameters: dict, optional

Set parameters. The dictionary keys are parameter names, with corresponding values.

Parameters may also be set after initialisation with the set_parameters and set_parameter methods.

Parameter example:

parameters={'earth_radius': 6371007.}

source: optional

Convert source, which can be any type of object, to a Datum instance.

All other parameters, apart from copy, are ignored and their values are instead inferred from source by assuming that it has the Datum API. Any parameters that can not be retrieved from source in this way are assumed to have their default value.

Note that if x is also a Datum instance then cfdm.Datum(source=x) is equivalent to x.copy().

copy: bool, optional

If True (the default) then deep copy the input parameters prior to initialisation. By default the parameters are not deep copied.

clear_parameters()[source]

Remove all parameters.

Added in version (cfdm): 1.7.0

See also

del_parameter, parameters, set_parameters

Returns:
dict

The parameters that have been removed.

Examples

>>> f = cfdm.Datum()
>>> f.parameters()
{}
>>> p = {'standard_parallel': 25.0,
...      'longitude_of_central_meridian': 265.0,
...      'latitude_of_projection_origin': 25.0}
>>> f.set_parameters(p)
>>> f.parameters()
{'standard_parallel': 25.0,
 'longitude_of_central_meridian': 265.0,
 'latitude_of_projection_origin': 25.0}

>>> old = f.clear_parameters()
>>> old
{'standard_parallel': 25.0,
 'longitude_of_central_meridian': 265.0,
 'latitude_of_projection_origin': 25.0}
>>> f.set_parameters(old)
copy()[source]

Return a deep copy.

f.copy() is equivalent to copy.deepcopy(f).

Added in version (cfdm): 1.7.0

Returns:
Datum

The deep copy.

Examples

>>> f = cfdm.Datum()
>>> g = f.copy()
creation_commands(namespace=None, indent=0, string=True, name='p', header=True)[source]

Return the commands that would create the component.

Added in version (cfdm): 1.12.2.0

See also

cfdm.Field.creation_commands

Parameters:
namespace: str, optional

The name space containing classes of the cfdm package. This is prefixed to the class name in commands that instantiate instances of cfdm objects. By default, or if None, the name space is assumed to be consistent with cfdm being imported as import cfdm.

Parameter example:

If cfdm was imported as import cfdm as xyz then set namespace='xyz'

Parameter example:

If cfdm was imported as from cfdm import * then set namespace=''

indent: int, optional

Indent each line by this many spaces. By default no indentation is applied. Ignored if string is False.

string: bool, optional

If False then return each command as an element of a list. By default the commands are concatenated into a string, with a new line inserted between each command.

name: str, optional

The name of the Datum instance created by the returned commands.

header: bool, optional

If True (the default) output a comment describing the components. If False no such comment is returned.

Returns:
str or list

The commands in a string, with a new line inserted between each command. If string is False then the separate commands are returned as each element of a list.

Examples

>>> x = cfdm.Datum({'algorithm': 'granular_bitround'})
>>> x.nc_set_variable('var')
>>> print(x.creation_commands(header=False))
p = cfdm.Datum()
p.set_parameters({'algorithm': 'granular_bitround'})
p.nc_set_variable('var')
del_parameter(parameter, default=ValueError())[source]

Delete a parameter.

Added in version (cfdm): 1.7.0

See also

get_parameter, has_parameter, parameters, set_parameter

Parameters:
parameter: str

The name of the parameter to be deleted.

default: optional

Return the value of the default parameter if the parameter has not been set.

If set to an Exception instance then it will be raised instead.

Returns:

The removed parameter value.

Examples

>>> f = cfdm.Datum()
>>> f.set_parameter('earth_radius', 6371007)
>>> f.has_parameter('earth_radius')
True
>>> f.get_parameter('earth_radius')
6371007
>>> f.del_parameter('earth_radius')
6371007
>>> f.has_parameter('earth_radius')
False
>>> print(f.del_parameter('earth_radius', None))
None
>>> print(f.get_parameter('earth_radius', None))
None
dump(*args, **kwargs)[source]

A full description.

Added in version (cfdm): 1.12.2.0

Parameters:
display: bool, optional

If False then return the description as a string. By default the description is printed.

Returns:
str or None

The description. If display is True then the description is printed and None is returned. Otherwise the description is returned as a string.

equals(**kwargs)[source]

Whether two instances are the same.

Equality is strict by default. This means that:

  • the named parameters must be the same, with the same values and data types, and vector-valued parameters must also have same the size 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 type of object may be tested but, in general, equality is only possible with another object of the same type, or a subclass of one. See the ignore_type parameter.

Parameters:
other:

The object to compare for equality.

atol: number, optional

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

rtol: number, optional

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

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_type: bool, optional

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

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 the operation.

Returns:
bool

Whether the two instances are equal.

Examples

>>> d.equals(d)
True
>>> d.equals(d.copy())
True
>>> d.equals(None)
False
get_original_filenames()[source]

The names of files containing the original data and metadata.

The original files are those that contain some or all of the data and metadata when it was first instantiated, and are necessary (but perhaps not sufficient) to recreate the Datum should the need arise. The cfdm.read function automatically records the original file names on all data that it creates.

The original files of any constituent components are also included.

In-place changes to the Datum will not generally change the collection of original files. However if the Datum was produced by combining other objects that also store their original file names, then the returned files will be the collection of original files from all contributing sources.

Added in version (cfdm): 1.10.0.1

Returns:
set

The original file names in normalised absolute form. If there are no original files then an empty set will be returned.

get_parameter(parameter, default=ValueError())[source]

Get a parameter value.

Added in version (cfdm): 1.7.0

Parameters:
parameter: str

The name of the parameter.

default: optional

Return the value of the default parameter if the parameter has not been set.

If set to an Exception instance then it will be raised instead.

Returns:

The value of the parameter.

Examples

>>> f = cfdm.Datum()
>>> f.set_parameter('earth_radius', 6371007)
>>> f.has_parameter('earth_radius')
True
>>> f.get_parameter('earth_radius')
6371007
>>> f.del_parameter('earth_radius')
6371007
>>> f.has_parameter('earth_radius')
False
>>> print(f.del_parameter('earth_radius', None))
None
>>> print(f.get_parameter('earth_radius', None))
None
has_parameter(parameter)[source]

Whether a parameter has been set.

Added in version (cfdm): 1.7.0

See also

del_parameter, get_parameter, parameters, set_parameter

Parameters:
parameter: str

The name of the parameter.

Parameter example:

parameter='geoid_name'

Returns:
bool

True if the parameter has been set, otherwise False.

Examples

>>> f = cfdm.Datum()
>>> f.set_parameter('earth_radius', 6371007)
>>> f.has_parameter('earth_radius')
True
>>> f.get_parameter('earth_radius')
6371007
>>> f.del_parameter('earth_radius')
6371007
>>> f.has_parameter('earth_radius')
False
>>> print(f.del_parameter('earth_radius', None))
None
>>> print(f.get_parameter('earth_radius', None))
None
nc_clear_variable_groups()[source]

Remove the netCDF variable group hierarchy.

The group hierarchy is defined by the netCDF name. Groups are delimited by / (slash) characters in the netCDF name. The groups are returned, in hierarchical order, as a sequence of strings. If the name is not set, or contains no / characters then an empty sequence is returned, signifying the root group.

An alternative technique for removing the group structure is to set the netCDF variable name, with nc_set_variable, with no / characters.

Added in version (cfdm): 1.8.6

See also

nc_variable_groups, nc_set_variable_groups

Returns:
tuple of str

The removed group structure.

Examples

>>> f.nc_set_variable('time')
>>> f.nc_variable_groups()
()
>>> f.nc_set_variable_groups(['forecast', 'model'])
>>> f.nc_variable_groups()
('forecast', 'model')
>>> f.nc_get_variable()
'/forecast/model/time'
>>> f.nc_clear_variable_groups()
('forecast', 'model')
>>> f.nc_get_variable()
'time'

>>> f.nc_set_variable('/forecast/model/time')
>>> f.nc_variable_groups()
('forecast', 'model')
>>> f.nc_del_variable('/forecast/model/time')
'/forecast/model/time'
>>> f.nc_variable_groups()
()
nc_del_variable(default=ValueError())[source]

Remove the netCDF variable name.

Added in version (cfdm): 1.7.0

See also

nc_get_variable, nc_has_variable, nc_set_variable

Parameters:
default: optional

Return the value of the default parameter if the netCDF variable name has not been set. If set to an Exception instance then it will be raised instead.

Returns:
str

The removed netCDF variable name.

Examples

>>> f.nc_set_variable('tas')
>>> f.nc_has_variable()
True
>>> f.nc_get_variable()
'tas'
>>> f.nc_del_variable()
'tas'
>>> f.nc_has_variable()
False
>>> print(f.nc_get_variable(None))
None
>>> print(f.nc_del_variable(None))
None
nc_get_variable(default=ValueError())[source]

Return the netCDF variable name.

Added in version (cfdm): 1.7.0

See also

nc_del_variable, nc_has_variable, nc_set_variable

Parameters:
default: optional

Return the value of the default parameter if the netCDF variable name has not been set. If set to an Exception instance then it will be raised instead.

Returns:
str

The netCDF variable name. If unset then default is returned, if provided.

Examples

>>> f.nc_set_variable('tas')
>>> f.nc_has_variable()
True
>>> f.nc_get_variable()
'tas'
>>> f.nc_del_variable()
'tas'
>>> f.nc_has_variable()
False
>>> print(f.nc_get_variable(None))
None
>>> print(f.nc_del_variable(None))
None
nc_has_variable()[source]

Whether the netCDF variable name has been set.

Added in version (cfdm): 1.7.0

See also

nc_del_variable, nc_get_variable, nc_set_variable

Returns:
bool

True if the netCDF variable name has been set, otherwise False.

Examples

>>> f.nc_set_variable('tas')
>>> f.nc_has_variable()
True
>>> f.nc_get_variable()
'tas'
>>> f.nc_del_variable()
'tas'
>>> f.nc_has_variable()
False
>>> print(f.nc_get_variable(None))
None
>>> print(f.nc_del_variable(None))
None
nc_set_variable(value)[source]

Set the netCDF variable name.

If there are any / (slash) characters in the netCDF name then these act as delimiters for a group hierarchy. By default, or if the name starts with a / character and contains no others, the name is assumed to be in the root group.

Added in version (cfdm): 1.7.0

See also

nc_del_variable, nc_get_variable, nc_has_variable

Parameters:
value: str

The value for the netCDF variable name.

Returns:

None

Examples

>>> f.nc_set_variable('tas')
>>> f.nc_has_variable()
True
>>> f.nc_get_variable()
'tas'
>>> f.nc_del_variable()
'tas'
>>> f.nc_has_variable()
False
>>> print(f.nc_get_variable(None))
None
>>> print(f.nc_del_variable(None))
None
nc_set_variable_groups(groups)[source]

Set the netCDF variable group hierarchy.

The group hierarchy is defined by the netCDF name. Groups are delimited by / (slash) characters in the netCDF name. The groups are returned, in hierarchical order, as a sequence of strings. If the name is not set, or contains no / characters then an empty sequence is returned, signifying the root group.

An alternative technique for setting the group structure is to set the netCDF variable name, with nc_set_variable, with the group structure delimited by / characters.

Added in version (cfdm): 1.8.6

See also

nc_clear_variable_groups, nc_variable_groups

Parameters:
groups: sequence of str

The new group structure.

Returns:
tuple of str

The group structure prior to being reset.

Examples

>>> f.nc_set_variable('time')
>>> f.nc_variable_groups()
()
>>> f.nc_set_variable_groups(['forecast', 'model'])
>>> f.nc_variable_groups()
('forecast', 'model')
>>> f.nc_get_variable()
'/forecast/model/time'
>>> f.nc_clear_variable_groups()
('forecast', 'model')
>>> f.nc_get_variable()
'time'

>>> f.nc_set_variable('/forecast/model/time')
>>> f.nc_variable_groups()
('forecast', 'model')
>>> f.nc_del_variable('/forecast/model/time')
'/forecast/model/time'
>>> f.nc_variable_groups()
()
nc_variable_groups()[source]

Return the netCDF variable group hierarchy.

The group hierarchy is defined by the netCDF name. Groups are delimited by / (slash) characters in the netCDF name. The groups are returned, in hierarchical order, as a sequence of strings. If the name is not set, or contains no / characters then an empty sequence is returned, signifying the root group.

Added in version (cfdm): 1.8.6

See also

nc_clear_variable_groups, nc_set_variable_groups

Returns:
tuple of str

The group structure.

Examples

>>> f.nc_set_variable('time')
>>> f.nc_variable_groups()
()
>>> f.nc_set_variable_groups(['forecast', 'model'])
>>> f.nc_variable_groups()
('forecast', 'model')
>>> f.nc_get_variable()
'/forecast/model/time'
>>> f.nc_clear_variable_groups()
('forecast', 'model')
>>> f.nc_get_variable()
'time'

>>> f.nc_set_variable('/forecast/model/time')
>>> f.nc_variable_groups()
('forecast', 'model')
>>> f.nc_del_variable('/forecast/model/time')
'/forecast/model/time'
>>> f.nc_variable_groups()
()
parameters()[source]

Return all parameters.

Added in version (cfdm): 1.7.0

See also

clear_parameters, get_parameter, has_parameter set_parameters

Returns:
dict

The parameters.

Examples

>>> f = cfdm.Datum()
>>> f.parameters()
{}
>>> p = {'standard_parallel': 25.0,
...      'longitude_of_central_meridian': 265.0,
...      'latitude_of_projection_origin': 25.0}
>>> f.set_parameters(p)
>>> f.parameters()
{'standard_parallel': 25.0,
 'longitude_of_central_meridian': 265.0,
 'latitude_of_projection_origin': 25.0}

>>> old = f.clear_parameters()
>>> old
{'standard_parallel': 25.0,
 'longitude_of_central_meridian': 265.0,
 'latitude_of_projection_origin': 25.0}
>>> f.set_parameters(old)
set_parameter(term, value, copy=True)[source]

Set a parameter-valued term.

Added in version (cfdm): 1.7.0

See also

parameters

Returns:

None

Examples

>>> f = cfdm.Datum()
>>> f.set_parameter('earth_radius', 6371007)
>>> f.has_parameter('earth_radius')
True
>>> f.get_parameter('earth_radius')
6371007
>>> f.del_parameter('earth_radius')
6371007
>>> f.has_parameter('earth_radius')
False
>>> print(f.del_parameter('earth_radius', None))
None
>>> print(f.get_parameter('earth_radius', None))
None
set_parameters(parameters, copy=True)[source]

Set parameters.

Added in version (cfdm): 1.7.0

See also

clear_parameters, parameters, set_parameter

Parameters:
parameters: dict

Store the parameters from the dictionary supplied.

Parameter example:

parameters={'earth_radius': 6371007}

copy: bool, optional

If False then any parameter values provided by the parameters parameter are not copied before insertion. By default they are deep copied.

Returns:

None

Examples

>>> f = cfdm.Datum()
>>> f.parameters()
{}
>>> p = {'standard_parallel': 25.0,
...      'longitude_of_central_meridian': 265.0,
...      'latitude_of_projection_origin': 25.0}
>>> f.set_parameters(p)
>>> f.parameters()
{'standard_parallel': 25.0,
 'longitude_of_central_meridian': 265.0,
 'latitude_of_projection_origin': 25.0}

>>> old = f.clear_parameters()
>>> old
{'standard_parallel': 25.0,
 'longitude_of_central_meridian': 265.0,
 'latitude_of_projection_origin': 25.0}
>>> f.set_parameters(old)