cf.Domain

class cf.Domain(axes=None, dim=None, aux=None, measure=None, ref=None, copy=True, assign_axes=None, **kwargs)[source]

Bases: object

Completely describe a field’s coordinate system (domain).

It contains the domain axis constructs, dimension coordinate constructs, auxiliary coordinate constructs, cell measure constructs and coordinate reference constructs defined by the CF data model.

Initialization

Parameters:
axes : optional

Initialize axes of the domain. The axes parameter may be one of:

  • None. This is the default and axes are inferred from the dimension coordinate specified with the dim parameter.

  • (A sequence of) int. For each integer, an axis with that size is inserted into the domain with domain identifiers 'dim0', 'dim1', etc. for the first to the last axes in the sequence. If axes is an integer (rather than a sequence) then it is treated as a single element sequence.

    Example:

    To insert an axis of size 12 with domain identifier 'dim0': axes=12.

    Example:

    To insert axes of sizes 73 and 96 with domain identifiers 'dim0' and 'dim1' respectively: axes=[73, 96].

  • A dictionary which maps axis domain identifiers to axis sizes.

    Example:

    To insert an axis of size 12 with domain identifier 'dim4': axes={'dim4': 12}.

    Example:

    To insert axes of sizes 73 and 96 with domain identifiers 'dim3' and 'dim4' respectively: axes={'dim3': 73, 'dim4': 96}.

Note that axis initialization occurs before the initialization of dimension coordiante, auxiliary coordinate and cell measure and coordinate reference objects.

dim : optional

Initialize dimension coordinate objects of the domain.

Inserting a dimension coordinate object into the domain will automatically create a domain axis of the correct size, unless an axis with the same domain identifier has already been created with the axes parameter. So, in general, it is not necessary to initialize the axes spanned by dimension coordinates with the axes parameter.

The dim parameter may be one of:

  • None. This is the default and no dimension coordinate objects are inserted into the domain.

  • (A sequence of) cf.DimensionCoordinate. Each dimension coordinate object is inserted into the domain with domain identifiers 'dim0', 'dim1', etc. for the first to the last dimension coordinate object in the sequence. If dim is a cf.DimensionCoordinate (rather than a sequence) then it is treated as a single element sequence.

    Example:

    To insert a dimension coordinate, x, with domain identifier 'dim0': dim=x.

    Example:

    To insert dimension coordinates, x and y, with domain identifiers 'dim0' and 'dim1' respectively: dim=[x, y].

  • A dictionary which maps dimension coordinate domain identifiers to cf.DimensionCoordinate objects.

    Example:

    To insert a dimension coordinate, t, with domain identifier 'dim4': dim={'dim4': t}.

    Example:

    To insert dimension coordinates, x and y, with domain identifiers 'dim3' and 'dim4' respectively: dim={'dim3': x, 'dim4': y}.

Note that dimension coordinate initialization occurs after axis initialization and before the initialization of auxiliary coordinate and cell measure and coordinate reference objects.

aux : optional

Initialize auxiliary coordinate objects of the domain.

The axes spanned by an auxiliary coordinate must be defined by the axes and/or dim parameters. If there is no ambiguity (as will be the case if all of the axes have different sizes) then it is not necessary to describe which axes an auxiliary coordinate spans, and in which order. Otherwise, or in any case, the auxiliary coordinate axes may be specified with the assign_axes parameter.

The aux parameter may be one of:

  • None. This is the default and no auxiliary coordinate objects are inserted into the domain.

  • (A sequence of) cf.AuxiliaryCoordinate. Each auxiliary coordinate object is inserted into the domain with domain identifiers 'aux0', 'aux1', etc. for the first to the last auxiliary coordinate object in the sequence. If aux is a cf.AuxiliaryCoordinate (rather than a sequence) then it is treated as a single element sequence.

    Example:

    To insert an auxiliary coordinate, p, with domain identifier 'aux0': aux=p.

    Example:

    To insert auxiliary coordinates, p and q, with domain identifiers 'aux0' and 'aux1' respectively: aux=[p, q].

  • A dictionary which maps auxiliary coordinate domain identifiers to cf.AuxiliaryCoordinate objects.

    Example:

    To insert an auxiliary coordinate, r, with domain identifier 'aux4': aux={'aux4': r}.

    Example:

    To insert auxiliary coordinates, p and q, with domain identifiers 'aux3' and 'aux4' respectively: aux={'aux3': p, 'aux4': q}.

Note that auxiliary coordinate initialization occurs after axis and dimension coordinate initialization.

measure : optional

Initialize cell measure objects of the domain.

The axes spanned by a cell measure object must be defined by the axes and/or dim parameters. If there is no ambiguity (as will be the case if all of the axes have different sizes) then it is not necessary to describe which axes a cell measure spans, and in which order. Otherwise, or in any case, the cell measure axes may be specified with the assign_axes parameter.

The measure parameter may be one of:

  • None. This is the default and no cell measure objects are inserted into the domain.

  • (A sequence of) cf.CellMeasure. Each cell measure object is inserted into the domain with domain identifiers 'msr0', 'msr1', etc. for the first to the last cell measure object in the sequence. If msr is a cf.CellMeasure (rather than a sequence) then it is treated as a single element sequence.

    Example:

    To insert a cell measure, m, with domain identifier 'msr0': msr=m.

    Example:

    To insert cell measures, m and n, with domain identifiers 'msr0' and 'msr1' respectively: msr=[m, n].

  • A dictionary which maps cell measure domain identifiers to cf.CellMeasure objects.

    Example:

    To insert a cell measure, m, with domain identifier 'msr4': msr={'msr4': m}.

    Example:

    To insert cell measures, m and n, with domain identifiers 'msr3' and 'msr4' respectively: msr={'msr3': m, 'msr4': n}.

Note that cell measure initialization occurs after axis, dimension coordinate and auxiliary coordinate initialization.

assign_axes, kwargs : dict, optional

Map coordinate and cell measure objects to the axes which they span.

Each dictionary key is a domain identifier of a dimension coordinate, auxiliary coordinate or cell measure object which has been previously defined by the dim, aux or measure parameters. Its corresponding value specifies the axes that the item spans, in the correct order. The axes are those returned by this call of the domain’s axes method: d.axes(value, order=True, **kwargs) (see cf.Field.axes for details).

For each dimension coordinate, auxiliary coordinate or cell measure object, if there is no ambiguity as to which axes it spans (as will be the case if all of the axes have different sizes) then it is not necessary provide this item to the assign_axes dictionary, as the spanning axes may be deduced automatically. Otherwise it is required.

Example:

Auxiliary coordinate 'aux0' spans axis 'dim0' and auxiliary coordinate 'aux1' spans axes 'dim2' and dim1', in that order: assign_axes={'aux0': 'dim0', 'aux1': ['dim2', `dim1`]}.

Example:

Auxiliary coordinate 'aux0' spans axis the Z axis cell measure 'msr1' spans the Y and X axes, in that order: assign_axes={'aux0': 'Z', 'msr1': ['Y', 'X']}. In this case it is assumed that the axes have dimension coordinates with sufficient metadta to be able to define them as Z, Y and X axes.

ref : optional

Initialize coordinate reference objects of the domain.

The ref parameter may be one of:

  • None. This is the default and no coordinate reference objects are inserted into the domain.

  • (A sequence of) cf.CoordinateReference. Each coordinate reference object is inserted into the domain with domain identifiers 'ref0', 'ref1', etc. for the first to the last coordinate reference object in the sequence. If ref is a cf.CoordinateReference (rather than a sequence) then it is treated as a single element sequence.

    Example:

    To insert a coordinate reference, b, with domain identifier 'ref0': ref=b.

    Example:

    To insert coordinate references, b and c, with domain identifiers 'ref0' and 'ref1' respectively: ref=[b, c].

  • A dictionary which maps coordinate reference domain identifiers to cf.CoordinateReference objects.

    Example:

    To insert a coordinate reference, m, with domain identifier 'ref4': ref={'ref4': m}.

    Example:

    To insert coordinate references, b and c, with domain identifiers 'ref3' and 'ref4' respectively: ref={'ref3': b, 'ref4': c}.

Note that coordinate reference initialization occurs after axis, dimension coordinate, auxiliary coordinate and cell measure initialization.

copy : bool, optional

If True (the default) then all dimension coordinate, auxiliary coordinate, cell measure and coordinate reference objects are copied prior to insertion.
Examples:

In this example, four dots (....) refers to appropriate initialization parameters of the coordinate, cell measure and coordinate reference constructs, which are omitted here for clarity.

>>> dim_coord_A = cf.DimensionCoordinate(....)
>>> dim_coord_B = cf.DimensionCoordinate(....)
>>> dim_coord_A.size, dim_coord_B.size
(73, 96)
>>> dim_coord_A.X, dim_coord_B.Y
(True, True)
>>> aux_coord_A = cf.AuxiliaryCoordinate(....)
>>> aux_coord_A.shape
(96, 73)
>>> cell_measure_A = cf.CellMeasure(....)
>>> cell_measure_A.shape
(73, 96)
>>> ref_A = cf.CoordinateReference(name='latitude_longitude', ....)
>>> d = cf.Domain(dim=[dim_coord_A, dim_coord_B],
...               aux=aux_coord_A,
...               measure=cell_measure_A,
...               ref=ref_A)
...
>>> d.items_axes()
{'aux0': ['dim1', 'dim0'],
 'msr0': ['dim0', 'dim1'],
 'dim1': ['dim1'],
 'dim0': ['dim0']}
>>> d.refs
{'ref0' : <CF CoordinateReference: latitude_longitude>}

It was not necessary to specify the axis mappings for aux_coord_A and cell_measure_A because the two axes have unambiguous sizes.

The same domain could have been initialised using the dictionary form of the parameters and explicitly assigning axes described by their dimension coordinate metadata:

>>> e = cf.Domain(axes={'dim0': 73, 'dim1': 96},
...               dim={'dim0': dim_coord_A, 'dim1': dim_coord_B},
...               aux={'aux0': aux_coord_A},
...               measure={'msr0': cell_measureA},
...               ref={'ref0': ref_A},
...               assign_axes={'aux0': ['Y', 'X'],
...                            'msr0': ['X', 'Y']})
...
>>> e.equals(d)
True

Domain methods

analyse Analyse a domain.
axes Return domain axis identifiers.
axis Return a domain axis identifier.
axis_name Return the canonical name for an axis.
close Close all referenced open data files.
copy Return a deep copy.
ref_axes Return the axes spanned by the coordinate object inputs of a coordinate reference object.
data_axes Return the axes of the field’s data array.
direction Return True if an axis is increasing, otherwise return False.
directions Return a dictionary mapping axes to their directions.
dump Return a string containing a full description of the domain.
dump_axes Return a string containing a description of the domain.
dump_components Return a string containing a full description of the domain.
equals True if two domains are equal, False otherwise.
equivalent True if and only if two domains are logically equivalent.
equivalent_refs True if a coordinate refencence object is the same as one in another domain.
expand_dims Expand the domain with a new dimension in place.
get Return the item corresponding to an internal identifier.
has True if the domain has the given internal identifier.
insert_aux Insert a auxiliary coordinate into the domain in place.
insert_axis Insert an axis into the domain in place.
insert_coord Insert a dimension coordinate or auxiliary coordinate into the domain in place.
insert_dim Insert a dimension coordinate to the domain in place.
insert_measure Insert a cell measure into the domain in place.
insert_ref Insert a coordinate reference object into the domain in place.
item Return an item of the domain, or its domain identifier.
item_axes Return the axes of a domain item.
items Return items of the domain.
map_axes Map the axis identifiers of the domain to their equivalent axis identifiers of another.
new_aux_identifier Return a new, unique auxiliary coordinate identifier for the domain.
new_axis_identifier Return a new, unique axis identifier for the domain.
new_measure_identifier Return a new, unique cell measure identifier for the domain.
new_ref_identifier Return a new, unique coordinate reference identifier for the domain.
remove_axes Remove and return axes from the domain.
remove_axis Remove and return an axis from the domain.
remove_item Remove and return an item from the domain.
remove_items Remove and return items from the domain.