cf.Variable

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

Bases: object

Base class for a space and its components.

Refer to the variable data storage, access and manipulation in the top level cf documentation for more details.

Parameters:

• public_attributes (dict) – Optional. The new variable 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 variable is given the private attributes named and valued from the key, value pairs of this dictionary. The values are deep copied.

Reserved attributes

The following attributes are reserved on the variable and may not be set.

Attribute	Description
array	A numpy array deep copy of the data.
dtype	Describes the format of the elements in the data array (refer to numpy.ndarray.dtype).
ndim	The data array’s number of dimensions (refer to numpy.ndarray.ndim).
shape	The shape of the data array (refer to numpy.ndarray.shape).
size	The number of elements in the data array (refer to numpy.ndarray.size).
varray	A numpy view of the data.

Special private attributes:

The following private attributes have special definitions and it is recommended to set them accordingly.

Attribute	Description
_data	The variable’s Data object.
ncvar	The variable’s netCDF variable name.
Units	The variable’s Units object. Setting this changes the calendar and units reserved public attributes, and vice versa.

Reserved public attributes:

The following public attributes have identical descriptions as in the CF convention and may be set directly on the instance as well as with the setpub or pub methods and retrieved directly from the instance as well as with the getpub or pub methods.

Attribute	Description
calendar	As in the CF convention.
_FillValue	As in the CF convention.
long_name	As in the CF convention.
missing_value	As in the CF convention.
standard_name	As in the CF convention.
units	As in the CF convention.

Methods:

A variable has the following methods.

Method	Description
copy	Create a deep copy of the variable.
dump	Return a string containing a full description of the variable.
equals	Determine whether two instances are congruent with each other.
match	Determine whether a variable 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 variable’s name.
type	The type of the data stored in the variable’s Data object.
pubattrs	Return a dictionary of the variable’s public attributes.
privattrs	Return a dictionary of the variable’s private attributes.
istime
ematch
extract
eextract
priv	Set or get a private attribute.
setpriv	Set a private attribute.
getpriv	Get a private attribute.
delpriv	Delete a private attribute.
pub	Set or get a public attribute.
setpub	Set a public attribute.
getpub	Get a public attribute.
delpub	Delete a public attribute.

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.

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

Parameters:

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

Returns:

A string containing the description of the variable.

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.

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.

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 variable’s data, returning a new variable.

Examples:

>>> v
<CF Variable: air_temperature(73, 96)>
>>> v.slice[0,0]
<CF Variable: air_temperature(1,1)>

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])