cf.Domain

class cf.Domain(dimension_sizes={}, dimensions={}, transform_map={}, dims=None, auxs=None, cms=None, trans=None, **kwargs)

Bases: cf.utils.CfDict

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 coordinate and cell measure constructs and store them as cf.Coordinate and cf.CellMeasure objects respectively.

It also has the following attributes:

Attribute	Description
dimension_sizes	The dimension constructs.
dimensions	Map which dimensions relate to each component of the domain.
transforms	The domain’s transform constructs stored as cf.Transform objects.

Initialization

Parameters :

kwargs : optional

Initialize coordinates, cell measures and transforms by setting key/value pairs exactly as for a built-in dict. Keys are dimension coordinate identifiers ('dimN'), auxiliary coordinate identifiers ('auxN'), cell measure construct identifiers ('cmN') and transform identifiers ('transN'), and values are cf.Coordinate, cf.CellMeasure and cf.Transform instances as appropriate.

The N part of each key identifier should be replaced by an arbitrary integer greater then or equal to zero, the only restriction being that the resulting identifier is not already in use by another coordinate or cell measure. No meaning should be inferred from the integer part of the identifiers, which need not include zero nor be consecutive. However, careful selection of dimension coordinate identifiers ('dimN') may prevent the need to set the dimensions parameter.

See also the dims, auxs, cms, trans and transform_map parameters.

dims : (sequence of) cf.Coordinate, optional

Initialize dimension coordinates from a scalar or a list. Identifiers will be automatically initialized as 'dim0', 'dim1', etc. for the first to the last dimension coordinates in the ordered sequence.

auxs : (sequence of) cf.Coordinate, optional

Initialize axuilliary coordinates from a scalar or a list. Identifiers will be automatically initialized as 'aux0', 'aux1', etc. for the first to the last axuilliary coordinates in the ordered sequence.

cms : (sequence of) cf.CellMeasure, optional

Initialize cell measures from a scalar or a list. Identifiers will be automatically initialized as 'cm0', 'cm1', etc. for the first to the last cell measures in the ordered sequence.

trans : (sequence of) cf.Transform, optional

Initialize transforms from a scalar or a list. Identifiers will be automatically initialized as 'trans0', 'trans1', etc. for the first to the last transform in the ordered sequence.

dimension_sizes : dict, optional

Initialize the dimensions by setting the dimension_sizes dictionary. 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 the dimension coordinate’s integer size.

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

Note that a dimension may be intialized which is not spanned by any of the given constructs.

dimensions : dict, optional

Initialize the mapping of which dimensions relate to each component of the domain by setting the dimensions dictionary. 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.

• 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') 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 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 dictionary key does not alter the default behaviour for other constructs.

Any dimension given by 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 containing 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.

transform_map : dict, optional

A dictionary mapping which transforms relate to which coordinates. Keys are transform identifiers ('transN') and values are a coordinate identifier ('dimN' or 'auxN'), or list of such identifiers, stating the coordinates to which the transforms relate.

The N part of each key identifier should be replaced by an integer greater then or equal to zero, such that the key is equal to a transform identifier that has been defined by the kwargs or trans parameters and each named coordinate identifier must have been defined with the kwargs, dims or auxs parameters.

Examples

In this example, .... refers to the appropriate initializations of the coordinates, cell measure and transform, which are omitted here for clarity.

>>> dim_coordA = cf.Coordinate(....)
>>> dim_coordB = cf.Coordinate(....)
>>> dim_coordA.size, dim_coordB.size, 
(73, 96)
>>> aux_coordA = cf.Coordinate(....)
>>> aux_coordA.shape
(96, 73)
>>> cell_measureA = cf.CellMeasure(....)
>>> cell_measureA.shape
(73, 96)
>>> transformA = cf.Transform(grid_mapping_name='latitude_longitude', ....)
>>> d = cf.Domain(dim0=dim_coordA, dim1=dim_coordB,
...               aux0=aux_coordA,
...               cm0=cell_measureA,
...               trans0=transformA,
...               dimensions={'aux0': ['dim1', 'dim0']}
...               transform_map={'trans0': 'aux0'})
...
>>> d.dimensions
{'aux0': ['dim1', 'dim0'],
 'cm0' : ['dim0', 'dim1'],
 'dim1': ['dim1'],
 'dim0': ['dim0']}
>>> d.transforms
{'trans0' : <CF Transform: latitude_longitude>}

Note that 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(dims=[dim_coordA, dim_coordB],
...               auxs=[aux_coordA],
...               cms=cell_measureA,
...               trans=transformA,
...               dimensions={'aux0': ['dim1', 'dim0']}
...               transform_map={'trans0': 'aux0'})

Here, note that we may specify an entry in the dimensions dictionary, even if the default behaviour aplies:

>>> d = cf.Domain(dims=[dim_coordA, dim_coordB],
...               aux0=aux_coordA,
...               cm0=cell_measureA,
...               trans=transformA,
...               dimensions={'aux0': ['dim1', 'dim0'],
...                           'cm0' : ['dim0', 'dim1']},
...               transform_map={'trans0': 'aux0'})

Here, the dimensions do not have default names ('dim0', 'dim1'), so it in this case it is necessary to specifiy all auxiliary coordinates and cell measures in the dimensions dictionary:

>>> d = cf.Domain(dim4=dim_coordA, dim12=dim_coordB,
...               auxs=aux_coordA,
...               cms=cell_measureA,
...               trans=(transformA,),
...               dimensions={'aux0': ['dim12', 'dim4'],
...                           'cm0' : ['dim4', 'dim12']},
...               transform_map={'trans0': 'aux0'})

In the last example, omitting the 'cm0' key from the dimensions dictionary would have been possible, but would have resulted in two new dimensions being created ('dim0', 'dim1' with sizes 73 and 96 respectively), which was not the intention in this case.

Domain attributes

dimension_sizes	A dictionary mapping the domain’s dimensions to their sizes.
dimensions	A dictionary mapping the domain’s components (including the field’s data array) to their dimensions.
transforms	A dictionary-like storing the domain’s transforms.

Domain methods

Undocumented methods behave exactly as their counterparts in a built-in dictionary.

analyse
aux_coords	Return a dictionary whose values are the auxiliary coordinates which span the given dimension and keys of the domain’s auxiliary coordinate identifiers.
cell_measures	Return a dictionary whose values are the cell measures which span the given dimension and keys of the cell measure identifiers.
clear
close	Close all referenced open data files.
coord	Return a coordinate of the domain.
coordinates	Return a dictionary mapping coordinate identifiers to their coordinates.
copy	Return a deep copy.
dim_coords	Return a dictionary whose values are the dimension coordinates which span the given dimension and keys of the domain’s dimension coordinate identifiers.
direction	Return True if a dimension is increasing, otherwise return False.
dump	Return a string containing a full description of the domain.
equals	True if two domains are equal, False otherwise.
expand_dims	Expand the domain with a new dimension in place.
get
get_keys	Return a list of the key names which match a regular expression.
has_key	Return true if and only if the dictionary contains the given key.
insert_aux_coordinate	Insert a new auxiliary coordinate into the domain in place, preserving internal consistency.
insert_cell_measure	Insert a new cell measure into the domain in place, preserving internal consistency.
insert_dim_coordinate	Insert a new dimension coordinate to the domain in place, preserving internal consistency.
insert_dimension	Insert a new dimension to the domain in place, preserving internal consistency.
insert_transform	Insert a new transform into the domain in place, preserving internal consistency.
items
itercell_measures	asdasdasdasdasdas
itercoordinates	asdasdasdasdasdas
iteritems
iterkeys
itervalues
keys
map_dims	Map the dimensions of two domains.
new_auxiliary_identifier	Return a new
new_cell_measure_identifier	Return a new
new_dimension_identifier	Return a new, unique dimension identifier for the domain.
new_transform_identifier	Return a new
pop	Remove specified key from the domain in-place and return the corresponding value.
popitem
remove_cell_measure	Remove a cell measure from the domain in place, preserving internal consistency.
remove_coordinate	Remove a coordinate from the domain in place, preserving internal consistency.
remove_dimension	Remove a dimension from the domain in place, preserving internal consistency.
remove_transform	Remove a transform from the domain in place, preserving internal consistency.
setdefault
squeeze	Remove a size 1 dimension from the domain in place.
update
values