cf.Domain

class cf.Domain(axes={}, assign_axes={}, dim=None, aux=None, cm=None, trans=None, copy=True, finalize=True)

Bases: object

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

It contains the dimensions constructs, auxiliary coordinate constructs, cell measure constructs and transform constructs defined by the CF data model.

The domain is a dictionary-like object whose key/value pairs identify dimension coordinate, auxiliary coordinate and cell measure constructs and store them as cf.DimensionCoordinate, cf.AuxiliaryCoordinate and cf.CellMeasure objects respectively.

Initialization

Note

cf.DimensionCoordinate, cf.AuxiliaryCoordinate and cf.Coordinate objects may almost always be used interchangably in the initialization, but there may be performance improvements if the appropriate type is provided.

Parameters :

dim : (sequence or dict of) cf.DimensionCoordinate, optional

Initialize dimension coordinates.

If sequence of dimension coordinates is given then identifiers will be automatically initialized as 'dim0', 'dim1', etc. for the first to the last dimension coordinates in the ordered sequence. Giving a cf.DimensionCoordinate object is equivalent to a single element sequence.

If a dictionary is given then the keys are dimension coordinate identifiers ('dimN') and values are dimension coordinate objects. The N part of each key identifier should be replaced by an arbitrary integer greater then or equal to zero. Careful selection of dimension coordinate identifiers ('dimN') may prevent the need to set the axes parameter.

No meaning should be inferred from the integer part of the identifiers, which need not include zero nor be consecutive.

aux : (sequence or dict of) cf.AuxiliaryCoordinate, optional

Initialize auxiliary coordinates.

If a sequence of auxiliary coordinates is given then identifiers will be automatically initialized as 'aux0', 'aux1', etc. for the first to the last auxiliary coordinates in the ordered sequence. Giving an cf.AuxiliaryCcoordinate object is equivalent to a single element sequence.

If a dictionary is given then the keys are auxiliary coordinate identifiers ('auxN') and values are auxiliary coordinate instances. The N part of each key identifier should be replaced by an arbitrary integer greater then or equal to zero.

No meaning should be inferred from the integer part of the identifiers, which need not include zero nor be consecutive.

cm : (sequence of) cf.CellMeasure, optional

Initialize cell measures.

If a sequence of cell measures is given then identifiers will be automatically initialized as 'cm0', 'cm1', etc. for the first to the last cell measures in the ordered sequence. Giving a cf.CellMeasure object is equivalent to a single element sequence.

If a dictionary is given then the keys are cell measure identifiers ('cmN') and values are auxiliary coordinate instances. The N part of each key identifier should be replaced by an arbitrary integer greater then or equal to zero.

No meaning should be inferred from the integer part of the identifiers, which need not include zero nor be consecutive.

assign_axes : dict, optional

Initialize the mapping of which axes span each component of the domain. The dictionary is stored in the domain’s dimensions attribute. By default it is intitialized as follows:

• For each dimension coordinate, a key/value pair is created for which the key is the dimension coordinate’s identifier ('dimN') and the value is a single element list of the same identifier ('dimN'). I.e. a dimension coordinate identifier is identical to the identifier of the dimension which it spans. Consequently, it is never necessary to map a dimension coordinate to its dimension.

• For each auxiliary coordinate and cell measure, a key/value pair is created for which the key is the auxiliary coordinate’s or cell measure’s identifier ('auxN' or 'cmN' respectively ) and the value is a list of dimension identifiers ('dimN'), stating the assumed dimensions, in order, of the construct concerned. These dimension identifiers will be the sequence of consecutive dimension identifiers 'dim0' up to 'dimM', where M-1 is the number of dimensions of the construct. An assumed dimension will be initialized with the correct size if it has not been specified elsewhere (by the kwargs, dims or dimension_sizes parameters).

Explicitly setting a particular construct’s dimensions does not alter the default behaviour for other constructs.

Any dimension given in a value list that has not been specified elsewhere (by the kwargs, dims or dimension_sizes parameters) will be initialized with the correct size.

Note that it is possible to set the mapping of which dimensions relate to a field’s data array by creating the key 'data' whose value is a list of dimension identifiers ('dimN'), stating the dimensions, in order, of the field’s data array.

axes : dict, optional

Initialize axes of the domain. By default the axes are inferred from the dimension coordinate, auxiliary coordinate and cell measure constructs.

An axis is set by providing a key/value pair for which the key is the dimension’s identifier ('dimN') and the value is the dimension’s integer size. The N part of the key identifier should be replaced by an arbitrary integer greater then or equal to zero.

No meaning should be inferred from the integer part of the identifiers, which need not include zero nor be consecutive.

Explicitly setting a dictionary key does not alter the default behaviour for other axes.

Note that a dimension may be intialized which is not spanned by any of the given constructs, and a dimension spanned by a given construct may also be initialized here, providing that there they are consistent.

assign_axes : dict, optional

Initialize the mapping of which axes span each component of the domain. The dictionary is stored in the domain’s dimensions attribute. By default it is intitialized as follows:

• For each dimension coordinate, a key/value pair is created for which the key is the dimension coordinate’s identifier ('dimN') and the value is a single element list of the same identifier ('dimN'). I.e. a dimension coordinate identifier is identical to the identifier of the dimension which it spans. Consequently, it is never necessary to map a dimension coordinate to its dimension.

• For each auxiliary coordinate and cell measure, a key/value pair is created for which the key is the auxiliary coordinate’s or cell measure’s identifier ('auxN' or 'cmN' respectively ) and the value is a list of dimension identifiers ('dimN'), stating the assumed dimensions, in order, of the construct concerned. These dimension identifiers will be the sequence of consecutive dimension identifiers 'dim0' up to 'dimM', where M-1 is the number of dimensions of the construct. An assumed dimension will be initialized with the correct size if it has not been specified elsewhere (by the kwargs, dims or dimension_sizes parameters).

Explicitly setting a particular construct’s dimensions does not alter the default behaviour for other constructs.

Any dimension given in a value list that has not been specified elsewhere (by the kwargs, dims or dimension_sizes parameters) will be initialized with the correct size.

Note that it is possible to set the mapping of which axes relate to a field’s data array by creating the key 'data' whose value is a list of axis identifiers ('dimN'), stating the axes, in order, of the field’s data array.

trans : (sequence or dict of) cf.Transform, optional

Initialize transforms.

If a sequence of transforms is given then identifiers will be automatically initialized as 'trans0', 'trans1', etc. for the first to the last transforms in the ordered sequence. Giving a cf.Transform object is equivalent to a single element sequence.

If a dictionary is given then the keys are transform identifiers ('transN') and values are auxiliary coordinate instances. The N part of each key identifier should be replaced by an arbitrary integer greater then or equal to zero.

No meaning should be inferred from the integer part of the identifiers, which need not include zero nor be consecutive.

Examples

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

>>> dim_coord_A = cf.DimensionCoordinate(....)
>>> dim_coord_B = cf.DimensionCoordinate(....)
>>> dim_coord_A.size
73
>>> dim_coord_B.size 
96
>>> aux_coord_A = cf.AuxiliaryCoordinate(....)
>>> aux_coord_A.shape
(96, 73)
>>> cell_measure_A = cf.CellMeasure(....)
>>> cell_measure_A.shape
(73, 96)
>>> transform_A = cf.Transform(grid_mapping_name='latitude_longitude', ....)
>>> d = cf.Domain(dim=(dim_coord_A, dim_coord_B),
...               aux=aux_coordA,
...               cm=[cell_measure_A],
...               trans=transform_A,
...               assign_axes={'aux0': ['dim1', 'dim0']})
...
>>> d.dimensions
{'aux0': ['dim1', 'dim0'],
 'cm0' : ['dim0', 'dim1'],
 'dim1': ['dim1'],
 'dim0': ['dim0']}
>>> d.transforms
{'trans0' : <CF Transform: latitude_longitude>}

It was necessary to specifiy the dimension mapping for 'aux0' because the auxiliary coordinate doesn’t have the default dimension order of ['dim0', 'dim1']. Equivalent ways of initializing the same domain are as follows:

>>> d = cf.Domain(dim=[dim_coordA, dim_coordB],
...               aux=aux_coordA,
...               cm=cell_measureA,
...               trans=transformA,
...               assign_axes={'aux0': ['dim1', 'dim0']}
...               transform_map={'trans0': 'aux0'})

Note that we may (for clarity) specify an entry in the dimensions dictionary, even if the default behaviour aplies:

>>> d = cf.Domain(dim={'dim1': dim_coord_B, 'dim0': dim_coord_A},
...               aux0={'aux0': aux_coord_A},
...               cm0={'cm0': cell_measure_A},
...               trans={'trans0': transform_A},,
...               assign_axes={'aux0': ['dim1', 'dim0'],
...                            'cm0' : ['dim0', 'dim1']})

We may change default identifier names:

>>> d = cf.Domain(dim=[dim_coord_A, dim_coord_B],
...               aux={'aux5': aux_coord_A},
...               cm=[cell_measureA],
...               trans=transform_A,
...               assign_axes={'aux5': ['dim1', 'dim0']})

>>> d = cf.Domain(dim={'dim21': dim_coord_A, 'dim3': dim_coord_B},
...               aux={'aux5': aux_coord_A},
...               cm=cell_measureA,
...               trans=[transform_A],
...               assign_axes={'aux5': ['dim3' , 'dim21'],
...                            'cm0' : ['dim21', 'dim3']})

In the last case it was necessary to include the cell measure construct in the dimension map because we had altered the default dimension names. If we had not included 'cm0' in the dimension map then the cell measure’s dimension would have initialized by the default values ['dim0', 'dim1'] and these two new axes would have created in addition to 'dim21', and 'dim3'.

Domain methods

analyse
attach_to_transform	Attach a coordinate construct to a transform.
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.
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.
equal_transform	Parameters:
equals	True if two domains are equal, False otherwise.
equivalent	True if and only if two domain are logically equivalent.
equivalent_transform	Parameters:
expand_dims	Expand the domain with a new dimension in place.
finalize	Returns:
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_cm	Insert a cell measure 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_transform	Insert a transform construct 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_cm_identifier	Return a new, unique cell measure identifier for the domain.
new_transform_identifier	Return a new, unique transform 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.
transform_axes	Return the axes spanned by the coordinate inputs of a transform.