cf.Space

class cf.Space(*args, **kwargs)

Bases: cf.utils.CfDict

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

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

The space is a dictionary-like object whose key/value pairs identify and store the coordinate and cell measure constructs which describe it.

The dimensionality of the space’s components and its transforms are stored as attributes.

Initialization

The dimension_sizes, dimensions and transforms attributes are automatically initialized.

Parameters :

args, kwargs

Keys and values are initialized exactly as for a built-in dict. Keys are coordinate and cell measure construct identifiers (such as dim1, aux0, and cm2) and values are coordinate and cell measure instances as appropriate.

Space attributes

dimension_sizes	A dictionary of the space’s dimensions and their sizes.
dimensions	A dictionary of the space’s components (including the field’s data array) and their dimensions.
transforms	A dictionary-like object of the space’s transforms and their identifiers.

Space 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 space’s auxiliary coordinate identifiers.
cell_measures	Return a dictionary whose values are the cell measures which span the given dimension and keys of the space’s cell measure identifiers.
clear
coord	Return a coordinate of the space.
copy	Return a deep copy.
direction	Return True if a dimension is increasing, otherwise return False.
dump	Return a string containing a full description of the space.
equals	True if two spaces are equal, False otherwise.
expand_dims	Expand the space 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_coordinate	Insert a new dimension or auxiliary coordinate to the space in place.
items
iteritems
iterkeys
itervalues
keys
map_dims	Map the dimnesions of two spaces.
new_auxiliary	Return a new
new_dimension	Return a new
new_transform	Return a new
pop	Remove a coordinate or cell measure from the space in place and return it.
popitem
remove_coordinate	Remove a coordinate from the space in place.
setdefault
squeeze	Remove a size 1 dimension from the space in place.
update
values

analyse()

aux_coords(dim=None)

Return a dictionary whose values are the auxiliary coordinates which span the given dimension and keys of the space’s auxiliary coordinate identifiers.

Parameters :

dim : str, optional

The identifier of the dimension to be spanned. By default all dimensions are considered (so all auxiliary coordinates are returned).

Returns :

out : dict

The auxiliary coordinates and their identifiers.

Examples

>>> s.dimensions
{'data': ['dim0', 'dim1', 'dim2'],
 'dim0': ['dim0'],
 'dim1': ['dim1'],
 'dim2': ['dim2'],
 'dim3': ['dim3'],
 'aux0': ['dim1', 'dim2'],
 'aux1': ['dim0'],
 'aux2': ['dim2', 'dim1']}
>>> s.aux_coords()
{'aux0': <CF Coordinate: ...>,
 'aux1': <CF Coordinate: ...>,
 'aux2': <CF Coordinate: ...>}
>>> s.aux_coords('dim2')
{'aux0': <CF Coordinate: ...>,
 'aux2': <CF Coordinate: ...>}
>>> s.aux_coords('dim3')
{}

cell_measures(dim=None)

Return a dictionary whose values are the cell measures which span the given dimension and keys of the space’s cell measure identifiers.

Parameters :

dim : str, optional

The identifier of the dimension to be spanned. By default all dimensions are considered (so all cell measures are returned).

Returns :

out : dict

The cell measures and their identifiers.

Examples

>>> s.dimensions
{'data': ['dim0', 'dim1', 'dim2'],
 'dim0': ['dim0'],
 'dim1': ['dim1'],
 'dim2': ['dim2'],
 'cm0' : ['dim1', 'dim2'],
 'cm1' : ['dim1', 'dim2', 'dim3']}
>>> s.cell_measures()
{'cm0': <CF CellMeasure: ...>,
 'cm1': <CF CellMeasure: ...>}
>>> s.cell_measures('dim3')
{'cm1': <CF CellMeasure: ...>}
>>> s.cell_measures('dim0')
{}

coord(arg, role=None, key=False, exact=False, dim=False, one_d=False, maximal_match=True)

Return a coordinate of the space.

Note that the returned coordinate is an object identity to the coordinate stored in the space so, for example, a coordinate’s properties may be changed in-place:

>>> f.coord('height').long_name
AttributeError: Coordinate has no CF property 'long_name'
>>> f.coord('hei').long_name = 'HEIGHT'
>>> f.coord('heigh').long_name
'HEIGHT'

Parameters :

arg : str or dict or int

The identify of the coordinate. One of:

• A string containing (an abbreviation) of its standard name (such as ‘time’).
• A string containing its identifier in the space (such as ‘dim2’).
• A dictionary containing one or more (abbreviations of) property names and their values as its key/value pairs (such as {‘long_name’: ‘something’}). If two or more properties are specified then the returned coordinate must satisfy all criteria, unless maximal_match is False in which case the returned coordinate will satisfy all criteria at least one of the criteria.
• An integer given the position of a dimension in the space’s field’s data array.

exact : bool, optional

If True then assume that the value of a name given by arg is exact. By default it is considered to be an abbreviation.

key : bool, optional

Return the space’s identifier for the coordinate.

role : str, optional

Restrict the search to coordinates of the given role. Valid values are ‘dim’ and ‘aux’ for dimension and auxiliary coordinate constructs repectively. By default both types are considered.

Returns :

out : Coordinate or str or None

The coordinate or, if key is True, the coordinate’s identifier in the space or, if no unique coordinate could be found, None.

Examples

>>> s['dim2'].properties
{'_FillValue': None,
 'axis': 'X',
 'long_name': 'longitude',
 'standard_name': 'longitude',
 'units': 'degrees_east'}

>>> s.coord('longitude')
<CF Coordinate: longitude(360)>
>>> s.coord('longitude', exact=True)
<CF Coordinate: longitude(360)>
>>> s.coord('lon')
<CF Coordinate: longitude(360)>
>>> s.coord('long', key=True)
'dim2'

>>> s.coord('lon', exact=True)
None
>>> s.coord('lonX')
None

copy()

Return a deep copy.

Equivalent to copy.deepcopy(d).

Returns :

out :

The deep copy.

Examples

>>> d.copy()

direction(dim)

Return True if a dimension is increasing, otherwise return False.

A dimension is considered to be increasing if its dimension coordinate values are increasing in index space or if it has no dimension coordinate.

The direction is taken directly from the appropriate coordinate’s Data object, if available. (This is because we can assume that the space has been finalized.)

Parameters :

dim : str

The identifier of the dimension (such as ‘dim0’).

Returns :

out : bool

Whether or not the dimension is increasing.

Examples

>>> s.dimension_sizes
{'dim0': 3, 'dim1': 1, 'dim2': 2, 'dim3': 2, 'dim4': 99}
>>> s.dimensions
{'dim0': ['dim0'],
 'dim1': ['dim1'],
 'aux0': ['dim0'],
 'aux1': ['dim2'],
 'aux2': ['dim3'],
}
>>> s['dim0'].array
array([  0  30  60])
>>> s.direction('dim0')
True
>>> s['dim1'].array
array([15])
>>> s['dim1'].bounds.array
array([  30  0])
>>> s.direction('dim1')
False
>>> s['aux1'].array
array([0, -1])
>>> s.direction('dim2')
True
>>> s['aux2'].array
array(['z' 'a'])
>>> s.direction('dim3')
True
>>> s.direction('dim4')
True

dump(id=None)

Return a string containing a full description of the space.

Parameters :

id : str, optional

Set the common prefix of component names. By default the instance’s class name is used.

Returns :

out : str

A string containing the description.

Examples

>>> x = s.dump()
>>> print s.dump()
>>> print s.dump(id='space1')

equals(other, rtol=None, atol=None, traceback=False)

True if two spaces are equal, False otherwise.

Equality is defined as follows:

• There is one-to-one correspondence between dimensions and dimension sizes between the two spaces.
• For each space component type (dimension coordinate, auxiliary coordinate and cell measures), the set of constructs in one space equals that of the other space. The component identifiers need not be the same.
• The set of transforms in one space equals that of the other space. The transform identifiers need not be the same.

Equality of numbers is to within a tolerance.

Parameters :

other :

The object to compare for equality.

atol : float, optional

The absolute tolerance for all numerical comparisons, By default the value returned by the ATOL function is used.

rtol : float, optional

The relative tolerance for all numerical comparisons, By default the value returned by the RTOL function is used.

traceback : bool, optional

If True then print a traceback highlighting where the two instances differ.

Returns :

out : bool

Whether or not the two instances are equal.

Examples

>>> s.equals(t)
True

expand_dims(coord=None, size=1)

Expand the space with a new dimension in place.

The new dimension may by of any size greater then 0.

Parameters :

coord : Coordinate, optional

A dimension coordinate for the new dimension. The new dimension’s size is set to the size of the coordinate’s array.

size : int, optional

The size of the new dimension. By default a dimension of size 1 is introduced. Ignored if coord is set.

Returns :

None

Examples

>>> s.expand_dims()
>>> s.expand_dims(size=12)
>>> c
<CF Coordinate: >
>>> s.expand_dims(coord=c)

get_keys(regex=None)

Return a list of the key names which match a regular expression.

Parameters :

regex : str, optional

The regular expression with which to identify key names. By default all keys names are returned.

Returns :

out : list

A list of key names.

Examples

>>> d.keys()
['dim2', 'dim0', 'dim1', 'aux0', 'cm0']
>>> d.get_keys()
['dim2', 'dim0', 'dim1', 'aux0', 'cm0']
>>> d.get_keys('dim')
['dim2', 'dim0', 'dim1']
>>> d.get_keys('^aux|^dim')
['dim2', 'dim0', 'dim1', 'aux0']
>>> d.get_keys('dim[1-9]')
['dim2', 'dim1']

has_key(key)

Return true if and only if the dictionary contains the given key.

Parameters :

key : hashable object

The key.

Returns :

out : bool

Examples

>>> d.keys()
['key1', 3, ('a', 1)]
>>> d.has_key(3)
True
>>> d.has_key('key9')
False

insert_coordinate(coord, dim_name_map=None, dim=False, aux=False, dimensions=None, space=None, key=None)

Insert a new dimension or auxiliary coordinate to the space in place.

Parameters :

coord : Coordinate

The new coordinate.

dim_name_map : dict, optional

dim : bool, optional

True if the new coordinate is to be a dimension coordinate.

aux : bool, optional

True if the new coordinate is to be an auxiliary coordinate.

dimensions : list

The ordered dimensions of the new coordinate. Ignored if the coordinate is a dimension coordinate. Required if the coordinate is an auxiliary coordinate.

space : Space, optional

Provide a space which contains both the new coordinate and its transforms, thus enabling transforms of the new coordinate to be included. By default, transforms of the new coordinate are not included.

key : str, optional

The identifier for the new coordinate. By default a unique identifier will be generated.

Returns :

None

Examples

>>>

map_dims(other)

Map the dimnesions of two spaces.

Return :out : dict

new_auxiliary()

Return a new

new_dimension()

Return a new

new_transform()

Return a new

pop(key, *default)

Remove a coordinate or cell measure from the space in place and return it.

Parameters :key : str Returns :out : Coordinate or CellMeasure

Examples

>>> s.pop('dim0')
>>> s.pop('aux1')
>>> s.pop('cm2')

remove_coordinate(key)

Remove a coordinate from the space in place.

Parameters :

key : str

The coordinate’s identifier.

Returns :

out : Coordinate or CellMeasure

Raises :

KeyError :

Examples

>>> s.remove_coordinate('dim0')
>>> s.remove_coordinate('aux1')

squeeze(dims)

Remove a size 1 dimension from the space in place.

If the dimension has a dimension coordinate then it is removed, as are 1-d auxiliary coordinates and cell measures which span the dimension. The dimension is squeezed from multidimensional auxiliary coordinates and cell measures if they span it.

The dimension is not squeezed from the field’s data array if it spans it, therefore the field’s data array may need to be squeezed concurrently.

Parameters :

dims : str or sequence of strs

The identifier of the dimension to remove.

Returns :

None

Examples

>>> s.dimension_sizes
{'dim0': 12, 'dim1': 73, 'dim2': 1}
>>> s.dimensions
{'data': ['dim0', 'dim1', 'dim2'],
 'aux0': ['dim1', 'dim2'],
 'aux1': ['dim2', 'dim1'],
 'dim0': ['dim0'],
 'dim1': ['dim1'],
 'dim2': ['dim2'],
 'cm0' : ['dim1', 'dim2']}
>>> s.squeeze('dim2')
>>> s.dimension_sizes
{'dim0': 12, 'dim1': 73}
>>> s.dimensions
{'data': ['dim0', 'dim1', 'dim2'],
 'aux0': ['dim1'],
 'aux1': ['dim1'],
 'dim0': ['dim0'],
 'dim1': ['dim1'],
 'cm0' : ['dim1']}

dimension_sizes

A dictionary of the space’s dimensions and their sizes.

Examples

>>> s.dimension_sizes
{'dim0': 1,
 'dim1': 73,
 'dim2': 96}

dimensions

A dictionary of the space’s components (including the field’s data array) and their dimensions.

>>> s.dimensions
{'aux0': ['dim1', 'dim2'],
 'aux1': ['dim2', 'dim1'],
 'cm0' : ['dim1', 'dim2'],
 'data': ['dim0', 'dim1', 'dim2'],
 'dim0': ['dim0'],
 'dim1': ['dim1'],
 'dim2': ['dim2']}

transforms

A dictionary-like object of the space’s transforms and their identifiers.

Examples

>>> s.transforms
{'trans0': <CF Transform: ocean_sigma_z_coordinate>,
 'trans1': <CF Transform: rotated_latitude_logitude>}
>>> isinstance(s.transforms, cf.CfDict)
True