Go to the cf-python home page
An implementation of the CF data model.
Provide the objects necessary to represent a space according to the CF data model, with functions for I/O and basic manipulation.
A space is composed as follows (ignoring attributes not composed from cf classes):
Space:* cell methods* ancillary variables* grid:* coordinates:* coordinate bounds* cell measures* transforms
All components of a space are optional. Coordinates and cell measures are key values of the grid dictionary and all other components are attributes. Refer to each class’s documentation for details.
Some of the objects contain data arrays, namely all objects derived from the base class Variable (spaces, coordinates, coordinate bounds and cell measures). The data storage, access and manipulation model is very similar for all of them. In the following description, ‘variable’ may refer to any such object and it will be noted when certain objects (usually a space) exhibit different behaviour.
When a variable is indexed, a new variable is created which is a deep copy of the original but with the data array sliced according to given indices. For a space, the grid is also sliced by applying each dimension’s slice to the appropriate grid elements.
A variable uses similar indexing to a numpy array:
>>> isinstance(v, Variable)
True
>>> v.shape
(10, 20, 30)
>>> v[0:5,...,slice(0,11,2)].shape
(5, 20, 6)
>>> v.shape
(10, 20, 30)
>>> v[:,:,numpy.arange(30) < 4].shape
(10, 20, 4)
The only differences to numpy array indexing are:
- More than one dimension’s slice may be a boolean array.
- A tuple (as well as a list) of indices for a single dimension is allowed.
Dimensions of size one resulting from a slice are discarded for a space but retained for other types:
>>> s
<CF Space: air_temperature(7070, 64, 128)>
>>> s[0]
<CF Space: air_temperature(64, 128)>
>>> c
<CF Coordinate: latitude(10, 20)>
>>> c[0]
<CF Coordinate: latitude(1, 20)>
Scalar data are not allowed in any case and are stored instead as size 1 arrays with at least one dimension:
>>> s[0,0,0]
<CF Space: air_temperature(1)>
>>> c[-1,-1]
<CF Coordinate: latitude(1, 1)>
Indexing a variable with an ellipsis or equivalent reads the data from disk (if required) before returning a deep copy of itself, and so both the original variable and its copy contain different numpy array objects in memory. It is, however, also possible to create a deep copy of a variable without altering the type of its data from a file pointer to a numpy array, which can enhance performance (see the ‘Storage’ section). There are three equivalent ways of doing this:
>>> w = v()
>>> w = v.copy()
>>> w = copy.deepcopy(v)
The difference between copying by one of these methods and copying by indexing is as follows:
>>> v.type
<type 'netCDF4.Variable'>
>>> w = v()
>>> w.type, v.type
(<type 'netCDF4.Variable'>, <type 'netCDF4.Variable'>)
>>> w = v[...]
>>> w.type, v.type
(<type 'numpy.ndarray'>, <type 'numpy.ndarray'>)
Note that a call to a space also allows arguments which create a slice of the space according to conditions on its coordinate values.
Assignment to the data array is done with the same indexing as for data access. Assignment can not change the shape of the data:
>>> v.shape
(10, 20, 30)
>>> v[0, 0, 0] = 273.15
>>> v.varray[0,0,0]
273.15
>>> v[0] = 273.15
>>> v.shape
(10, 20, 30)
>>> v[1,2,:] = range(30)
>>> v[...] = numpy.arange(6000).reshape(10, 20, 30)
The data may be stored as a numpy array or as a file pointer in the form of a netCDF4.Variable instance. Accessing the data makes no distinction between the two storage methods, but there are I/O, memory and speed performance issues to consider. If the data are a file pointer then accessing any part of the array will cause the entire array to be read from disk into memory and stored as a numpy array, replacing the original file pointer. Refer to read and write.
A variable’s repoint method will revert the data back to a file pointer if possible, freeing memory if no other variables are referring to the numpy array (or arrays).
The following operators, operations and assignments are overloaded in a variable to apply element-wise to the variable’s data numpy array.
Comparison operators:
==, !=, >, <, >=, <=
Binary arithmetic operations:
+, -, *, /, //, %, pow(), **, &, ^, |
Unary arithmetic operations:
-, +, abs(), ~
Augmented arithmetic assignments:
+=, -=, *=, /=, //=, %=, **=, &=, ^=, |=
Either side of an arithmetic operation may be a variable (in which case its data as a numpy array are used) or any object allowed by the equivalent numpy operation. Note that, as usual, if the left hand side object supports the operation with the right hand side then the returned object will be of former’s type:
>>> type(v)
<class 'cf.space.Space'>
>>> type(2.5 + v)
<class 'cf.space.Space'>
>>> type(v.varray + v)
<type 'numpy.ndarray'>
Apart from this exception, the unary and binary arithmetic operations return a new variable with modified data. The augmented arithmetic assignments change a variable’s data an in-place.
Numeric equalities for the == and != comparisons are determined to within a tolerance which may be adjusted.
All objects defined in cf have an equals method which determines the congruence of two instances. The aspects of this equality vary between objects, but for all objects numeric equalities are tested to within a tolerance defined by parameters ‘rtol’ (relative tolerance) and ‘atol’ (absolute tolerance), where two numbers a and b (from the left and right sides respectively of the comparison) are considered equal if:
|a - b| <= atol + rtol*|b|
Default tolerances are taken from the parameters DEFAULT_RTOL and DEFAULT_ATOL.
The values of these parameters may be overridden for any object by setting its _rtol and _atol attributes for relative and absolute tolerances respectively. Either of these attributes may be non-existent or None, which generally results in the default parameters being used. The only exception to this is if the object is an element of a CF iterable (see below).
In a comparison between objects x and y (x==y, for example), the values used for relative and absolute tolerances are the first found from each column of the following table:
| Relative tolerance | Absolute tolerance |
|---|---|
| x._rtol | x._atol |
| y._rtol | y._atol |
| DEFAULT_RTOL | DEFAULT_ATOL |
If the _rtol and _atol attributes of iterable CF objects (those subclassed from CfDict or CfList, such as SpaceList) exist, then they are used if and only if an element does not have its own numeric value of a tolerance parameter.
A grid contains any number of dimension coordinate constructs (or ‘dimensions’ for short), auxiliary coordinate constructs, cell measure constructs and transforms.
The grid must have dimensionality attributes (even if they are null, i.e. empty dictionaries) but all other components are optional.
The dimensions of the grid, and of its associated space, are given by the dimension_sizes and dimension attributes.
The dimension_sizes attribute is a dictionary whose keys are dimension identifiers and values are positive integer dimension sizes. A dimension identifier is the string ‘dim’ suffixed by an arbitrary, but unique, integer. For example:
>>> g
<CF Grid: (30, 24, 1, 17)>
>>> g.dimension_sizes
{'dim0': 1, 'dim1': 17, 'dim2': 30, 'dim3': 24}
The dimension attribute specifies which dimensions relate to each grid component (coordinates and cell measures) and to the data array of the space which holds the grid. For example:
>>> g.dimensions
{'data': ['dim1', 'dim2', 'dim3'],
'aux0': ['dim2', 'dim3'],
'aux1': ['dim2', 'dim3'],
'cm0' : ['dim2', 'dim3'],
'dim0': ['dim0'],
'dim1': ['dim1'],
'dim2': ['dim2'],
'dim3': ['dim3']}
Each value of this dictionary is an ordered list which corresponds to the shape of each component.
Note that if the grid contains dimensions of size 1 then the data of the space may have a lesser dimensionality then the grid (see the ‘data’ key in the above example).
Note that it is possible for a grid dimension to have no associated grid components.
Keys of the grid are identifiers for each of grid’s coordinate and cell measures variables. The key values are the variable objects themselves. The key names are strings which describe which type of variable they store. Recognized types are:
aux : Auxiliary coordinate cm : Cell measures dim : Dimension coordinate
A key string comprises one of these prefixes followed by a non-negative integer to discern between grid components of the same type. For example, a grid’s keys may be:
>>> sorted(g.keys())
['aux0', 'aux1', 'cm0', 'dim0', 'dim1', 'dim2', 'dim3']
The non-negative integer suffixing each key is arbitrary but must be unique amongst keys of the same type.
Note that, similarly to the storage of dimension coordinates in a netCDF file, a dimension coordinate’s dimension name must be the same as its grid identifier.
If a coordinate has an associated transform (such as projection parameters or a derived dimensional coordinate), then it will have a transform attribute whose value is a key of the grid’s transform attribute, which in turn is a CfDcit object (cf dictionary). The values of this cf dictionary are Transform objects which contain the information required to realise the transform. For example:
>>> g.transform['atmosphere_sigma_coordinate']
<CF Transform: atmosphere_sigma_coordinate transform>
>>> dump(g.transform['atmosphere_sigma_coordinate'])
atmosphere_sigma_coordinate transform
-------------------------------------
Transform['ps'] = <CF Space: surface_air_pressure(30, 24)>
Transform['ptop'] = <CF Space: ptop(1)>
Transform['sigma'] = 'dim0'
If a coordinate has a transform attribute but no data and no specified dimensions (i.e. its entry in the grid’s dimensions dictionary attribute is an empty list) then it should be considered a container for the coordinate implied by the named transform, should it be realized.
| Class (parent class) | Description |
|---|---|
| Variable(object) | Base class |
| Space(Variable) | Space |
| Coordinate(Variable) | Dimension or auxiliary coordinate |
| CoordinateBounds(Variable) | Coordinate bounds |
| CellMeasures(Variable) | Cell measures |
| CfDict(MutableMapping)) | Base class |
| Grid(CfDict)) | Grid |
| Transform(CfDict)) | Coordinate transforms |
| CfList(MutableSequence)) | Base class |
| VariableList(CfList)) | List of variables |
| SpaceList(VariableList) | List of spaces |
| CellMethods(CfList)) | Cell methods |
| Comparison(object) | Comparison expression |
Analogously to the above diagram of a space, the composition of a space may be cast in terms of the class of each space element type:
Space:* CellMethods* SpaceList* Grid:* Coordinate:* CoordinateBounds* CellMeasures* Transform
Note
Ancillary variables are stored in a SpaceList object
| Function | Description |
|---|---|
| dump | Print the string returned from an object’s dump method. |
| eq | Create a Comparison object. |
| equals | Determine whether two objects are congruent. |
| ge | Create a Comparison object. |
| gt | Create a Comparison object. |
| inside | Create a Comparison object. |
| le | Create a Comparison object. |
| lt | Create a Comparison object. |
| ne | Create a Comparison object. |
| outside | Create a Comparison object. |
| read | Read spaces from netCDF files. |
| read1 | Read a space from netCDF files. |
| write | Write spaces to a netCDF file. |
Print the full description of an object using its dump method.
This function is exactly equivalent to:
>>> print x.dump(...)
or, if the object has no dump method:
>>> print x
The parameters are only used if the object’s dump method is being utilized.
| Parameters: |
|
|---|---|
| Returns: | None |
Create a Comparison object for evaluating whether a variable is equal to the given value.
| Parameters: | value (object) – The value attribute in the returned Comparison object. |
|---|---|
| Returns: | A Comparison object whose relation attribute is set to the string “eq” and whose value attribute set to the value parameter. |
Ascertain if x equals y, assuming that they’re 1) space components, 2) numbers or 3) anything else, in that order.
dch
Create a Comparison object for evaluating whether a variable is greater than or equal to the given value.
| Parameters: | value (object) – The value attribute in the returned Comparison object. |
|---|---|
| Returns: | A Comparison object whose relation attribute is set to the string “ge” and whose value attribute set to the value parameter. |
Create a Comparison object for evaluating whether a variable is greater than the given value.
| Parameters: | value (object) – The value attribute in the returned Comparison object. |
|---|---|
| Returns: | A Comparison object whose relation attribute is set to the string “gt” and whose value attribute set to the value parameter. |
Create a Comparison object for evaluating whether a variable is inside the given range.
| Parameters: |
|
|---|---|
| Returns: | A Comparison object whose relation attribute is set to the string “inside” and whose value attribute set to the tuple (value0, value1). |
Create a Comparison object for evaluating whether a variable is less than or equal to the given value.
| Parameters: | value (object) – The value attribute in the returned Comparison object. |
|---|---|
| Returns: | A Comparison object whose relation attribute is set to the string “le” and whose value attribute set to the value parameter. |
Create a Comparison object for evaluating whether a variable is less than the given value.
| Parameters: | value (object) – The value attribute in the returned Comparison object. |
|---|---|
| Returns: | A Comparison object whose relation attribute is set to the string “lt” and whose value attribute set to the value parameter. |
Create a Comparison object for evaluating whether a variable is not equal to the given value.
| Parameters: | value (object) – The value attribute in the returned Comparison object. |
|---|---|
| Returns: | A Comparison object whose relation attribute is set to the string “ne” and whose value attribute set to the value parameter. |
Create a Comparison object for evaluating whether a variable is outside the given range.
| Parameters: |
|
|---|---|
| Returns: | A Comparison object whose relation attribute is set to the string “outside” and whose value attribute set to the tuple (value0, value1). |
Read spaces from netCDF files.
By default, all data arrays from all space components are not read from disk but are stored in the returned spaces as file pointers. This behaviour may be changed with the data parameter.
The netCDF dimension names are stored in the nc_dimensions attribute of a space’s grid and the netCDF variable names are stored in the ncvar attributes of the space and its grid components (coordinates, coordinate bounds, cell measures and transformations).
Note that if a single space has been requested by setting the index parameter and that space contains other spaces as part of a coordinate transformation or in a list ancillary variables, then the file in which the returned space resides will be scanned in its entirety so that these supplementary spaces may be located stored in the returned space.
| Parameters: |
|
|---|---|
| Returns: | A list of spaces (a SpaceList object) or, if and only if the index parameter is set to a non-negative integer, a space (Space object). |
See also
read1
Examples
>>> s = read('file.nc')
>>> type(s)
<class 'cf.space.SpaceList'>
>>> s
[<CF Space: pmsl(30, 24)>,
<CF Space: z-squared(17, 30, 24)>,
<CF Space: temperature(17, 30, 24)>,
<CF Space: temperature_wind(17, 29, 24)>]
>>> read('file.nc')[0:2]
[<CF Space: pmsl(30, 24)>,
<CF Space: z-squared(17, 30, 24)>]
>>> read('file.nc', units='K')
[<CF Space: temperature(17, 30, 24)>,
<CF Space: temperature_wind(17, 29, 24)>]
>>> read('file.nc').extract(units='K')
[<CF Space: temperature(17, 30, 24)>,
<CF Space: temperature_wind(17, 29, 24)>]
Note
read('file.nc', index=1) returns a list of spaces with one element whilst read('file.nc')[1] returns a space.
>>> read('file.nc', index=0)
[<CF Space: pmsl(30, 24)>]
>>> read('file.nc')[0]
<CF Space: pmsl(30, 24)>
>>> read1('file.nc')
<CF Space: pmsl(30, 24)>
>>> read('file.nc').units
['Pa', 'm2', 'K', 'K']
See also
Space.extract for more examples of space selection by phenomena criteria
Read the first matching space from netCDF files.
This function is exactly equivalent to calling the read function with the index argument set to 0. Refer to read for more details.
Note that if the first space contains other spaces as part of a coordinate transform or in a list ancillary variables, then these supplementary spaces will also be read from the file.
:argument files : Refer to read
:parameter data : Optional. Refer to read
| Parameters: |
|
|---|---|
| Returns: | A space. |
See also
read
Examples
>>> from cf import read, read1
>>> read('file.nc')
[<CF Space: pmsl(30, 24)>,
<CF Space: z-squared(17, 30, 24)>,
<CF Space: temperature(17, 30, 24)>
<CF Space: temperature_wind(17, 29, 24)>]
>>> read1('file.nc')
<CF Space: pmsl(30, 24)>
>>> read1('file.nc').extract(units='Pa')
True
>>> read1('file.nc').extract(units='K')
False
>>> read1('file.nc', units='K')
<CF Space: temperature(17, 30, 24)>
Write a space, or sequence of spaces, to a CF compliant netCDF file.
NetCDF dimension and variable names will be taken from the attributes ncvar and nc_dimensions if present, otherwise they are inferred from standard_name attributes or set to defaults. NetCDF names may be automatically given a numerical suffix to avoid duplication.
Output netCDF file global attributes are those which occur in the set of CF global attributes and non-standard data variable attributes and which have equal values across all input spaces.
It is possible to write only a subset of the input spaces by providing phenomena conditions with **kwargs parameters.
It does not matter if an input space’s data has not yet been read into memory. The write operation will automatically read the data array from disk if required, but the default is for it not to be saved in the input space if it had to be read during the write operation. However, if the data argument equals True then any input spaces which didn’t contain their full data arrays in memory will be changed in place so that they do. For example, for a space, s:
>>> s.type
<type 'netCDF4.Variable'>
>>> write(s, 'filename')
>>> s.type
<type 'netCDF4.Variable'>
>>> write(s, 'filename', data=True)
>>> s.type
<type 'numpy.ndarray'>
Identical grid components (as determined by their numerically tolerant equals methods) are only written to the file once, apart from when they need to fulfil both dimension coordinate and auxiliary coordinate roles for different data variables.
If a coordinate with a transform attribute is fully specified by another coordinate’s transformation then it will be not written to the file.
| Parameters: |
|
|---|
Examples
>>> s
[<CF Space: air_pressure(30, 24)>,
<CF Space: u_compnt_of_wind(19, 29, 24)>,
<CF Space: v_compnt_of_wind(19, 29, 24)>,
<CF Space: potential_temperature(19, 30, 24)>]
>>> write(s, 'file')
>>> write(s, 'file', standard_name = 'air_pressure')
See also
Space.extract for more examples of space selection by phenomena criteria.
Bases: cf.space.Variable
A CF cell measures object.
Refer to Variable for all details.
| Parameters: | **kwargs – Optional. refer to Variable |
|---|
Overloaded operators
Refer to Variable.
Methods
Refer to Variable.
Bases: cf.space.CfList
A CF cell methods object to describe the characteristic of a field that is represented by cell values.
Each cell method is stored in a dictionary and these dictionaries are stored in a list-like object. Similarly to a CF ‘cell_methods’ string, the order of cell methods in the list is important.
The dictionary representing each cell method recognizes the following keys (where all keys are optional; the referenced sections are from NetCDF Climate and Forecast (CF) Metadata Conventions Version 1.5; and words in double quotes (”...”) refer to CF cell_methods components in the referenced sections):
| Key | Value |
|---|---|
| method | A “method” component. Refer to section 7.3. |
| name | A list of all of the “name” components involved with the “method” component. Each element is either:
Option 3. only occurs if the cell method’s dimension either has no dimension coordinate or has a dimension coordinate with no standard_name. This is a deviation from the “name” components as described in sections 7.3, 7.3.1 and 7.3.4, in that standard_names are stored whenever possible, rather than only in the special cases described in section 7.3.4. Inspection of the ‘no_coords’ list retains the information required to fully interpret the cell method. |
| dim | A list of space dimension names corresponding to the ‘name’ list. A ‘name’ list value of ‘area’ always corresponds to a ‘dim’ list value of None. |
| no_coords | A list of booleans, corresponding to the ‘name’ list, indicating whether or not a particular cell method is relevant to the data in a way which may not be precisely defined by the corresponding dimension or dimensions. Refer to section 7.3.4. |
| interval | A list of “interval” component values corresponding to the ‘name’ list. Refer to section 7.3.2. |
| units | A list of “interval” component units corresponding to the ‘interval’ list. Refer to section 7.3.2. |
| comment | A “comment” or non-standardised information, component. Refer to sections 7.3.2 and 7.4 |
| within | A “within” climatology component. Refer to section 7.4. |
| over | An “over” cell portion or “over” climatology component. Refer to sections 7.3.3 and 7.4. |
| where | A “where” component. Refer to section 7.3.3. |
Note that the above table assumes that the cell methods have been constructed in the context of a space, the only way in which the ‘dim’ and ‘no_coords’ keys may take sensible values. If this is not the case, as would happen if the parse method were called without its space keyword, then elements of the ‘dim’ key default to False and elements of the ‘no_coords’ key default to None.
| Parameters: | sequence (sequence) – Optional. Initialize new list from sequence’s items. |
|---|
Examples
>>> c = CellMethods()
>>> c = c.parse('time: minimum within years time: mean over years (ENSO years)')
>>> print(c)
Cell methods : time: minimum within years
time: mean over years (ENSO years)
>>> list(c)
[
{'method' : 'minimum',
'name' : ['time'],
'dim' : [False],
'no_coords': [None],
'within' : 'years'
},
{'method' : 'mean'
'name' : ['time'],
'dim' : [False],
'no_coords': [None],
'comment' : 'ENSO years',
'over' : 'years'
}
]
>>> c = c.parse('lat: lon: standard_deviation')
>>> list(c)
[
{'dim' : [False, False],
'method' : 'standard_deviation'
'name' : ['lat', 'lon'],
'no_coords': [None, None],
}
]
Overloaded operators
Refer to CfList.
| Attribute | (type) Description |
|---|---|
| _atol | (None or float) Optional. Absolute tolerance for numeric equality. Unset is equivalent to None, which implies a default value. Refer to cf. |
| _elements_atts | (bool) If True then do not raise an exception when requesting a non-existent attribute, but broadcast the request to each element of the list. |
| _rtol | (None or float) Optional. Relative tolerance for numeric equality. Unset is equivalent to None, which implies a default value. Refer to cf. |
| Method | Description |
|---|---|
| append | As for a built-in list. |
| copy | Create a deep copy. |
| count | As for a built-in list but using numerically tolerant equality. |
| dump | Return a string containing a full description of the object. |
| equals | Determine whether two lists are congruent element-wise. |
| extend | As for a built-in list. |
| index | As for a built-in list but using numerically tolerant equality. |
| insert | As for a built-in list. |
| parse | Parse a netCDF(CF) cell_methods string. |
| pop | As for a built-in list. |
| properties | Return a set of writable, public attributes. |
| remove | As for a built-in list. |
| reverse | As for a built-in list. |
| sort | As for a built-in list. |
| strings | Convert each element to a string. |
Return a string containing a full description of the cell methods.
If a cell methods ‘name’ is followed by a ‘*’ then that cell method is relevant to the data in a way which may not be precisely defined its corresponding dimension or dimensions.
| Parameters: |
|
|---|---|
| Returns: | A string containing the description of the cell methods. |
See also
dump
Parse a CF cell_methods string into this CellMethods instance.
| Parameters: |
|
|---|---|
| Returns: | A cell methods list. |
Examples
>>> c = CellMethods()
>>> c = c.parse('time: minimum within years time: mean over years (ENSO years)')
>>> print c
Cell methods : time: minimum within years
time: mean over years (ENSO years)
Convert each element of the cell methods list to a netCDF(CF) cell_methods-like string.
Note that if the intention is to concatenate the output list into a string for creating a netCDF(CF) cell_methods attribute, then the cell methods “name” components may need to be modified, where appropriate, to reflect netCDF variable names. This is done automatically by the write function when creating a file on disk.
| Returns: | A built-in list of cell method strings. |
|---|
Examples
>>> c = CellMethods()
>>> c = c.parse('time: minimum within years time: mean over years (ENSO years)')
>>> print c
Cell methods : time: minimum within years
time: mean over years (ENSO years)
>>> c.strings()
['time: minimum within years',
'time: mean over years (ENSO years)']
Bases: _abcoll.MutableMapping
A dictionary-like object (a ‘cf dictionary’) suitable for storing CF structures.
| Parameters: |
|
|---|
| Attribute | (type) Description |
|---|---|
| _atol | (None or float) Optional. Absolute tolerance for numeric equality. Unset is equivalent to None, which implies a default value. Refer to cf. |
| _rtol | (None or float) Optional. Relative tolerance for numeric equality. Unset is equivalent to None, which implies a default value. Refer to cf. |
| Methods | Description |
|---|---|
| clear | As for a built-in dict. |
| copy | Create a deep copy. |
| equals | Determine whether two instances are congruent with each other. |
| get | As for a built-in dict. |
| get_keys | Return grid keys which match a pattern. |
| has_key | As for a built-in dict but using numerically tolerant equality. |
| items | As for a built-in dict. |
| iteritems | As for a built-in dict. |
| iterkeys | As for a built-in dict. |
| itervalues | As for a built-in dict. |
| keys | As for a built-in dict. |
| pop | As for a built-in dict. |
| popitem | As for a built-in dict. |
| properties | Return a set of writable, public attributes. |
| setdefault | As for a built-in dict. |
| update | As for a built-in dict. |
| values | As for a built-in dict. |
Overloaded operators
The in (set membership) operator is overloaded to use numerically tolerant equality.
Return True if two instances are congruent in that they have the equal sets of keys and for each key, the two values are equal.
Equality of numbers is to within a tolerance. Refer to cf for details.
| Parameters: |
|
|---|---|
| Returns: | True if the two objects are congruent, False otherwise. |
Return a list of the cf dictionary’s key names which, at their beginning, match the given regular expression.
| Parameters: | regex (str) – The regular expression with which to identify key names. A leading ‘^’ special character is assumed if not given. |
|---|---|
| Returns: | A list of keys names. |
Examples
>>> d.keys()
['dim2', 'dim0', 'dim1', 'aux0', 'cm0']
>>> d.get_keys('dim')
['dim2', 'dim0', 'dim1']
>>> d.get_keys('aux|dim')
['dim2', 'dim0', 'dim1', 'aux0']
>>> d.get_keys('dim[12]')
['dim2', 'dim1']
| Returns: | True if the key exists, using numerically tolerant equality. |
|---|
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. |
Bases: _abcoll.MutableSequence
A list-like object (a ‘cf list’) suitable for CF structures.
When requesting a non-private attribute that the cf list does not have, and the _elements_atts attribute is True, instead of raising an AttributeError a cf list is returned containing the values of the attribute from each of the elements, with a value of None if an element does not have the attribute. The setting of an attribute is as usual, i.e. it is set on the object itself rather that the object’s elements.
| Parameters: | sequence (iterable) – Optional. Initialize new list from sequence’s items. |
|---|
Overloaded operators
The in (set membership), == and != operators are overloaded to use numerically tolerant equality.
The +, *, += and *= operators behave as for a built-in list. Note in particular that in-place changes to an element of the result of one of these operations will affect the equivalent element on the right hand side, and possibly other equivalent elements in the result itself.
| Attribute | (type) Description |
|---|---|
| _atol | (None or float) Optional. Absolute tolerance for numeric equality. Unset is equivalent to None, which implies a default value. Refer to cf. |
| _elements_atts | (bool) If True then do not raise an exception when requesting a non-existent attribute, but broadcast the request to each element of the list. |
| _rtol | (None or float) Optional. Relative tolerance for numeric equality. Unset is equivalent to None, which implies a default value. Refer to cf. |
| Methods | |
|---|---|
| append | As for a built-in list. |
| copy | Create a deep copy. |
| count | As for a built-in list but using numerically tolerant equality. |
| equals | Determine whether two lists are congruent element-wise. |
| extend | As for a built-in list. |
| index | As for a built-in list but using numerically tolerant equality. |
| insert | As for a built-in list. |
| pop | As for a built-in list. |
| properties | Return a set of writable, public attributes. |
| remove | As for a built-in list. |
| reverse | As for a built-in list. |
| sort | As for a built-in list. |
Create a deep copy of the list. Equivalent to calling copy.deepcopy on the list.
| Returns: | A deep copy of the list. |
|---|
| Returns: | The number of occurrences of value using numerically tolerant equality. |
|---|
Return True if two instances are congruent in that each pair of their elements are equal.
Equality of numbers is to within a tolerance. Refer to cf for details.
| Parameters: |
|
|---|---|
| Returns: | True if the two objects are congruent, False otherwise. |
| Returns: | The first index of value using numerically tolerant equality. Restrict the search to the slice ‘start:stop’. If stop is None then the slice is ‘start:’. |
|---|
L.insert(index, object) – insert object before index
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. |
Bases: object
Create an object for storing a comparison expression.
A comparison expression comprises a relation (such as ‘less than’) and a value (any object capable of being related to with the standard comparison operators). These are stored in the relation and value attributes respectively.
The comparison is evaluated for an arbitrary object with the evaluate method.
Valid relations are:
| Relation | Description |
|---|---|
| lt | Strictly less than |
| le | Less than or equal |
| gt | Strictly greater than |
| ge | Greater than or equal |
| eq | Equals (within a tolerance) |
| ne | Not equal to (within a tolerance) |
| inside | Inside a given range (range bounds included) |
| outside | Outside a given range (range bounds excluded) |
| Parameters: | **kwargs – A keyword argument to the call is the relation of the comparison (any one of the relations listed above). The keyword’s argument is the object to test the comparison against. If the keyword argument is “inside” or “outside” then the value should be a two-element list or tuple. |
|---|
| Attribute | (type) Description |
|---|---|
| relation |
|
| value | (object) The object with which to compare. |
| Methods | |
|---|---|
| dump | Return a string containing a full description of the object. |
| evaluate | Evaluate the comparison for a given variable. |
Examples
>>> c = Comparison(le = 5)
>>> c.evaluate(4)
True
>>> c.evaluate(5)
True
>>> c = lt(5)
>>> c.evaluate(4)
True
>>> c = Comparison(inside = (1,2))
>>> a = numpy.arange(4)
>>> c.evaluate(a)
array([False, True, True, False], dtype=bool)
>>> (a >= 1) & (a <= 2)
array([False, True, True, False], dtype=bool)
Evaluate the comparison for a given object.
x : object
Typically a boolean or array of booleans. More generally, the output from the appropriate relation operators (==, !=, <, >, <=, >=) for the given variable, x.
Bases: cf.space.Variable
A CF coordinate object.
Refer to Variable, Grid and the cf module for details.
| Parameters: | **kwargs – The new variable is given attributes named by the keywords, whose values are deep copies the keyword values. |
|---|
| Attributes | (type) Description |
|---|---|
| array | (numpy array) A numpy array deep copy of the data. |
| bounds | (CoordinateBounds) Optional The coordinate’s cell boundaries. |
| climatology | (CoordinateBounds) Optional. A time coordinate’s climatological cell boundaries. |
| compress | (VariableList) Optional List of coordinates which are compressed by gathering into this coordinate’s single dimension. |
| dtype | (numpy.dtype) Describes the format of the elements in the data array (refer to numpy.ndarray.dtype). |
| ncvar | (string) 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 of ints) 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 array view) A numpy view of the data. |
| _atol | (None or float) Optional. Absolute tolerance for numeric equality. Unset is equivalent to None, which implies a default value. Refer to cf. |
| _rtol | (None or float) Optional. Relative tolerance for numeric equality. Unset is equivalent to None, which implies a default value. Refer to cf. |
| Methods | Description |
|---|---|
| copy | Create a copy. |
| dump | Return a string containing a full description of the coordinate. |
| equals | Determine whether two coordinates are congruent with each other. |
| extract | Determine whether a coordinate 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. |
Return a string containing a full description of the coordinate.
| Parameters: |
|
|---|---|
| Returns: | A string containing the description of the coordinate. |
See also
dump
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’); those starting with “nc”; and the bounds, climatology and transform attributes.
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. |
|---|
Reset the data of all coordinate components to a file pointers if they are all available, regardless of of whether the data are currently stored as a numpy arrays or not.
This may free memory, but any changes to data stored as a numpy arrays will be lost.
| Parameters: | test (bool) – Optional. If True then do not reinstate a file pointers if it exists. |
|---|---|
| Returns: | True if all file pointers of all coordinate components exist, False otherwise. |
Bases: cf.space.Variable
A CF coordinate bounds object.
Refer to Variable for all details.
| Parameters: | **kwargs – Optional. refer to Variable |
|---|
Overloaded operators
Refer to Variable.
Methods
Refer to Variable.
Bases: cf.space.CfDict
A CF grid object defining a space’s dimensionality, coordinates, cell measures and transformations in a dictionary-like object.
| Parameters: |
|
|---|
Overloaded operators
The in (set membership) operator is overloaded to use numerically tolerant equality.
| Attribute | (type) Description |
|---|---|
| dimension_sizes | (dict) See the ‘Grid dimensionality’ section. |
| dimensions | (dict) See the ‘Grid dimensionality’ section. |
| nc_dimensions | (dict) Optional. The netCDF dimension name for each dimension in the dimension_sizes attribute. If present when the grid is written to a netCDF file, then used for output netCDF dimension names. |
| transform | (dict) Optional. A cf dictionary of Transform objects referred to by grid coordinates with a transform attribute. See the ‘Transforms’ section for more details. |
| _atol | (None or float) Optional. Absolute tolerance for numeric equality. Unset is equivalent to None, which implies a default value. Refer to cf. |
| _rtol | (None or float) Optional. Relative tolerance for numeric equality. Unset is equivalent to None, which implies a default value. Refer to cf. |
| Methods | Description |
|---|---|
| clear | As for a built-in dict. |
| coord | : Return a coordinate identified by its name. |
| copy | Create a deep copy. |
| equals | Determine whether two instances are congruent with each other. |
| get | As for a built-in dict. |
| get_keys | Return grid keys which match a pattern. |
| has_key | As for a built-in dict but using numerically tolerant equality. |
| items | As for a built-in dict. |
| iteritems | As for a built-in dict. |
| iterkeys | As for a built-in dict. |
| itervalues | As for a built-in dict. |
| keys | As for a built-in dict. |
| pop | As for a built-in dict. |
| popitem | As for a built-in dict. |
| properties | Return a set of writable, public attributes. |
| setdefault | As for a built-in dict. |
| update | As for a built-in dict. |
| values | As for a built-in dict. |
Find a coordinate of the 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 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:
>>> g.coord('height').long_name
AttributeError: 'Coordinate' object has no attribute 'long_name'
>>> g.coord('hei').long_name = 'HEIGHT'
>>> g.coord('heigh').long_name
'HEIGHT'
Or a deep copy may be made with the coordinate’s copy method:
>>> h = g.coord('height').copy()
| Parameters: |
|
|---|---|
| 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
>>> g.coord('lon')
<CF Coordinate: longitude(128)>
>>> g.coord('lon', key=True)
'dim2'
>>> g.coord('lonX', key=True)
None
>>> g.coord('lon', exact=True)
None
>>> g.coord('longitude', exact=True)
<CF Coordinate: longitude(128)>
Return a string containing a full description of the grid.
| Parameters: |
|
|---|---|
| Returns: | A string containing the description of the grid. |
See also
dump
Return True if two instances are congruent in that, for each group of grid component types (dimension coordinate, auxiliary coordinate, cell measures, etc.) there are an equal number of keys and each key’s value equals a value in the other grid. Note that within a group of component types, the key names need not be the same.
Equality of numbers is to within a tolerance. Refer to cf for details.
| Parameters: |
|
|---|---|
| Returns: | True if the two objects are congruent, False otherwise. |
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.
Slicing a space instance with call arguments
A space is callable and keyword arguments may be used to define slices of the space’s data based on conditions on the space’s coordinate values, creating a new space whose data and grid are a subset of the original.
The keyword arguments are exactly as for the space’s slice method, i.e. for a space, s, s(...) is exactly equivalent to s.slice(...). Refer to the slice method for details and examples.
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. |
|---|
| Attributes | (type) Description |
|---|---|
| ancillary_variables | (SpaceList) Optional. Contains other spaces comprising the variables described by a CF ancillary_variables string. |
| array | (numpy array) 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 | (string) 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 of ints) 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 array view) A numpy view of the data. |
| _atol | (None or float) Optional. Absolute tolerance for numeric equality. Unset is equivalent to None, which implies a default value. Refer to cf. |
| _rtol | (None or float) Optional. Relative tolerance for numeric equality. Unset is equivalent to None, which implies a default value. Refer to cf. |
| Methods | 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. |
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 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: |
|
|---|---|
| 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)>
Return a string containing a full description of the space.
| Parameters: |
|
|---|---|
| Returns: | A string containing the description of the space. |
See also
dump
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’), those starting with “nc” and the grid attribute.
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. |
|---|
Reset the data of all space components to a file pointers if they are all available, regardless of of whether the data are currently stored as a numpy arrays or not.
This may free memory, but any changes to data stored as a numpy arrays will be lost.
| Parameters: | test (bool) – Optional. If True then do not reinstate a file pointer if it exists. |
|---|---|
| Returns: | True if all file pointers of all space components exist, False otherwise. |
Tuple of the data’s dimension sizes.
If the data originates from a file, the returned data dimensions may differ from the dimensions of the array on disk in that size one dimendef slicesions are not represented in the space’s data, unless the space’s data would otherwise be a scalar, in which case the shape is (1,).
| Returns: | A tuple of the data’s dimension sizes. |
|---|
Return a new space whose data and grid are a subset of the original by slicing the space where conditions on coordinate data values are met.
A coordinate and the conditions on its data are specified with **kwargs parameters.
If a coordinate is not specified, then its dimension is returned unchanged. A call with no parameters (kwargs = {}) is returns a deep copy of the space.
The order in which coordinates are given in the parameter list is irrelevant.
Unless the exact keyword is True, the coordinates identified in different space elements may vary. For example, the keyword ‘lon’ could identify the ‘longitude’ coordinate in one variable and ‘longwave’ in another.
| Parameters: |
|
|---|---|
| Returns: | A space. |
See also
__call__
Examples
>>> from cf import *
>>> s = read1('surface_air_temperature.nc')
>>> print s
Data : air_temperature(time, latitude, longitude)
Cell methods : time: mean (interval: 1.0 month)
Dimensions : time(7070) -> 450-11-16 00:00:00 to 1049-12-16 12:00:00
: latitude(64) -> -87.8638 to 87.8638 degrees_north
: longitude(128) -> 0 to 357.1875 degrees_east
: height(1) -> 2 m
Auxiliary coords:
>>> s
<CF Space: air_temperature(7070, 64, 128)>
>>> s.slice(lon = 0)
<CF Space: air_temperature(7070, 64)>
>>> s.slice(lon = [0, 45, 45.1])
<CF Space: air_temperature(7070, 64, 2)>
>>> s.slice(lon = numpy.arange(128)*2.8125)
<CF Space: air_temperature(7070, 64, 128)>
>>> s.slice(lon = s.coord('lon')<90)
<CF Space: air_temperature(7070, 64, 64)>
>>> s.slice(lon = 0, lat = gt(0))
<CF Space: air_temperature(7070, 32)>
>>> s.slice(longitude = 0, exact=True)
<CF Space: air_temperature(7070, 32)>
>>> s.slice(lon = 0, exact=True)
RuntimeError: Can not find dimension from keyword: lon
The next two commands are equivalent:
>>> s.slice(lon = lt(180))
<CF Space: air_temperature(7070, 64, 64)>
>>> s.slice(long = s.coord('lon')<180)
<CF Space: air_temperature(7070, 64, 64)>
The next two commands are equivalent:
>>> s.slice(lon = inside(90,135))
<CF Space: air_temperature(7070, 64, 17)>
>>> lon = s.coord('lon') ; s.slice(lon = (lon>=90) & (lon<=135))
<CF Space: air_temperature(7070, 64, 17)>
The next three commands are equivalent:
>>> s.slice()
>>> s.slice(**{})
>>> copy.deepcopy(s)
>>> s.copy()
Bases: cf.space.VariableList
A modified list for spaces supporting element-wise slicing, element-wise attribute retrieval and subsetting by phenomena criteria.
When requesting a non-private attribute that the cf list does not have, and the _elements_atts attribute is True, instead of raising an AttributeError a cf list is returned containing the values of the attribute from each of the elements, with a value of None if an element does not have the attribute. The setting of an attribute is as usual, i.e. it is set on the object itself rather that the object’s elements.
Slicing the space list returns a new space list with each element sliced with its slice method.
| Parameters: | sequence (iterable) – Optional. Initialize new list from sequence’s items. |
|---|
Overloaded operators
Refer to VariableList.
| Methods | |
|---|---|
| append | As for a built-in list. |
| copy | Create a deep copy. |
| count | As for a built-in list but using numerically tolerant equality. |
| dump | Return a string containing a full description of the each of the list’s elements. |
| equals | Determine whether two lists are congruent element-wise. |
| extend | As for a built-in list. |
| extract | Select list elements which match phenomena criteria. |
| index | As for a built-in list but using numerically tolerant equality. |
| insert | As for a built-in list. |
| pop | As for a built-in list. |
| properties | Return a set of writable, public attributes. |
| remove | As for a built-in list. |
| reverse | As for a built-in list. |
| sort | As for a built-in list. |
Examples
>>> from cf import *
>>> type(s)
<class 'cf.space.SpaceList'>
>>> s
[<CF Space: pmsl(30, 24)>,
<CF Space: temperature(17, 30, 24)>]
>>> s[slice(0,2)]
[<CF Space: pmsl(30, 24)>,
<CF Space: temperature(17, 30, 24)>]
>>> s[0]
<CF Space: pmsl(30, 24)>
>>> type(s[0])
<class 'cf.space.Space'>
>>> s[0].units
'Pa'
>>> s[-1].units
'K'
>>> s.units
['Pa', 'K']
>>> s.not_an_attribute
[None, None]
>>> s.extract(units = 'K')
[<CF Space: temperature(17, 30, 24)>]
>>> s.slice(lon = le(355))
[<CF Space: pmsl(30, 2)>,
<CF Space: temperature(17, 30, 2)>]
Return a new list of spaces in which each space element has been sliced according to conditions on coordinate data values. Refer to Space.slice.
A coordinate and the conditions on its data are specified with **kwargs parameters.
If a coordinate is not specified, then its dimension is returned unchanged in each space. A call with no parameters (kwargs={}) returns a deep copy of the list of spaces.
The order in which coordinates are given in the parameter list is irrelevant.
Unless the exact keyword is True, the coordinates identified in different space elements may vary. For example, the keyword ‘lon’ could identify the ‘longitude’ coordinate in one variable and ‘longwave’ in another.
| Parameters: |
|
|---|---|
| Returns: | A space list. |
Examples
>>> print s
Data : pressure(latitude_30, longitude)
Cell methods : time: mean
Dimensions : time(1) -> 1960-01-16 00:00:00
: latitude_30(30) -> -5.28 to 7.48 degrees_north
: longitude(24) -> 354.28 to 364.4 degrees_east
Auxiliary coords:
Data : u_compnt_of_wind(hybrid_sigma_pressure, latitude_29, longitude)
Cell methods : time: mean
Dimensions : time(1) -> 1960-01-16 00:00:00
: hybrid_sigma_pressure(19) -> 0.9970123 to 0.00460588 1
: latitude_29(29) -> -5.06 to 7.26 degrees_north
: longitude(24) -> 354.28 to 364.4 degrees_east
Auxiliary coords:
>>> s
[<CF Space: pressure(30, 24)>,
<CF Space: u_compnt_of_wind(19, 29, 24)>,
>>> s.slice(long = ge(360))
[<CF Space: pressure(30, 11)>,
<CF Space: u_compnt_of_wind(19, 29, 11)>]
Refer to Space.slice for more examples.
Bases: cf.space.CfDict
A CF transform object defining a coordinate’s transformation in a dictionary-like object.
The named parameters and their values of the transformation (i.e. the transformation’s mappings) comprise the object’s key-value pairs.
A transformation is equivalent to either a netCDF(CF) ‘formula_terms’ or ‘grid_mapping’ property. The latter is identified by the presence of the ‘grid_mapping_name’ key which contains the mapping’s name.
In the ‘formula_terms’ case, a mapping to a coordinate uses the coordinate’s grid key name as a value. A mapping to another space might be a shallow copy of another space in memory.
| Parameters: |
|
|---|
Overloaded operators
The in (set membership) operator is overloaded to use numerically tolerant equality.
| Attribute | (type) Description |
|---|---|
| transform_name | (str) Optional. The identifying name of the transformation. Typically a netCDF(CF) ‘formula_terms’ or ‘grid_mapping_name’. |
| _atol | (None or float) Optional. Absolute tolerance for numeric equality. Unset is equivalent to None, which implies a default value. Refer to cf. |
| _rtol | (None or float) Optional. Relative tolerance for numeric equality. Unset is equivalent to None, which implies a default value. Refer to cf. |
| Methods | Description |
|---|---|
| clear | As for a built-in dict. |
| copy | Create a deep copy. |
| equals | Determine whether two instances are congruent with each other. |
| get | As for a built-in dict. |
| get_keys | Return grid keys which match a pattern. |
| has_key | As for a built-in dict but using numerically tolerant equality. |
| items | As for a built-in dict. |
| iteritems | As for a built-in dict. |
| iterkeys | As for a built-in dict. |
| itervalues | As for a built-in dict. |
| keys | As for a built-in dict. |
| pop | As for a built-in dict. |
| popitem | As for a built-in dict. |
| properties | Return a set of writable, public attributes. |
| setdefault | As for a built-in dict. |
| update | As for a built-in dict. |
| values | As for a built-in dict. |
Examples
>>> t
<CF Transform: atmosphere_sigma_coordinate>
>>> dump(t)
atmosphere_sigma_coordinate transform
-------------------------------------
Transform['ps'] = <CF Space: surface_air_pressure(73, 96)>
Transform['ptop'] = 0.05
Transform['sigma'] = 'dim0'
>>> t
<CF Transform: rotated_latitude_longitude>
>>> dump(t)
rotated_latitude_longitude transformation
-----------------------------------------
Transform['grid_mapping_name'] = 'rotated_latitude_longitude'
Transform['grid_north_pole_latitude'] = 33.67
Transform['grid_north_pole_longitude'] = 190.0
Return a string containing a full description of the transformation.
| Parameters: |
|
|---|---|
| Returns: | A string containing the description of the object. |
See also
dump
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.
| Parameters: | **kwargs – The new variable is given attributes named by the keywords, whose values are deep copies the keyword values. |
|---|
Overloaded operators
Refer to cf.
| Attributes | (type) Description |
|---|---|
| array | (numpy array) 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 | (string) 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 of ints) 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 array view) A numpy view of the data. |
| _atol | (None or float) Optional. Absolute tolerance for numeric equality. Unset is equivalent to None, which implies a default value. Refer to cf. |
| _rtol | (None or float) Optional. Relative tolerance for numeric equality. Unset is equivalent to None, which implies a default value. Refer to cf. |
| Methods | 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. |
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,)
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: |
|
|---|---|
| Returns: | A deep copy of the variable with the exceptions of those attributes given by the shallow argument. |
Data-type of the data’s elements.
| Returns: | A numpy dtype object. |
|---|
Return a string containing a full description of the variable.
| Parameters: |
|
|---|---|
| Returns: | A string containing the description of the variable. |
See also
dump
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: |
|
|---|---|
| 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
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: |
|
|---|---|
| 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
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. |
|---|
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. |
|---|
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: |
|
|---|---|
| Returns: | The name of the variable. |
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. |
|---|
Number of data dimensions.
Equivalent to the number of elements in shape tuple.
| Returns: | A non-negative integer |
|---|
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. |
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. |
Tuple of the data’s dimension sizes.
| Returns: | A tuple |
|---|
Number of elements in the data.
Equivalent to the product of the data’s dimension sizes.
| Returns: | A non-negative integer |
|---|
The type of the data object.
| Returns: | A type object, or None if the variable has no data. |
|---|
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.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])
Bases: cf.space.CfList
A modified list for variables (any object which is subclass of Variable, such as a space, coordinate, etc.) supporting element-wise attribute retrieval and subsetting by phenomena criteria.
When requesting a non-private attribute that the cf list does not have, and the _elements_atts attribute is True, instead of raising an AttributeError a cf list is returned containing the values of the attribute from each of the elements, with a value of None if an element does not have the attribute. The setting of an attribute is as usual, i.e. it is set on the object itself rather that the object’s elements.
| Parameters: | sequence (iterable) – Optional. Initialize new list from sequence’s items. |
|---|
Overloaded operators
Refer to CfList.
Attributes
Refer to CfList
| Methods | |
|---|---|
| append | As for a built-in list. |
| copy | Create a deep copy. |
| count | As for a built-in list but using numerically tolerant equality. |
| dump | Return a string containing a full description of the each of the list’s elements. |
| equals | Determine whether two lists are congruent element-wise. |
| extend | As for a built-in list. |
| extract | Select list elements which match phenomena criteria. |
| index | As for a built-in list but using numerically tolerant equality. |
| insert | As for a built-in list. |
| pop | As for a built-in list. |
| properties | Return a set of writable, public attributes. |
| remove | As for a built-in list. |
| reverse | As for a built-in list. |
| sort | As for a built-in list. |
Return a string containing a full description of each variable in the list, utilizing each variable’s dump method.
| Parameters: |
|
|---|---|
| Returns: | A string containing the descriptions of each variable in the list. |
See also
dump
Return a subset of a list of variables by selecting only the variables which match conditions on their phenomena.
A variable’s phenomena are its attributes and, if it has any, its size 1 coordinates.
A phenomenon and its conditions are specified with **kwargs parameters.
A variable in the list 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 (kwargs={})
A match for a variable is determined by passing the criteria to the variable’s extract method.
Unless the exact keyword is True, the phenomena identified in different variable elements may vary. For example, the keyword ‘unit’ could identify the ‘units’ phenomenon in one variable and ‘unitary’ in another.
By default, the returned list of variables is a shallow copy of part of the original list (in the same way that a standard slice is). To return a list whose elements are deep copies, set the deep parameter to True.
| Parameters: |
|
|---|---|
| Returns: | A list of variables |
Examples
>>> s
[<CF Space: pressure(30, 24)>,
<CF Space: u_compnt_of_wind(19, 29, 24)>
>>> s.units
['hPa', 'm s-1']
>>> s.extract(units = 'm s-1')
[<CF Space: u_compnt_of_wind(19, 29, 24)>]
>>> t = s.extract(uni = 'm\s*s-1')
>>> t
[<CF Space: u_compnt_of_wind(19, 29, 24)>]
>>> t[0] is s[1]
True
>>> t = s.extract(uni = 'm\s*s-1', deep=True)
>>> t[0] is s[1]
False
Refer to Variable.extract for more examples.