Bases: cf.variable.Variable
A CF cell measure construct containing information that is needed about the size, shape or location of the field’s cells.
It is a variable which contains a data array and metadata comprising properties to describe the physical nature of the data.
The name of spatial measure being represented is stored in the measure attribute.
Initialization
Parameters : |
|
---|
CellMeasure CF Properties
add_offset | The add_offset CF property. |
calendar | The calendar CF property. |
comment | The comment CF property. |
_FillValue | The _FillValue CF property. |
history | The history CF property. |
leap_month | The leap_month CF property. |
leap_year | The leap_year CF property. |
long_name | The long_name CF property. |
missing_value | The missing_value CF property. |
month_lengths | The month_lengths CF property. |
scale_factor | The scale_factor CF property. |
standard_name | The standard_name CF property. |
units | The units CF property. |
valid_max | The valid_max CF property. |
valid_min | The valid_min CF property. |
valid_range | The valid_range CF property. |
CellMeasure data attributes
array | A numpy array deep copy of the data array. |
Data | The Data object containing the data array. |
dtype | The numpy data type of the data array. |
_FillValue | The _FillValue CF property. |
first_datum | The first element of the data array. |
hardmask | Whether the mask is hard (True) or soft (False). |
isscalar | True if and only if the data array is a scalar array. |
last_datum | The last element of the data array. |
mask | The mask of the data array. |
ndim | Number of dimensions in the data array. |
shape | Tuple of the data array’s dimension sizes. |
size | Number of elements in the data array. |
Units | The Units object containing the units of the data array. |
varray | A numpy array view of the data array. |
CellMeasure miscellaneous attributes
hasData | True if and only if there is a data array. |
measure | The name of spatial measure being represented. |
properties | A dictionary of the CF properties. |
CellMeasure methods
binary_mask | Return a binary missing data mask of the data array. |
chunk | Partition the data array using Large Amounts of Massive Arrays (LAMA) |
clip | Clip (limit) the values in the data array in place. |
copy | Return a deep copy. |
cos | Take the trigonometric cosine of the data array in place. |
delprop | Delete a CF property. |
dump | Return a string containing a full description of the cell measure. |
equals | True if two variables are logically equal, False otherwise. |
expand_dims | axis is an integer |
flip | Flip dimensions of the data array in place. |
getprop | Get a CF property. |
hasprop | Return True if the variable has a CF property. |
identity | Return the cell measure’s identity. |
match | Determine whether or not a variable satisfies conditions. |
name | |
override_units | Override the data array units in place. |
setitem | Set selected elements of the data array in place. |
setmask | Set selected elements of the data array’s mask in place. |
setprop | Set a CF property. |
sin | Take the trigonometric sine of the data in place. |
squeeze | Remove size 1 dimensions from the data array in place. |
subset | Return the instance if it matches the given conditions. |
subspace | Return a new variable whose data is subspaced. |
transpose | Permute the dimensions of the data array in place. |
Return a binary missing data mask of the data array.
The binary mask’s data array comprises dimensionless 32-bit integers and has 0 where the data array has missing data and 1 otherwise.
Returns : |
|
---|
Examples
>>> print f.mask.array
[[ True False True False]]
>>> b = f.binary_mask().array
>>> print b.array
[[0 1 0 1]]
Partition the data array using Large Amounts of Massive Arrays (LAMA) functionality.
Parameters : | chunksize : int extra_boundaries : list pdim : list |
---|---|
Returns : | extra_boundaries, pdim : {list, list} |
Clip (limit) the values in the data array in place.
Given an interval, values outside the interval are clipped to the interval edges.
Parameters :
a_min : scalar
a_max : scalar
units : str or Units
Returns : | None |
---|
Examples
Return a deep copy.
Equivalent to copy.deepcopy(f).
Returns : |
|
---|
Examples
>>> g = f.copy()
Take the trigonometric cosine of the data array in place.
Units are accounted for in the calcualtion, so that the the cosine of 90 degrees_east is 0.0, as is the sine of 1.57079632 radians. If the units are not equivalent to radians (such as Kelvin) then they are treated as if they were radians.
The Units are changed to ‘1’ (nondimensionsal).
Returns : | None |
---|
Examples
>>> f.Units
<CF Units: degrees_east>
>>> print f.array
[[-90 0 90 --]]
>>> f.cos()
>>> f.Units
<CF Units: 1>
>>> print f.array
[[0.0 1.0 0.0 --]]
>>> f.Units
<CF Units: m s-1>
>>> print f.array
[[1 2 3 --]]
>>> f.cos()
>>> f.Units
<CF Units: 1>
>>> print f.array
[[0.540302305868 -0.416146836547 -0.9899924966 --]]
Delete a CF property.
Parameters : |
|
---|---|
Returns : | None |
Raises : |
|
Examples
>>> f.delprop('standard_name')
>>> f.delprop('foo')
AttributeError: Field doesn't have CF property 'foo'
Return a string containing a full description of the cell measure.
Parameters : |
|
---|---|
Returns : |
|
Examples
>>> x = c.dump()
>>> print c.dump()
>>> print c.dump(id='area_measure')
True if two variables are logically equal, False otherwise.
Parameters : |
|
---|---|
Returns : |
|
Examples
>>> f.equals(f)
True
>>> g = f + 1
>>> f.equals(g)
False
>>> g -= 1
>>> f.equals(g)
True
>>> f.setprop('name', 'name0')
>>> g.setprop('name', 'name1')
>>> f.equals(g)
False
>>> f.equals(g, ignore=set('name',))
True
axis is an integer dim is a string direction is a boolean
Flip dimensions of the data array in place.
Parameters : |
|
---|---|
Returns : |
|
Examples
>>> f.flip()
>>> f.flip(1)
>>> f.flip([0, 1])
>>> g = f[::-1, :, ::-1]
>>> f.flip([2, 0]).equals(g)
True
Get a CF property.
When a default argument is given, it is returned when the attribute doesn’t exist; without it, an exception is raised in that case.
Parameters : |
|
---|---|
Returns : |
|
Raises : |
|
Examples
>>> f.getprop('standard_name')
>>> f.getprop('standard_name', None)
>>> f.getprop('foo')
AttributeError: Field doesn't have CF property 'foo'
>>> f.getprop('foo', 'bar')
'bar'
Return True if the variable has a CF property.
Parameters : |
|
---|---|
Returns : |
|
Examples
>>> f.hasprop('standard_name')
True
>>> f.hasprop('foo')
False
Return the cell measure’s identity.
The idendity is the value of the measure attribute, or if that doesn’t exist the standard_name property or, if that does not exist, the id attribute.
Parameters : |
|
---|---|
Returns : |
|
Examples
Determine whether or not a variable satisfies conditions.
Conditions may be specified on the variable’s CF properties and attributes.
Parameters : |
|
---|---|
Returns : |
|
Examples
Override the data array units in place.
Not to be confused with setting the Units attribute to units which are equivalent to the original units.
This is different to setting the Units attribute, as the new units need not be equivalent to the original ones and the data array elements will not be changed to reflect the new units.
Parameters : |
|
---|---|
Returns : | None |
Examples
>>> f.Units
<CF Units: hPa>
>>> f.first_datum
100000.0
>>> f.override_units('km')
>>> f.Units
<CF Units: km>
>>> f.first_datum
100000.0
>>> f.override_units(cf.Units('watts'))
>>> f.Units
<CF Units: watts>
>>> f.first_datum
100000.0
Set selected elements of the data array in place.
The value to which the selected elements of the data array will be set may be any object which is broadcastable across the selected elements.
Note the following:
Parameters : |
|
---|---|
Returns : | None |
Examples
Set selected elements of the data array’s mask in place.
The value to which the selected elements of the mask will be set may be any object which is broadcastable across the selected elements. The broadcasted value may be of any data type but will be evaluated as boolean.
Unmasked elements are set to the fill value.
The mask may be effectively removed by setting every element to False with f.setmask(False).
Note that if and only if the value to be assigned is logically scalar and evaluates to True then f.setmask(value, indices) is equivalent to f.setitem(cf.masked, indices). This is consistent with the behaviour of numpy masked arrays.
Parameters : |
|
---|---|
Returns : | None |
Examples
Set a CF property.
Parameters : |
|
---|---|
Returns : | None |
Examples
>>> f.setprop('standard_name', 'time')
>>> f.setprop('foo', 12.5)
Take the trigonometric sine of the data in place.
Units are accounted for in the calculation. For example, the the sine of 90 degrees_east is 1.0, as is the sine of 1.57079632 radians. If the units are not equivalent to radians (such as Kelvin) then they are treated as if they were radians.
The Units are changed to ‘1’ (nondimensionsal).
Returns : | None |
---|
Examples
>>> f.Units
<CF Units: degrees_north>
>>> print f.array
[[-90 0 90 --]]
>>> f.sin()
>>> f.Units
<CF Units: 1>
>>> print f.array
[[-1.0 0.0 1.0 --]]
>>> f.Units
<CF Units: m s-1>
>>> print f.array
[[1 2 3 --]]
>>> f.sin()
>>> f.Units
<CF Units: 1>
>>> print f.array
[[0.841470984808 0.909297426826 0.14112000806 --]]
Remove size 1 dimensions from the data array in place.
Parameters : |
|
---|---|
Returns : | None |
Examples
>>> v.squeeze()
>>> v.squeeze(1)
>>> v.squeeze([1, 2])
Return the instance if it matches the given conditions.
Equivalent to:
def subset(f, *args, **kwargs):
if f.match(*args, **kwargs):
return f
raise ValueError('')
Parameters : |
|
---|---|
Returns : |
|
Raises : |
|
Permute the dimensions of the data array in place.
Parameters : |
|
---|---|
Returns : | None |
Examples
>>> v.transpose()
>>> v.ndim
3
>>> v.transpose([1, 2, 0])
The Data object containing the data array.
Examples
>>> f.Data
<CF Data: >
The Units object containing the units of the data array.
Stores the units and calendar CF properties in an internally consistent manner. These are mirrored by the units and calendar CF properties respectively.
Examples
>>> f.Units
<CF Units: K>
The add_offset CF property.
This property is only used when writing to a file on disk.
Examples
>>> f.add_offset = -4.0
>>> f.add_offset
-4.0
>>> del f.add_offset
>>> f.setprop('add_offset', 10.5)
>>> f.getprop('add_offset')
10.5
>>> f.delprop('add_offset')
A numpy array deep copy of the data array.
Changing the returned numpy array does not change the data array.
Examples
>>> a = f.array
>>> type(a)
<type 'numpy.ndarray'>
>>> print a
[0 1 2 3 4]
>>> a[0] = 999
>>> print a
[999 1 2 3 4]
>>> print f.array
[0 1 2 3 4]
The calendar CF property.
This property is a mirror of the calendar stored in the Units attribute.
Examples
>>> f.calendar = 'noleap'
>>> f.calendar
'noleap'
>>> del f.calendar
>>> f.setprop('calendar', 'proleptic_gregorian')
>>> f.getprop('calendar')
'proleptic_gregorian'
>>> f.delprop('calendar')
The comment CF property.
Examples
>>> f.comment = 'a comment'
>>> f.comment
'a comment'
>>> del f.comment
>>> f.setprop('comment', 'a comment')
>>> f.getprop('comment')
'a comment'
>>> f.delprop('comment')
The numpy data type of the data array.
By default this is the data type with the smallest size and smallest scalar kind to which all data array partitions may be safely cast. For example, if the partitions have data types ‘int64’ and ‘float32’ then the data array’s data type will be ‘float64’.
Setting the data type to a numpy.dtype object, or any object convertible to a numpy.dtype object, will change the interpretation of the underlying data array elements. Note that the underlying data are not altered, so reinstating the original data type results in no loss of information.
Deleting the data type after setting it will reinstate the default behaviour. Deleting the data type when the default behaviour is in place will have no effect.
Examples
>>> f.dtype
dtype('float64')
>>> type(f.dtype)
<type 'numpy.dtype'>
>>> print f.array
[0.5 1.5 2.5]
>>> print f.array
[0.5 1.5 2.5]
>>> import numpy
>>> f.dtype = numpy.dtype(int)
>>> print f.array
[0 1 2]
>>> f.dtype = bool
>>> print f.array
[False True True]
>>> f.dtype = 'float64'
>>> print f.array
[0.5 1.5 2.5]
The first element of the data array.
Examples
>>> print f.array
[[1 2 3 4]]
>>> f.first_datum
1
>>> print f.array
[[-- 2 3 4]]
>>> f.first_datum
--
Whether the mask is hard (True) or soft (False).
When the mask is hard, masked entries of the data array can not be unmasked by assignment.
By default, the mask is hard.
Examples
>>> f.hardmask = False
>>> f.hardmask
False
True if and only if there is a data array.
Examples
>>> hasattr(f, 'Data')
True
>>> f.hasData
True
>>> del f.Data
>>> f.hasData
False
The history CF property.
Examples
>>> f.history = 'created on 2012/10/01'
>>> f.history
'created on 2012/10/01'
>>> del f.history
>>> f.setprop('history', 'created on 2012/10/01')
>>> f.getprop('history')
'created on 2012/10/01'
>>> f.delprop('history')
True if and only if the data array is a scalar array.
Examples
>>> print f.array
2
>>> f.isscalar
True
>>> print f.array
[2]
>>> f.isscalar
False
>>> print f.array
[[2, 3]]
>>> f.isscalar
False
>>> f.hasData
False
>>> f.isscalar
False
The last element of the data array.
Examples
>>> print f.array
[[1 2 3 4]]
>>> f.last_datum
4
>>> print f.array
[[1 2 3 --]]
>>> f.last_datum
--
The leap_month CF property.
Examples
>>> f.leap_month = 2
>>> f.leap_month
2
>>> del f.leap_month
>>> f.setprop('leap_month', 2)
>>> f.getprop('leap_month')
2
>>> f.delprop('leap_month')
The leap_year CF property.
Examples
>>> f.leap_year = 1984
>>> f.leap_year
1984
>>> del f.leap_year
>>> f.setprop('leap_year', 1984)
>>> f.getprop('leap_year')
1984
>>> f.delprop('leap_year')
The long_name CF property.
Examples
>>> f.long_name = 'zonal_wind'
>>> f.long_name
'zonal_wind'
>>> del f.long_name
>>> f.setprop('long_name', 'surface air temperature')
>>> f.getprop('long_name')
'surface air temperature'
>>> f.delprop('long_name')
The mask of the data array.
Examples
>>> f.shape
(12, 73, 96)
>>> m = f.mask
<CF Field: mask()>
>>> m.shape
(12, 73, 96)
>>> m.dtype
dtype('bool')
The name of spatial measure being represented.
Examples
>>> c.measure
'area'
The missing_value CF property.
This property is forced to be consistent with the _FillValue property as follows:
- Assigning a value to missing_value also assigns the same value to _FillValue whether the latter has been previously set or not.
- Assigning a value to _FillValue also assigns the same value to missing_value, but only if the latter has previously been defined.
Examples
>>> f.missing_value = 1e30
>>> f.missing_value
1e30
>>> f._FillValue
1e30
>>> del f.missing_value
>>> f._FillValue
1e30
The month_lengths CF property.
Stored as a tuple but may be set as any array-like object.
Examples
>>> f.month_lengths = numpy.array([34, 31, 32, 30, 29, 27, 28, 28, 28, 32, 32, 34])
>>> f.month_lengths
(34, 31, 32, 30, 29, 27, 28, 28, 28, 32, 32, 34)
>>> del f.month_lengths
>>> f.setprop('month_lengths', [34, 31, 32, 30, 29, 27, 28, 28, 28, 32, 32, 34])
>>> f.getprop('month_lengths')
(34, 31, 32, 30, 29, 27, 28, 28, 28, 32, 32, 34)
>>> f.delprop('month_lengths')
Number of dimensions in the data array.
Examples
>>> f.shape
(73, 96)
>>> f.ndim
2
A dictionary of the CF properties.
Note that modifying the returned dictionary will not change the CF properties.
Examples
>>> f.properties
{'_FillValue': 1e+20,
'foo': 'bar',
'long_name': 'Surface Air Temperature',
'standard_name': 'air_temperature',
'units': 'K'}
The scale_factor CF property.
This property is only used when writing to a file on disk.
Examples
>>> f.scale_factor = 10.0
>>> f.scale_factor
10.0
>>> del f.scale_factor
>>> f.setprop('scale_factor', 10.0)
>>> f.getprop('scale_factor')
10.0
>>> f.delprop('scale_factor')
Tuple of the data array’s dimension sizes.
Examples
>>> f.shape
(73, 96)
Number of elements in the data array.
Examples
>>> f.shape
(73, 96)
>>> f.size
7008
The standard_name CF property.
Examples
>>> f.standard_name = 'time'
>>> f.standard_name
'time'
>>> del f.standard_name
>>> f.setprop('standard_name', 'time')
>>> f.getprop('standard_name')
'time'
>>> f.delprop('standard_name')
Return a new variable whose data is subspaced.
This attribute may be indexed to select a subspace from dimension index values.
Subspacing by indexing
Subspacing by dimension indices uses an extended Python slicing syntax, which is similar numpy array indexing. There are two extensions to the numpy indexing functionality:
Size 1 dimensions are never removed.
An integer index i takes the i-th element but does not reduce the rank of the output array by one.
When advanced indexing is used on more than one dimension, the advanced indices work independently.
When more than one dimension’s slice is a 1-d boolean array or 1-d sequence of integers, then these indices work independently along each dimension (similar to the way vector subscripts work in Fortran), rather than by their elements.
Examples
The units CF property.
This property is a mirror of the units stored in the Units attribute.
Examples
>>> f.units = 'K'
>>> f.units
'K'
>>> del f.units
>>> f.setprop('units', 'm.s-1')
>>> f.getprop('units')
'm.s-1'
>>> f.delprop('units')
The valid_max CF property.
Examples
>>> f.valid_max = 100.0
>>> f.valid_max
100.0
>>> del f.valid_max
>>> f.setprop('valid_max', 100.0)
>>> f.getprop('valid_max')
100.0
>>> f.delprop('valid_max')
The valid_min CF property.
Examples
>>> f.valid_min = 100.0
>>> f.valid_min
100.0
>>> del f.valid_min
>>> f.setprop('valid_min', 100.0)
>>> f.getprop('valid_min')
100.0
>>> f.delprop('valid_min')
The valid_range CF property.
Stored as a tuple but may be set as any array-like object.
Examples
>>> f.valid_range = numpy.array([100., 400.])
>>> f.valid_range
(100.0, 400.0)
>>> del f.valid_range
>>> f.setprop('valid_range', [100.0, 400.0])
>>> f.getprop('valid_range')
(100.0, 400.0)
>>> f.delprop('valid_range')
A numpy array view of the data array.
Changing the elements of the returned view changes the data array.
Examples
>>> a = f.varray
>>> type(a)
<type 'numpy.ndarray'>
>>> a
array([0, 1, 2, 3, 4])
>>> a[0] = 999
>>> f.varray
array([999, 1, 2, 3, 4])