cf.Variable

class cf.Variable(**kwargs)

Bases: object

Base class for a space and its components.

The following objects are all subclasses of Variable: a space, a coordinate, coordinate bounds and cell measures.

Refer to the cf module for more details.

argument **kwargs:  The new variable is given attributes named by the keywords, whose values are deep copies the keyword values.

Overloaded operators

Refer to cf.

Attribute	(type) Description
array	(numpy.ndarray) A numpy array deep copy of the data.
dtype	(numpy.dtype) Describes the format of the elements in the data array (refer to numpy.ndarray.dtype).
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.
_atol	(NoneType or float) Optional. Absolute tolerance for numeric equality. Unset is equivalent to None, which implies a default value. Refer to cf.
_rtol	(NoneType or float) Optional. Relative tolerance for numeric equality. Unset is equivalent to None, which implies a default value. Refer to cf.

Method	Description
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.

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

copy(shallow=(), omit=())

Create a deep copy of the variable, but with shallow copies of selected attributes.

If a deep copy of a variable’s attribute raises an exception then a shallow copy is attempted. If the shallow copy also raises an exception then the variable’s attribute is assigned to the returned copy.

In particular, netCDF4.Variable instances are copied by assignment.

Parameters:

• omit (sequence) – Optional. A collection of the variable’s attribute names which are not to be copied to the new variable. Supersedes duplicate entries in the shallow sequence.
• shallow (sequence) – Optional. A collection of the variable’s attribute names which are to be shallow copied, as opposed to deep copied.

Returns:

A deep copy of the variable with the exceptions of those attributes given by the shallow argument.

dtype

Data-type of the data’s elements.

Returns:A numpy dtype object.

dump(id=None, nc=False, 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.
• nc (bool) – Optional. If True then include attributes whose names begin “nc”.
• omit (sequence) – Optional. Omit the given attributes from the description.

Returns:

A string containing the description of the variable.

See also

cf.dump()

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

Return True if the variable is congruent to another variable in that they have identical data, property names (as returned by the properties() method) and corresponding property values.

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 equality of real numbers (refer to cf for details). If a float then set the absolute tolerance to this value for all comparisons (refer to the override parameter).
• override (bool) – Optional. If False then only use a float value of the rtol or atol parameters if it can not be set from attributes of the objects being compared.
• rtol (None or float) – Optional. If None then use the default method for setting the relative tolerance for equality of real numbers (refer to cf for details). If a float then set the relative tolerance to this value for all comparisons (refer to the override parameter).

Returns:

True if the two objects are congruent, False otherwise.

Examples

>>> y = x
>>> x.equals(y)
True
>>> y =x()
>>> y[...] = y.varray + 1
>>> x.equals(y)
False
>>> y[...] = y.varray - 1
>>> x.equals(y)
True
>>> y.standard_name += '_different'
>>> x.equals(y)
False

extract(exact=False, **kwargs)

Determine whether or not the variable matches conditions on its phenomena.

The variable’s phenomena are its attributes and, if it has any, its size 1 coordinates.

The phenomenon and its conditions are specified with **kwargs parameters.

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

Parameters:

• exact (bool) – Optional If True then the remaining keyword arguments given by **kwargs are assumed to be unambiguous exact matches for a phenomenon names, as opposed to an unambiguous abbreviations.
• **kwargs –

  The remaining keyword arguments may be any unambiguous abbreviation of any phenomenon name, either an attribute name or the standard_name of a coordinate. This behaviour is modified by the exact keyword.

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

  1. A number. A match requires that a numeric phenomenon equals the number using the variable’s == operator.
  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 at least one of the sequence’s elements (as in 1.) or a string-valued phenomenon passes a regular expression match for at least one string in the sequence (as in 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.standard_name
'air_temperature'
>>> 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(exact=True, standard_name = 'air_temperature')
True

>>> s.extract(exact=True, standard_ = 'air_temperature')
False
>>> s.extract(standard = ['temp', 'pressure'])
False
>>> s.extract(standard_name = inside('o', 'p'))
False

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.

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.

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.

ncatts()

Return a set of attributes which are netCDF attributes suitable for writing to a netCDF file.

All writable attributes are considered netCDF attributes except those starting with an underscore, (with the exception of ‘_FillValue’) and those starting with “nc”.

To create an attribute which will not be in the set of netCDF attributes, assign directly to the __dict__ dictionary as opposed to using setattr.

Returns:A set of attributes which are netCDF attributes.

ndim

Number of data dimensions.

Equivalent to the number of elements in shape tuple.

Returns:A non-negative integer

properties(nc=False)

Return a set of writable, public attribute names, excluding methods.

An attribute created by assigning directly to the __dict__ dictionary (as opposed to using setattr()) will not appear in this set.

Parameters:nc (bool) – If False then exclude attributes whose names begin “nc”. Returns:A set of attribute names.

repoint(test=False)

Reset the data to a file pointer if one is available, regardless of of whether the data is currently stored as a numpy array or not.

This may free memory, but any changes to data stored as a numpy array will be lost.

Parameters:test (bool) – Optional. If True then do not reinstate a file pointer if it exists. Returns:True if a file pointer exists, False otherwise.

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

type

The type of the data object.

Returns:A type object, or None if the variable has no data.

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