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 attributes dimension_sizes, dimensions and transforms 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.

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'],
 '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: ...>}

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 CellMeasures: ...>,
 'cm1': <CF CellMeasures: ...>}
>>> s.cell_measures('dim3')
{'cm1': <CF CellMeasures: ...>}

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

Find a coordinate of the space by name. Refer to cf.Field.coord for details.

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 logically 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(k) → True if CFD has a key k, else 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

>>>

new_auxiliary()

Return a new

new_dimension()

Return a new

new_transform()

Return a new

remove_coordinate(key)

Remove a coordinate from the space in place.

Parameters :

key : str

The coordinate’s identifier.

Returns :

None

Examples

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

squeeze(dim)

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 :

dim : str

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 = None

The sizes of the space’s dimensions.

Examples

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

dimensions = None

The dimensions of each of the space’s components and of the its field’s data array.

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

transforms = None

The space’s transform constructs.

>>> s.transforms
{'trans0': <CF Transform: ocean_sigma_z_coordinate>
>>> type(s.transforms)
'cf.utils.CfDict'