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 cf module for details on data access by indexing and data storage.

Overloaded operators

Refer to Variable.

Parameters:**kwargs

The new instance is given attributes named by the keywords, whose values are deep copies the keyword values.

Attribute (type) Description
ancillary_variables (SpaceList) Optional. Contains other spaces comprising the variables described by a CF ancillary_variables string.
array (numpy.ndarray) A numpy array deep copy of the data.
bounds (CoordinateBounds) Optional The coordinate’s cell boundaries.
cell_methods (CellMethods) Optional. Contains the information from a CF cell_methods string parsed into a data structure. Refer to CellMethods for more details.
dtype (numpy.dtype) Describes the format of the elements in the data array (refer to numpy.ndarray.dtype).
grid (Grid) Optional. Describes the space’s dimensionality and contains the space’s dimension coordinates, auxiliary coordinates and cell measures. Refer to Grid for more details.
ncvar (str) Optional. Contains the name of the variable in the original netCDF file. If present when the space is written to a netCDF file, then used for the output netCDF variable name.
ndim (int) The data array’s number of dimensions (refer to numpy.ndarray.ndim).
shape (tuple) The shape of the data array (refer to numpy.ndarray.shape).
size (int) The number of elements in the data array (refer to numpy.ndarray.size).
transform (str) Optional. The key of a grid’s transform attribute which contains a transformation for this coordinate.
type (type) The type of the data object, which is either a numpy array or a file pointer.
varray (numpy.ndarray) A numpy view of the data.
Method Description
coord Return a coordinate identified by its name.
copy Create a copy.
dump Return a string containing a full description of the instances.
equals Determine whether two instances are congruent with each other.
extract Determine whether an instance matches phenomena criteria.
first_datum Return the first element of the data without replacing a file pointer with a numpy array.
last_datum Return the last element of the data without replacing a file pointer with a numpy array.
name Return the name (standard_name, long_name or ncvar).
ncatts Return the set of attributes which are netCDF attributes.
properties Return a set of writable, public attributes.
repoint Revert the data to a file pointer.
slice Slice a space with conditions on coordinate values.
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 ‘calendar’ public attribute.

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

Find a coordinate of the space’s grid by name.

The given name argument is an abbreviation for (or equal to if the exact parameter is True) its standard_name attribute. If the key parameter is True then return the coordinate’s grid key name. If a coordinate does not have standard_name attribute, then its :att`ncvar` attribute is used.

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

>>> s.coord('height').long_name
AttributeError: 'Coordinate' object has no attribute 'long_name'
>>> s.coord('hei').long_name = 'HEIGHT'
>>> s.coord('heigh').long_name
'HEIGHT'

Or a deep copy may be made with the coordinate’s copy method:

>>> h = s.coord('height').copy()
Parameters:
  • name (str) – The string to identify a coordinate by name.
  • exact (bool) – Optional. If True then assume that the value of the name argument is equal to exactly one coordinate’s name.
  • key (str) – Optional. Return the grid key name instead of the coordinate.
  • role (str or None) – Optional. Restrict the search to coordinates of the given role. Valid values are ‘dim’ and ‘aux’, for dimension and auxiliary coordinate types respectively. If None then both types of coordinates will be searched.
Returns:

If a coordinate has been identified, return either a Coordinate instance or, if the keys parameter is True, a grid key name string. otherwise, return None.

Examples:

>>> s.coord('lon')
<CF Coordinate: longitude(128)>
>>> s.coord('lon', key=True)
'dim2'
>>> s.coord('lonX', key=True)
None
>>> s.coord('lon', exact=True)
None
>>> s.coord('longitude', exact=True)
<CF Coordinate: longitude(128)>
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:
  • idOptional. 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 they have identical data, special attributes and 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.setcf('name', 'x')
>>> y.setcf('name', 'y')
>>> 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
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 ‘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)

Revsere axes IN PLACE

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

Return the instance’s slice object.

squash()

Squash axes IN PLACE

standard_name

The variable’s ‘standard_name’ public attribute.

type()

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

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

The variable’s ‘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])

Previous topic

cf.CfDict

Next topic

cf.Coordinate

This Page