Navigation

cf.Field

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

Bases: cf.field.Variable

Represent a field 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 attributes:

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

Attribute Description
cell_methods The field’s CellMethods object.
space The field’s Field 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.

x.calendar=value <==> x.setpub(‘calendar’, value) x.calendar <==> x.getpub(‘calendar’) del x.calendar <==> x.delpub(‘calendar’) x.calendar=value <==> x.Units.calendar=value x.calendar <==> x.Units.calendar del x.calendar <==> del x.Units.calendar

cell_methods

The field’s CellMethods object.

coord(standard_name=None, role=None, key=False, exact=False, axis=None, ncvar=None, long_name=None, position=None, **kwargs)

Find a field’s coordinate by name.

The given name argument is an abbreviation for (or equal to if the exact parameter is True) the standard name of desired coordinate If the key parameter is True then return the coordinate’s space key name instead of the Coordinate variable. If a coordinate does not have standard_name attribute, then name will be matched against its ncvar attribute is used.

Note that the returned coordinate is an object identity to the coordinate stored in the space 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 space 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 space 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 field.

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 field.

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 Field: 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.
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.
lon_name

The variable’s CF long_name public attribute.

long_name

The variable’s CF long_name public attribute.

mask
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 Field: 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

The variable’s CF missing_value public attribute.

Assigning a value to this attribute also assigns the same value to the _FillValue public attribute, if the latter has previously been defined.

name(long_name=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_name (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
override_Units(units)

Change the variable’s units in place without changing the variable’s data.

Parameters:units (Units) – The new units as a Units object.
Returns:None

Examples:

>>> v.Units
<CF Units: metre>
>>> v.varray
array([ 0.,  1.,  2.,  3.,  4.])

>>> v.override_Units(cf.Units('km'))
>>> v.Units
<CF Units: km>
>>> v.varray
array([ 0.,  1.,  2.,  3.,  4.])
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 field’s data, returning a new field. The field’s space 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 Field: air_temperature(12, 64, 1)
>>> s.slice(lon=0.0)
<CF Field: 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 Field: 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 Field: air_temperature(12, 1, 1)
>>> s.slice(lon=cf.lt(0.0), lon=[0, 2.8125])
<CF Field: 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
space

The field’s Space object

squash()

Squash axes IN PLACE. I.e. squeeze size 1 dimensions from the field and its dimension coordinates if and only if a size 1 dimension is not spanned by an auxuliary coordinate 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.

x.units=value <==> x.setpub(‘units’, value) x.units <==> x.getpub(‘units’) del x.units <==> x.delpub(‘units’) x.units=value <==> x.Units.units=value x.units <==> x.Units.units del x.units <==> del x.Units.units

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

Navigation

© Copyright 2012, David Hassell. Last updated on Mar 23, 2012. Created using Sphinx 1.0.7.