cf.Space

class cf.Space(public_attributes={}, private_attributes={})

Bases: cf.space.Variable

Represent a space construct according to the CF data model.

Refer to the Variable class for details.

Refer to the cf module for details on data access by indexing and data storage.

Parameters:

• public_attributes (dict) – Optional. The new instance is given the public attributes named and valued from the key, value pairs of this dictionary. The values are deep copied.
• private_attributes (dict) – Optional. The new instance is given the private attributes named and valued from the key, value pairs of this dictionary. The values are deep copied.

Reserved public attributes:

In addition to the special private attributes inherited from the Variable class, the following private attributes have special definitions and it is recommended to set them accordingly.

Attribute	Description
cell_methods	The space’s CellMethods object.
grid	The space’s Grid object.

Methods and attributes defined here:

Units

The variable’s Units object.

array

Create a numpy array deep copy of the data.

If the data was stored as a file pointer then it will be changed in-place to be stored as a numpy array.

Returns:A numpy array.

Examples:

>>> a = x.array
>>> type(a)
<type 'numpy.ndarray'>
>>> a = x.array[[0,1]]
>>> type(a)
<type 'numpy.ndarray'>
>>> a.shape
(2,)

calendar

The variable’s CF ‘calendar’ public attribute.

cell_methods

The space’s CellMethods object.

coord(name, role=None, key=False, exact=False)

Find a coordinate of the space’s grid by name. Refer to cf.Grid.coord for details.

copy(data=True)

Return a deep copy.

Parameters:data (bool) – Optional. If False then assign the output variable’s data elements to None, with the expectation that they will be replaced subsequently. The data object’s metadata are deep copied in any case. Returns:A deep copy.

delpriv(attr)

Delete a private attribute.

Parameters:attr (str) – The name of the private attribute to be deleted. Returns:None

delpub(attr)

Delete a public attribute.

Parameters:attr (str) – The name of the public attribute to be deleted. Returns:None

dtype

Data-type of the data’s elements.

Returns:A numpy dtype object.

dump(id=None, omit=())

Return a string containing a full description of the space.

Parameters:

• id – Optional. Set the common prefix of variable component names. If None then defaults to the class name.
• id – str
• omit (sequence) – Optional. Omit the given attributes the description.

Returns:

A string containing the description of the space.

See also

cf.dump

eextract(**kwargs)

Return the variable if and only if it matches conditions on its phenomena, i.e. its public attributes and, if it has any, its scalar or 1-d, size 1 coordinates. As extract, but with the restriction that only exact public attribute or coordinate names are allowed.

keyword **kwargs: The keyword arguments identify exact phenomenon

names, either a public attribute names or 1-d, size 1 coorinate standard names.

The keyword values are as for match.

Returns:The variable if the it matches the criteria, otherwise a ValueError is raised.

ematch(**kwargs)

Determine whether or not a variable matches conditions on its phenomena, i.e. its public attributes and, if it has any, its scalar or 1-d, size 1 coordinates. As match, but with the restriction that only exact public attribute or coordinate names are allowed.

Parameters:**kwargs –

The keyword arguments identify exact phenomenon names, either a public attribute names or 1-d, size 1 coorinate standard names.

The keyword values are as for match.

Returns:True if the variable matches the criteria, False otherwise.

Examples:

>>> s
<CF Space: air_temperature(19, 30, 24)>
>>> s.standard_name
'air_temperature'
>>> s.extract(standard_name = 'air_temperature')
True
>>> s.extract(standard_n = '^air.*')
False

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

Return True if the variable is congruent to another variable in that

1. They have identical data. Pointers to data on disk may be converted to numpy arrays in memory if required.
2. They have identical reserved public attributes.
3. They have identical public attributes.

Equality of numbers is to within a tolerance. Refer to cf for details.

Parameters:

• other (object) – The variable to compare against for equality.
• atol (None or float) – Optional. If None then use the default method for setting the absolute tolerance for numerical equality (refer to cf for details). If a number then set the absolute tolerance to this value for all such comparisons.
• rtol (None or float) – Optional. If None then use the default method for setting the relative tolerance for numerical equality (refer to cf for details). If a number then set the relative tolerance to this value for all such comparisons.

Returns:

True if the two objects are congruent, False otherwise.

Examples:

>>> y = x
>>> x.equals(y)
True
>>> y = x + 1
>>> x.equals(y)
False
>>> y -= 1
>>> x.equals(y)
True
>>> x.setpub('name', 'name0')
>>> y.setpub('name', 'name1')
>>> x.equals(y)
False

extract(**kwargs)

Return the variable if and only if it matches conditions on its phenomena, i.e. its public attributes and, if it has any, its scalar or 1-d, size 1 coordinates. Unambiguous abbreviations of public attribute or coordinate names are allowed.

Refer to match for further details.

keyword **kwargs: The keyword arguments identify a public attribute’s

name or a coordinate’s standard name. Any unambiguous abbreviation of the phenomenon’s name is acceptable.

The keyword values are as for match.

Returns:The variable if the it matches the criteria, otherwise a ValueError is raised.

first_datum

Return the first element of the data without replacing a file pointer with a numpy array.

Returns:The scalar value of the first element of the data.

getpriv(attr, *default)

Return a private attribute.

Parameters:

• attr (str) – The name of the private attribute to be returned.
• default (object) – Optional. Return default if the requested private attribute has not been set

Returns:

The value of a private attribute.

getpub(attr, *default)

Return a public attribute.

Parameters:

• attr (str) – The name of the public attribute to be returned.
• default (object) – Optional. Return default if the requested public attribute has not been set

Returns:

The value of a public attribute.

grid

The space’s Grid object

istime()

last_datum

Return the last element of the data without replacing a file pointer with a numpy array.

Returns:The scalar value of the last element of the data.

long_name

The variable’s CF ‘long_name’ public attribute.

match(**kwargs)

Determine whether or not a variable matches conditions on its phenomena, i.e. its public attributes and, if it has any, its scalar or 1-d, size 1 coordinates. Unambiguous abbreviations of public attribute or coordinate names are allowed.

The phenomena and their conditions are specified with **kwargs parameters.

The variable matches the conditions if and only if it contains all of the specified phenomena and they satisfy all of their given criteria. A variable always matches no criteria.

Parameters:**kwargs –

The keyword arguments identify a public attribute’s name or a coordinate’s standard name. Any unambiguous abbreviation of the phenomenon’s name is acceptable.

A keyword’s value may be one of the following:

1. A number. A match requires that a numeric valued phenomenon equals the number using the numerically tolerant equality.
2. A string. A match requires that a string-valued phenomenon passes a regular expression match on the string. The string may contain regular expression special characters. To avoid ambiguities, it is assumed that the regular expression string matches the whole of the phenomenon string, i.e. the regular expression special characters ^ and $ are assumed if not given.
3. A sequence of numbers or strings. A match requires that a numeric phenomenon equals, within numerical tolerance, at least one of the sequence’s elements or a string-valued phenomenon passes a regular expression match for at least one string in the sequence (see 2.).
4. A Comparison object. A match requires that the comparison for the phenomenon evaluates to True.

Returns:True if the variable matches the criteria, False otherwise.

Examples:

>>> s
<CF Space: air_temperature(19, 30, 24)>
>>> s.pub('standard_name'), s.pub('units')
('air_temperature', 'K')
>>> s.extract(standard_name = 'air_temperature')
True
>>> s.extract(standard = '^air.*')
True
>>> s.extract(standard_name = lt('b'))
True
>>> s.extract(standard_name = outside('b', 'p'))
True
>>> s.extract(standard = ['.*temp.*', 'pressure'])
True
>>> s.extract(height = 2.0, units = 'K')
True

missing_value

x.missing_value <==> x._FillValue

name(long=False, ncvar=False, default=None)

Return the standard_name attribute of the variable.

If there is no standard_name attribute then return one of the long_name attribute, the ncvar attribute or the value of the default parameter, depending on the values of the parameters.

Parameters:

• long (bool) – Optional. If True, return the long_name if standard_name does not exist.
• ncvar (bool) – Optional If True, return ncvar if neither standard_name not long_name have already been returned.
• default (None or object) – Optional. Return default if standard_name, long_name nor ncvar have already been returned.

Returns:

The name of the variable.

ndim

Number of data dimensions.

Equivalent to the number of elements in shape tuple.

Returns:A non-negative integer

priv(*args, **kwargs)

A method which may be used in place of getpriv or setpriv.

If called with positional parameters, then they are interpreted as for getpriv and a public attribute (or default) value is returned.

If called with a keyword parameter, then the keyword and its value act as the two positional parameters of setpriv and a public attribute is set.

privattrs

Return a dictionary of the instance’s private attributes.

pub(*args, **kwargs)

A method which may be used in place of getpub or setpub.

If called with positional parameters, then they are interpreted as for getpub and a public attribute (or default) value is returned.

If called with a keyword parameter, then the keyword and its value act as the two positional parameters of setpub and a public attribute is set.

Examples:

>>> v.pub(units='K')
>>> v.pub('units')
'K'
>>> v.pub('UNITS', 'default_value')
'default_value'

pubattrs

Return a dictionary of the instance’s public attributes.

reverse_axes(*names)

Reverse the direction of named axes IN PLACE. The reverse does not actually occur until the data are accessed.

setpriv(attr, value)

Set a private attribute.

Parameters:

• attr (str) – The name of the private attribute to be set.
• value (object) – Optional. The value for the private attribute.

Returns:

None

setpub(attr, value)

Set a public attribute.

Parameters:

• attr (str) – The name of the public attribute to be set.
• value (object) – Optional. The value for the public attribute.

Returns:

None

shape

Tuple of the data’s dimension sizes.

Returns:A tuple

size

Number of elements in the data.

Equivalent to the product of the data’s dimension sizes.

Returns:A non-negative integer

slice

Slice the space’s data, returning a new space. The space’s grid is also sliced.

Refer to the ‘Copying and resizing’ in the cf package.

Coordinates are identified by keyword parameters of their standard names. If the optional first positional argument exact evaluates to False (the default) then unambiguous abbreviations of the standard names are accepted, otherwise exact standard names are required:

>>> s.slice(longitude=0.0)
<CF Space: air_temperature(12, 64, 1)
>>> s.slice(lon=0.0)
<CF Space: air_temperature(12, 64, 1)
>>> s.slice(l=0.0)
ValueError: Can't identify coordinate from keyword 'l'
>>> s.slice(False, lon=0.0)
<CF Space: air_temperature(12, 64, 1)
>>> s.slice(True, lon=0.0)
ValueError: Can't identify coordinate from keyword 'lon'

The coordinate criteria are given by the keyword parameters values. Four different methods are available:

1. A scalar. The dimension is sliced where coordinate equals (using the coordinate’s == operator) the scalar value:

   >>> s.slice(lat=0.0)
   

2. A sequence. The dimension is sliced where the coordinate equals (using the coordinate’s == operator) the sequence’s elements. All elements of the sequence must be found in the coordinate, but the sequence may contain fewer elements than the coordinate’s data:

   >>> s.slice(lon=[0.0, 2.8125])
   

3. A Comparison object (as, for example, returned by the lt function). The dimension is sliced where the comparison for the coordinate evaluates to True:

   >>> s.slice(lat=cf.lt(0.0))
   

4. An numpy array of booleans with the same shape as the coordinate. The dimension is sliced where elements of this array are True:

   >>> s.slice(lat=s.coord('lat')<0.0)
   

If a coordinate is not identified with a keyword parameter then its dimension is returned unchanged.

The order in which coordinates are given in the parameter list is irrelevant.

A call with no keyword parameters is equivalent to indexing with an Ellipsis (...).

Examples:

>>> s.slice(lat=0.0, lon=0.0)
<CF Space: air_temperature(12, 1, 1)
>>> s.slice(lon=cf.lt(0.0), lon=[0, 2.8125])
<CF Space: air_temperature(12, 32, 2)
>>> s.slice(lon=[0, 1])
ValeuError: 'longitude' coordinate doesn't contain the value 1
>>> s.slice(lon=1)
ValueError: No indices found for 'longitude' coordinate

squash()

Squash axes IN PLACE. I.e. squeeze size 1 dimensions from the space and its dimension coordinates if and only if a size 1 dimension is not spanned by an auxuliary coordiante or a cell measures variable.

standard_name

The variable’s CF ‘standard_name’ public attribute.

type()

The types of the data stored in the variable’s Data object.

Returns:A list of type objects for each of the data elements.

Examples:

>>> v.type()
[<type 'netCDF4.Variable'>]
>>> v.slice[...]
>>> v.type()
[<type 'numpy.ndarray'>]

units

The variable’s CF ‘units’ public attribute.

varray

Create a numpy view of the data.

If the data was stored as a file pointer then it will be changed in-place to be stored as a numpy array.

Note that making changes to elements of the returned view changes the underlying data. Refer to numpy.ndarray.view.

Returns:A numpy view.

Examples:

>>> a = x.varray
>>> print a
array([0, 1, 2, 3, 4])
>>> a[0] = 999
>>> print x.varray[0]
999
>>> a = 'a_different_object'
>>> print x.varray
array([999, 1, 2, 3, 4])