cf.FieldAncillary

class cf.FieldAncillary(properties={}, attributes=None, data=None, source=None, copy=True)[source]

Bases: cf.variable.Variable

A CF field ancillary construct.

Initialization

Parameters:
properties: dict, optional

Initialize CF properties from the dictionary’s key/value pairs.

attributes: dict, optional

Provide attributes from the dictionary’s key/value pairs.

data: cf.Data, optional

Provide a data array.

source: cf.{+Variable}, optional

Take the attributes, CF properties and data array from the source {+variable}. Any attributes, CF properties or data array specified with other parameters are set after initialisation from the source {+variable}.

copy: bool, optional

If False then do not deep copy arguments prior to initialization. By default arguments are deep copied.
__init__(properties={}, attributes=None, data=None, source=None, copy=True)[source]

Initialization

Parameters:
properties: dict, optional

Initialize CF properties from the dictionary’s key/value pairs.

attributes: dict, optional

Provide attributes from the dictionary’s key/value pairs.

data: cf.Data, optional

Provide a data array.

source: cf.{+Variable}, optional

Take the attributes, CF properties and data array from the source {+variable}. Any attributes, CF properties or data array specified with other parameters are set after initialisation from the source {+variable}.

copy: bool, optional

If False then do not deep copy arguments prior to initialization. By default arguments are deep copied.

Methods

HDF_chunks(*chunksizes) Specify HDF5 chunks for the data array.
__init__([properties, attributes, data, …]) Initialization
all() Test whether all data array elements evaluate to True.
allclose(y[, atol, rtol]) Returns True if two broadcastable field ancillarys have equal array values to within numerical tolerance.
any() Return True if any data array elements evaluate to True.
asdatetime([i]) Convert the internal representation of data array elements to date-time objects.
asreftime([i]) Convert the internal representation of data array elements to numeric reference times.
attributes([attrs, copy]) Inspect or change attributes which are not CF properties.
ceil([i]) The ceiling of the data array.
chunk([chunksize]) Partition the data array.
clip(a_min, a_max[, units, bounds, i]) Limit the values in the data array.
close() Close all files referenced by the field ancillary.
concatenate(variables[, axis, _preserve]) Join a sequence of variables together.
convert_reference_time([units, …]) Convert reference time data values to have new units.
copy([_omit_Data, _only_Data, …]) Return a deep copy.
cos([bounds, i]) Take the trigonometric cosine of the data array.
count() Count the non-masked elements of the array.
cyclic([axes, iscyclic]) Set the cyclicity of axes of the data array.
datum(*index) Return an element of the data array as a standard Python scalar.
delprop(prop) Delete a CF property.
dump([display, omit, field, key, _level, _title]) Return a string containing a full description of the field ancillary object.
equals(other[, rtol, atol, …]) True if two field ancillarys are equal, False otherwise.
equivalent(other[, rtol, atol, traceback]) True if two field ancillarys are equal, False otherwise.
exp([bounds, i]) The exponential of the data array.
expand_dims([position, i]) Insert a size 1 axis into the data array.
files() Return the names of any files containing parts of the data array.
fill_value([default]) Return the data array missing data value.
flip([axes, i]) Flip dimensions of the data array in place.
floor([bounds, i]) Floor the data array.
getprop(prop, *default) Get a CF property.
hasprop(prop) Return True if a CF property exists, otherise False.
identity([default, relaxed_identity]) Return the identity of the field ancillary.
index(x[, start, stop]) L.index(value, [start, [stop]]) – return first index of value.
insert_data(data[, copy]) Insert a new data array into the variable in place.
inspect() Inspect the object for debugging.
log([base, bounds, i]) The logarithm of the data array.
mask_invalid([i]) Mask the array where invalid values occur.
match([description, ndim, exact, match_and, …]) Determine whether or not a variable satisfies conditions.
max() The maximum of the data array.
mean() The unweighted mean the data array.
mid_range() The unweighted average of the maximum and minimum of the data array.
min() The minimum of the data array.
name([default, identity, ncvar, …]) Return a name for the field ancillary.
override_calendar(calendar[, i]) Override the calendar of date-time units.
override_units(units[, i]) Override the units.
properties([props, clear, copy]) Inspect or change the CF properties.
range() The absolute difference between the maximum and minimum of the data array.
remove_data() Remove and return the data array.
rint([bounds, i]) Round data array.
roll(iaxis, shift[, i]) Roll the field ancillary along an axis.
round([decimals, bounds, i]) Round the data array.
sample_size() The number of non-missing data elements in the data array.
sd() The unweighted sample standard deviation of the data array.
select(*args, **kwargs) cf.FieldAncillary.select has been deprecated.
setprop(prop, value) Set a CF property.
sin([bounds, i]) The trigonometric sine of the data array.
squeeze([axes, i]) Remove size 1 dimensions from the data array
sum() The sum of the data array.
tan([bounds, i]) The trigonometric tangent of the data array.
transpose([axes, i]) Permute the dimensions of the data array.
trunc([bounds, i]) Truncate the data array.
unique() The unique elements of the data array.
var() The unweighted sample variance of the data array.
where(condition[, x, y, i]) Set data array elements depending on a condition.
HDF_chunks(*chunksizes)[source]

Specify HDF5 chunks for the data array.

Chunking refers to a storage layout where the data array is partitioned into fixed-size multi-dimensional chunks when written to a netCDF4 file on disk. Chunking is ignored if the data array is written to a netCDF3 format file.

A chunk has the same rank as the data array, but with fewer (or no more) elements along each axis. The chunk is defined by a dictionary in which the keys identify axes and the values are the chunk sizes for those axes.

If a given chunk size for an axis is larger than the axis size, then the size of the axis at the time of writing to disk will be used instead.

If chunk sizes have been specified for some but not all axes, then the each unspecified chunk size is assumed to be the full size of its axis.

If no chunk sizes have been set for any axes then the netCDF default chunk is used (http://www.unidata.ucar.edu/software/netcdf/docs/netcdf_perf_chunking.html).

A detailed discussion of HDF chunking and I/O performance is available at https://www.hdfgroup.org/HDF5/doc/H5.user/Chunking.html and http://www.unidata.ucar.edu/software/netcdf/workshops/2011/nc4chunking. Basically, you want the chunks for each dimension to match as closely as possible the size and shape of the data block that users will read from the file.

New in version 1.1.13.

Examples 1:

To define chunks which are the full size for each axis except for the first axis which is to have a chunk size of 12:

>>> old_chunks = f.HDF_chunks({0: 12})
Parameters:
chunksizes: dict or None, optional

Specify the chunk sizes for axes of the field ancillary. Axes are given by dictionary keys, with a chunk size for those axes as the dictionary values. A dictionary key may be an integer or a tuple of integers defining axes by position in the data array. In the special case of chunksizes being None, then chunking is set to the netCDF default.

Example:

To set the chunk size for first axes to 365: {0: 365}.

Example:

To set the chunk size for the first and third data array axes to 100: {0: 100, 2: 100}, or equivalently {(0, 2): 100}.

Example:

To set the chunk size for the second axis to 100 and for the third axis to 5: {1: 100, 2: 5}.

Example:

To set the chunking to the netCDF default: None.
Returns:
out: dict

The chunk sizes prior to the new setting, or the current current sizes if no new values are specified.
all()[source]

Test whether all data array elements evaluate to True.

Performs a logical and over the data array and returns the result. Masked values are considered as True during computation.

See also

any

Examples 1: 
>>> x = f.all()
Returns:
out: bool

Whether ot not all data array elements evaluate to True.
Examples: 
>>> print f.array
[[0 3 0]]
>>> f.all()
False

>>> print f.array
[[1 3 --]]
>>> f.all()
True
allclose(y, atol=None, rtol=None)[source]

Returns True if two broadcastable field ancillarys have equal array values to within numerical tolerance.

For numeric data arrays f.allclose(y, atol, rtol) is equivalent to (abs(f - y) <= atol + rtol*abs(y)).all(); for other data types it is equivalent to (f == y).all().

See also

~cf.FieldAncillary.equals

Examples 1: 
>>> x = f.allclose(g)
Parameters:
y: data-like object

The object to be compared with the data array. y must be broadcastable to the data array and if y has units then they must be compatible.

A data-like object is any object containing array-like or scalar data which could be used to create a cf.Data object.

Example:

Instances, x, of following types are all examples of data-like objects (because cf.Data(x) creates a valid cf.Data object): int, float, str, tuple, list, numpy.ndarray, cf.Data, cf.Coordinate, cf.Field.

atol: float, optional

The absolute tolerance for all numerical comparisons, By default the value returned by the cf.ATOL function is used.

rtol: float, optional

The relative tolerance for all numerical comparisons, By default the value returned by the cf.RTOL function is used.
Returns:
out: bool

Whether or not the two data arrays are equivalent.
Examples 2:
any()[source]

Return True if any data array elements evaluate to True.

Performs a logical or over the data array and returns the result. Masked values are considered as False during computation.

See also

all

Examples 1: 
>>> x = f.any()
Returns:
out: bool

Whether ot not any data array elements evaluate to True.
Examples 2: 
>>> print f.array
[[0 0 0]]
>>> f.any()
False

>>> print f.array
[[-- 0 0]]
>>> d.any()
False

>>> print f.array
[[-- 3 0]]
>>> f.any()
True
asdatetime(i=False)[source]

Convert the internal representation of data array elements to date-time objects.

Only applicable to field ancillarys with reference time units.

If the calendar has not been set then the CF default calendar will be used and the units will be updated accordingly.

See also

asreftime

Examples 1: 
>>> g = f.asdatetime()
Parameters:
i: bool, optional

If True then update the field ancillary in place. By default a new field ancillary is created. In either case, a field ancillary is returned.
Returns:

out: cf.FieldAncillary
Examples 2: 
>>> t.asdatetime().dtype
dtype('float64')
>>> t.asdatetime().dtype
dtype('O')
asreftime(i=False)[source]

Convert the internal representation of data array elements to numeric reference times.

Only applicable to field ancillarys with reference time units.

If the calendar has not been set then the CF default calendar will be used and the units will be updated accordingly.

See also

asdatetime

Examples 1: 
>>> g = f.asreftime()
Parameters:
i: bool, optional

If True then update the field ancillary in place. By default a new field ancillary is created. In either case, a field ancillary is returned.
Returns:

out: cf.FieldAncillary
Examples 2: 
>>> t.asdatetime().dtype
dtype('O')
>>> t.asreftime().dtype
dtype('float64')
attributes(attrs=None, copy=True)[source]

Inspect or change attributes which are not CF properties.

Examples 1: 
>>> f.attributes()
Parameters:
attrs: dict, optional

Set field ancillary attributes from the dictionary of values. If the copy parameter is True then the values in the attrs dictionary are deep copied

clear: bool, optional

If True then delete all attributes.

copy: bool, optional

If True then the values in the returned dictionary are deep copies of the field ancillary’s attribute values. By default they are not copied.
Returns:

out: dict
Examples: 
>>> f.attributes()
{}
>>> f.foo = 'bar'
>>> f.attributes()
{'foo': 'bar'}
>>> f.attributes().pop('foo')
'bar'
>>> f.attributes()
{'foo': 'bar'}

>>> f.attributes({'name': 'value'})
{'foo': 'bar', 'name': 'value'}
ceil(i=False)[source]

The ceiling of the data array.

The ceiling of the scalar x is the smallest integer i, such that i >= x.

New in version 1.0.

See also

floor, rint, trunc

Examples 1:

Create a new field ancillary with the ceiling of the data:

>>> g = f.ceil()
Parameters:
i: bool, optional

If True then update the field ancillary in place. By default a new field ancillary is created. In either case, a field ancillary is returned.
Returns:
out: cf.FieldAncillary

The field ancillary with the ceiling of data array values.
Examples 2: 
>>> print f.array
[-1.9 -1.5 -1.1 -1.   0.   1.   1.1  1.5  1.9]
>>> print f.ceil().array
[-1. -1. -1. -1.  0.  1.  2.  2.  2.]
>>> print f.array
[-1.9 -1.5 -1.1 -1.   0.   1.   1.1  1.5  1.9]
>>> print f.ceil(i=True).array
[-1. -1. -1. -1.  0.  1.  2.  2.  2.]
>>> print f.array
[-1. -1. -1. -1.  0.  1.  2.  2.  2.]
chunk(chunksize=None)[source]

Partition the data array.

Parameters:chunksize: int
Returns:None
clip(a_min, a_max, units=None, bounds=True, i=False)[source]

Limit the values in the data array.

Given an interval, values outside the interval are clipped to the interval edges.

Examples 1: 
>>> g = f.clip(-90, 90)
Parameters:

a_min: scalar

a_max: scalar

units: str or cf.Units

bounds: optional

Ignored.

i: bool, optional

If True then update the field ancillary in place. By default a new field ancillary is created. In either case, a field ancillary is returned.
Returns:

out: cf.FieldAncillary
Examples 2: 
>>>
close()[source]

Close all files referenced by the field ancillary.

Note that a closed file will be automatically reopened if its contents are subsequently required.

See also

files

Examples 1: 
>>> v.close()
Returns:None
concatenate(variables, axis=0, _preserve=True)[source]

Join a sequence of variables together.

Parameters:

variables: sequence of cf.FieldAncillary

axis: int, optional

_preserve: bool, optional
Returns:

out: cf.FieldAncillary
convert_reference_time(units=None, calendar_months=False, calendar_years=False, i=False)[source]

Convert reference time data values to have new units.

Conversion is done by decoding the reference times to date-time objects and then re-encoding them for the new units.

Any conversions are possible, but this method is primarily for conversions which require a change in the date-times originally encoded. For example, use this method to reinterpret data values in units of “months” since a reference time to data values in “calendar months” since a reference time. This is often necessary when when units of “calendar months” were intended but encoded as “months”, which have special definition. See the note and examples below for more details.

For conversions which do not require a change in the date-times implied by the data values, this method will be considerably slower than a simple reassignment of the units. For example, if the original units are 'days since 2000-12-1' then c.Units = cf.Units('days since 1901-1-1') will give the same result and be considerably faster than c.convert_reference_time(cf.Units('days since 1901-1-1'))

Note

It is recommended that the units “year” and “month” be used with caution, as explained in the following excerpt from the CF conventions: “The Udunits package defines a year to be exactly 365.242198781 days (the interval between 2 successive passages of the sun through vernal equinox). It is not a calendar year. Udunits includes the following definitions for years: a common_year is 365 days, a leap_year is 366 days, a Julian_year is 365.25 days, and a Gregorian_year is 365.2425 days. For similar reasons the unit month, which is defined to be exactly year/12, should also be used with caution.

Examples 1: 
>>> g = f.convert_reference_time()
Parameters:
units: cf.Units, optional

The reference time units to convert to. By default the units days since the original reference time in the the original calendar.

Example:

If the original units are 'months since 2000-1-1' in the Gregorian calendar then the default units to convert to are 'days since 2000-1-1' in the Gregorian calendar.

calendar_months: bool, optional

If True then treat units of 'months' as if they were calendar months (in whichever calendar is originally specified), rather than a 12th of the interval between 2 successive passages of the sun through vernal equinox (i.e. 365.242198781/12 days).

calendar_years: bool, optional

If True then treat units of 'years' as if they were calendar years (in whichever calendar is originally specified), rather than the interval between 2 successive passages of the sun through vernal equinox (i.e. 365.242198781 days).

i: bool, optional

If True then update the field ancillary in place. By default a new field ancillary is created. In either case, a field ancillary is returned.
Returns:
out: cf.FieldAncillary

The field ancillary with converted reference time data values.
Examples 2: 
>>> print f.array
[1 2 3 4]
>>> print f.Units
months since 2000-1-1
>>> print f.dtarray
[datetime.datetime(2000, 1, 31, 10, 29, 3, 831197)
 datetime.datetime(2000, 3, 1, 20, 58, 7, 662441)
 datetime.datetime(2000, 4, 1, 7, 27, 11, 493645)
 datetime.datetime(2000, 5, 1, 17, 56, 15, 324889)]
>>> f.convert_reference_time(calendar_months=True, i=True)
>>> print f.dtarray
[datetime.datetime(2000, 2, 1, 0, 0)
 datetime.datetime(2000, 3, 1, 0, 0)
 datetime.datetime(2000, 4, 1, 0, 0)
 datetime.datetime(2000, 5, 1, 0, 0)]
>>> print f.array
[  31.   60.   91.  121.]
>>> print f.Units
days since 2000-1-1
copy(_omit_Data=False, _only_Data=False, _omit_special=None, _omit_properties=False, _omit_attributes=False)[source]

Return a deep copy.

f.copy() is equivalent to copy.deepcopy(f).

Examples 1: 
>>> g = f.copy()
Returns:
out: cf.FieldAncillary

The deep copy.
Examples 2: 
>>> g = f.copy()
>>> g is f
False
>>> f.equals(g)
True
>>> import copy
>>> h = copy.deepcopy(f)
>>> h is f
False
>>> f.equals(g)
True
cos(bounds=True, i=False)[source]

Take the trigonometric cosine of the data array.

Units are accounted for in the calculation, so that the the cosine of 90 degrees_east is 0.0, as is the cosine 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 output units are ‘1’ (nondimensionsal).

See also

sin, tan

Examples 1: 
>>> g = f.cos()
Parameters:
bounds: optional

Ignored.

i: bool, optional

If True then update the field ancillary in place. By default a new field ancillary is created. In either case, a field ancillary is returned.
Returns:
out: cf.FieldAncillary

The field ancillary with the cosine of data array values.
Examples 2: 
>>> 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 --]]
count()[source]

Count the non-masked elements of the array.

Examples 1: 
>>> n = f.count()
Returns:out: int
cyclic(axes=None, iscyclic=True)[source]

Set the cyclicity of axes of the data array.

See also

iscyclic

Parameters:
axes: (sequence of) int

The axes to be set. Each axis is identified by its integer position. By default no axes are set.

iscyclic: bool, optional

If False then the axis is set to be non-cyclic. By default the axis is set to be cyclic.
Returns:

out: !set
Examples: 
>>> f.cyclic()
{}
>>> f.cyclic(1)
{}
>>> f.cyclic()
{1}
datum(*index)[source]

Return an element of the data array as a standard Python scalar.

The first and last elements are always returned with f.datum(0) and f.datum(-1) respectively, even if the data array is a scalar array or has two or more dimensions.

Parameters:
index: optional

Specify which element to return. When no positional arguments are provided, the method only works for data arrays with one element (but any number of dimensions), and the single element is returned. If positional arguments are given then they must be one of the following:

  • An integer. This argument is interpreted as a flat index into the array, specifying which element to copy and return.

    Example: If the data aray shape is (2, 3, 6) then:
    • f.datum(0) is equivalent to f.datum(0, 0, 0).
    • f.datum(-1) is equivalent to f.datum(1, 2, 5).
    • f.datum(16) is equivalent to f.datum(0, 2, 4).

    If index is 0 or -1 then the first or last data array element respecitively will be returned, even if the data array is a scalar array or has two or more dimensions.

  • Two or more integers. These arguments are interpreted as a multidimensionsal index to the array. There must be the same number of integers as data array dimensions.

  • A tuple of integers. This argument is interpreted as a multidimensionsal index to the array. There must be the same number of integers as data array dimensions.

    Example: f.datum((0, 2, 4)) is equivalent to f.datum(0, 2, 4); and f.datum(()) is equivalent to f.datum().
Returns:
out:

A copy of the specified element of the array as a suitable Python scalar.
Examples: 
>>> print f.array
2
>>> f.datum()
2
>>> 2 == f.datum(0) == f.datum(-1) == f.datum(())
True

>>> print f.array
[[2]]
>>> 2 == f.datum() == f.datum(0) == f.datum(-1)
True
>>> 2 == f.datum(0, 0) == f.datum((-1, -1)) == f.datum(-1, 0)
True

>>> print f.array
[[4 -- 6]
 [1 2 3]]
>>> f.datum(0)
4     
>>> f.datum(-1)
3     
>>> f.datum(1)
masked
>>> f.datum(4)
2     
>>> f.datum(-2)
2     
>>> f.datum(0, 0)
4     
>>> f.datum(-2, -1)
6     
>>> f.datum(1, 2)
3     
>>> f.datum((0, 2))
6
delprop(prop)[source]

Delete a CF property.

See also

getprop, hasprop, setprop

Examples 1: 
>>> f.delprop('standard_name')
Parameters:
prop: str

The name of the CF property.
Returns:

None
Examples 2: 
>>> f.foo = 'bar'
>>> f.delprop('foo')
>>> f.delprop('foo')
AttributeError: Can't delete non-existent Field CF property 'foo'
dump(display=True, omit=(), field=None, key=None, _level=0, _title=None)[source]

Return a string containing a full description of the field ancillary object.

Parameters:
display: bool, optional

If False then return the description as a string. By default the description is printed, i.e. f.dump() is equivalent to print f.dump(display=False).
Returns:
out: None or str

A string containing the description.
Examples:
equals(other, rtol=None, atol=None, ignore_fill_value=False, traceback=False, ignore=())[source]

True if two field ancillarys are equal, False otherwise.

Parameters:
other:

The object to compare for equality.

atol: float, optional

The absolute tolerance for all numerical comparisons, By default the value returned by the cf.ATOL function is used.

rtol: float, optional

The relative tolerance for all numerical comparisons, By default the value returned by the cf.RTOL function is used.

ignore_fill_value: bool, optional

If True then data arrays with different fill values are considered equal. By default they are considered unequal.

traceback: bool, optional

If True then print a traceback highlighting where the two field ancillarys differ.

ignore: tuple, optional

The names of CF properties to omit from the comparison.
Returns:
out: bool

Whether or not the two field ancillarys are equal.
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=['name'])
True
equivalent(other, rtol=None, atol=None, traceback=False)[source]

True if two field ancillarys are equal, False otherwise.

Parameters:
other:

The object to compare for equality.

atol: float, optional

The absolute tolerance for all numerical comparisons, By default the value returned by the cf.ATOL function is used.

rtol: float, optional

The relative tolerance for all numerical comparisons, By default the value returned by the cf.RTOL function is used.
exp(bounds=True, i=False)[source]

The exponential of the data array.

See also

log

Examples 1: 
>>> g = f.exp()
Parameters:
bounds: optional

Ignored.

i: bool, optional

If True then update the field ancillary in place. By default a new field ancillary is created. In either case, a field ancillary is returned.
Returns:
out: cf.FieldAncillary

The field ancillary with the exponential of data array values.
Examples 2: 
>>> f.data
<CF Data: [[1, 2]]>
>>> f.exp().data            
<CF Data: [[2.71828182846, 7.38905609893]]>

>>> f.data
<CF Data: [[1, 2]] 2>
>>> f.exp().data            
<CF Data: [[7.38905609893, 54.5981500331]]>

>>> g = f.exp(i=True)
>>> g is f
True

>>> f.data
<CF Data: [[1, 2]] kg m-1 s-2>
>>> f.+name}()          
ValueError: Can't take exponential of dimensional quantities: <CF Units: kg m-1 s-2>
expand_dims(position=0, i=False)[source]

Insert a size 1 axis into the data array.

See also

flip, squeeze, transpose

Examples 1: 
>>> g = f.expand_dims()
Parameters:
position: int, optional

Specify the position amongst the data array axes where the new axis is to be inserted. By default the new axis is inserted at position 0, the slowest varying position.

bounds: optional

Ignored.

i: bool, optional

If True then update the field ancillary in place. By default a new field ancillary is created. In either case, a field ancillary is returned.
Returns:

None
Examples: 
>>> v.expand_dims(2)
>>> v.expand_dims(-1)
files()[source]

Return the names of any files containing parts of the data array.

See also

close

Examples 1: 
>>> f.files()
Returns:
out: !set

The file names in normalized, absolute form.
Examples 2: 
>>> f = cf.read_field('../file*')
>>> f.files()
{'/data/user/file1',
 '/data/user/file2',
 '/data/user/file3'}
>>> a = f.array
>>> f.files()
set()
fill_value(default=None)[source]

Return the data array missing data value.

This is the value of the missing_value CF property, or if that is not set, the value of the _FillValue CF property, else if that is not set, None. In the last case the default numpy missing data value for the array’s data type is assumed if a missing data value is required.

Parameters:
default: optional

If the missing value is unset then return this value. By default, default is None. If default is the special value 'netCDF' then return the netCDF default value appropriate to the data array’s data type is used. These may be found as follows:

>>> import netCDF4
>>> print netCDF4.default_fillvals
Returns:
out:

The missing data value, or the value specified by default if one has not been set.
Examples: 
>>> f.fill_value()
None
>>> f._FillValue = -1e30
>>> f.fill_value()
-1e30
>>> f.missing_value = 1073741824
>>> f.fill_value()
1073741824
>>> del f.missing_value
>>> f.fill_value()
-1e30
>>> del f._FillValue
>>> f.fill_value()
None
>>> f,dtype
dtype('float64')
>>> f.fill_value(default='netCDF')
9.969209968386869e+36
>>> f._FillValue = -999
>>> f.fill_value(default='netCDF')
-999
flip(axes=None, i=False)[source]

Flip dimensions of the data array in place.

See also

expand_dims, squeeze, transpose

Examples 1: 
>>> g = f.flip()
Parameters:
axes: (sequence of) int

Flip the dimensions whose positions are given. By default all dimensions are flipped.
Returns:

out: cf.FieldAncillary
Examples 2: 
>>> f.flip()
>>> f.flip(1)
>>> f.flip([0, 1])

>>> g = f[::-1, :, ::-1]
>>> f.flip([2, 0]).equals(g)
True
floor(bounds=True, i=False)[source]

Floor the data array.

The floor of the scalar x is the largest integer i, such that i <= x.

New in version 1.0.

See also

ceil, rint, trunc

Examples 1: 
>>> g = f.floor()
Parameters:
bounds: optional

Ignored.

i: bool, optional

If True then update the field ancillary in place. By default a new field ancillary is created. In either case, a field ancillary is returned.
Returns:
out: cf.FieldAncillary

The field ancillary with the floor of data array values.
Examples 2: 
>>> print f.array
[-1.9 -1.5 -1.1 -1.   0.   1.   1.1  1.5  1.9]
>>> print f.floor().array
[-2. -2. -2. -1.  0.  1.  1.  1.  1.]
>>> print f.array
[-1.9 -1.5 -1.1 -1.   0.   1.   1.1  1.5  1.9]
>>> print f.floor(i=True).array
[-2. -2. -2. -1.  0.  1.  1.  1.  1.]
>>> print f.array
[-2. -2. -2. -1.  0.  1.  1.  1.  1.]
getprop(prop, *default)[source]

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.

See also

delprop, hasprop, setprop

Examples 1: 
>>> f.getprop('standard_name')
Parameters:
prop: str

The name of the CF property.

default: optional

Return default if and only if the variable does not have the named property.
Returns:
out:

The value of the named property or the default value, if set.
Examples 2: 
>>> 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'
hasprop(prop)[source]

Return True if a CF property exists, otherise False.

See also

delprop, getprop, setprop

Examples 1: 
>>> x = f.hasprop('standard_name')
Parameters:
prop: str

The name of the property.
Returns:
out: bool

True if the CF property exists, otherwise False.
identity(default=None, relaxed_identity=None)[source]

Return the identity of the field ancillary.

The identity is, by default, the first found of the following:

  • The standard_name CF property.
  • The !id attribute.
  • If the relaxed parameter is True, the standard_name CF property.
  • The !id attribute.
  • The value of the default parameter.

This is altered if the relaxed parameter is True.

See also

name

Examples 1: 
>>> i = f.identity()
Parameters:
default: optional

The identity if one could not otherwise be found. By default, default is None.
Returns:
out:

The identity.
Examples 2: 
>>> f.standard_name = 'Kelvin'
>>> f.id = 'foo'
>>> f.identity()
'Kelvin'
>>> del f.standard_name
>>> f.identity()
'foo'
>>> del f.id
>>> f.identity()
None
>>> f.identity('bar')
'bar'
>>> print f.identity()
None
index(x, start=0, stop=None)[source]

L.index(value, [start, [stop]]) – return first index of value.

Each field in the field ancillary is compared with the field’s ~cf.Field.equals method (as aopposed to the == operator).

It is an error if there is no such field.

See also

list.index

Examples: 
>>>
insert_data(data, copy=True)[source]

Insert a new data array into the variable in place.

Parameters:

data: cf.Data

copy: bool, optional
Returns:

None
inspect()[source]

Inspect the object for debugging.

See also

cf.inspect

Examples 1: 
>>> f.inspect()
Returns:None
log(base=10, bounds=True, i=False)[source]

The logarithm of the data array.

By default the natural logarithm is taken, but any base may be specified.

See also

exp

Examples 1: 
>>> g = f.log()
Parameters:
base: number, optional

The base of the logiarthm. By default a natural logiarithm is taken.

i: bool, optional

If True then update the field ancillary in place. By default a new field ancillary is created. In either case, a field ancillary is returned.
Returns:
out: cf.FieldAncillary

The field ancillary with the logarithm of data array values.
Examples 2: 
>>> f.data
<CF Data: [[1, 2]]>
>>> f.log().data
<CF Data: [[0.0, 0.69314718056]] ln(re 1)>

>>> f.data
<CF Data: [[1, 2]] 2>
>>> f.log().data
<CF Data: [[0.0, 0.69314718056]] ln(re 2 1)>

>>> f.data
<CF Data: [[1, 2]] kg s-1 m-2>
>>> f.log().data
<CF Data: [[0.0, 0.69314718056]] ln(re 1 m-2.kg.s-1)>

>>> g = f.log(i=True)
>>> g is f
True

>>> f.Units
<CF Units: >
>>> f.log()
ValueError: Can't take the logarithm to the base 2.718281828459045 of <CF Units: >
mask_invalid(i=False)[source]

Mask the array where invalid values occur.

Note that:

  • Invalid values are Nan or inf
  • Invalid values in the results of arithmetic operations only occur if the raising of FloatingPointError exceptions has been suppressed by cf.Data.seterr.
  • If the raising of FloatingPointError exceptions has been allowed then invalid values in the results of arithmetic operations it is possible for them to be automatically converted to masked values, depending on the setting of cf.Data.mask_fpe. In this case, such automatic conversion might be faster than calling mask_invalid.

See also

cf.Data.mask_fpe, cf.Data.seterr

Examples 1: 
>>> g = f.mask_invalid()
Parameters:
i: bool, optional

If True then update the field ancillary in place. By default a new field ancillary is created. In either case, a field ancillary is returned.
Returns:

out: cf.FieldAncillary
Examples 2: 
>>> print f.array
[ 0.  1.]
>>> print g.array
[ 1.  2.]

>>> old = cf.Data.seterr('ignore')
>>> h = g/f
>>> print h.array
[ inf   2.]
>>> h.mask_invalid(i=True)
>>> print  h.array
[--  2.]

>>> h = g**12345
>>> print h.array
[ 1.  inf]
>>> h = h.mask_invalid()
>>> print h.array
[1.  --]

>>> old = cf.Data.seterr('raise')
>>> old = cf.Data.mask_fpe(True)
>>> print (g/f).array
[ --  2]
>>> print (g**12345).array
[1.  -- ]
match(description=None, ndim=None, exact=False, match_and=True, inverse=False, _Flags=False, _CellMethods=False)[source]

Determine whether or not a variable satisfies conditions.

Conditions may be specified on the variable’s attributes and CF properties.

Parameters:
Returns:
out: bool

Whether or not the variable matches the given criteria.
Examples:
max()[source]

The maximum of the data array.

See also

collapse, mean, mid_range, min, range, sample_size, sd, sum, var

Examples 1: 
>>> d = f.max()
Returns:
out: cf.Data

The maximum of the data array.
Examples 2: 
>>> f.data
<CF Data: [[[236.512756348, ..., 256.93371582]]] K>
>>> f.max()
311.343780518
>>> f.max().data
<CF Data: 311.343780518 K>
mean()[source]

The unweighted mean the data array.

See also

collapse, max, mid_range, min, range, sample_size, sd, sum, var

Examples 1: 
>>> d = f.mean()
Returns:
out: cf.Data

The unweighted mean the data array.
Examples 2: 
>>> f.data
<CF Data: [[[236.512756348, ..., 256.93371582]]] K>
>>> f.mean()
280.192227593
>>> f.mean().data
<CF Data: 280.192227593 K>
mid_range()[source]

The unweighted average of the maximum and minimum of the data array.

See also

collapse, max, mean, min, range, sample_size, sd, sum, var

Examples 1: 
>>> d = f.mid_range()
Returns:
out: cf.Data

The unweighted average of the maximum and minimum of the data array.
Examples 2: 
>>> f.data
<CF Data: [[[236.512756348, ..., 256.93371582]]] K>
>>> f.mid_range()
255.08618927
>>> f.mid_range().data
<CF Data: 255.08618927 K>
min()[source]

The minimum of the data array.

See also

collapse, max, mean, mid_range, range, sample_size, sd, sum, var

Examples 1: 
>>> d = f.min()
Returns:
out: cf.Data

The minimum of the data array.
Examples 2: 
>>> f.data
<CF Data: [[[236.512756348, ..., 256.93371582]]] K>
>>> f.min()
198.828598022
>>> f.min().data
<CF Data: 198.828598022 K>
name(default=None, identity=False, ncvar=False, relaxed_identity=None)[source]

Return a name for the field ancillary.

By default the name is the first found of the following:

  1. The standard_name CF property.
  2. The long_name CF property, preceeded by the string 'long_name:'.
  3. The !id attribute.
  4. The !ncvar attribute, preceeded by the string 'ncvar%'.
  5. The value of the default parameter.

Note that f.name(identity=True) is equivalent to f.identity().

See also

identity

Examples 1: 
>>> n = f.name()
>>> n = f.name(default='NO NAME')
Parameters:
default: optional

If no name can be found then return the value of the default parameter. By default the default is None.

identity: bool, optional

If True then only 1., 3. and 5. are considered as possible names.

ncvar: bool, optional

If True then only 4. and 5. are considered as possible names.
Returns:
out:

The name.
Examples 2: 
>>> f.standard_name = 'air_temperature'
>>> f.long_name = 'temperature of the air'
>>> f.ncvar = 'tas'
>>> f.name()
'air_temperature'
>>> del f.standard_name
>>> f.name()
'long_name:temperature of the air'
>>> del f.long_name
>>> f.name()
'ncvar:tas'
>>> del f.ncvar
>>> f.name()
None
>>> f.name('no_name')
'no_name'
>>> f.standard_name = 'air_temperature'
>>> f.name('no_name')
'air_temperature'
override_calendar(calendar, i=False)[source]

Override the calendar of date-time units.

The new calendar need not be equivalent to the original one and the data array elements will not be changed to reflect the new units. Therefore, this method should only be used when it is known that the data array values are correct but the calendar has been incorrectly encoded.

Not to be confused with setting the calendar or Units attributes to a calendar which is equivalent to the original calendar

See also

calendar, override_units, units, Units

Examples 1: 
>>> g = f.override_calendar('noleap')
Parameters:
calendar: str

The new calendar.

i: bool, optional

If True then update the field ancillary in place. By default a new field ancillary is created. In either case, a field ancillary is returned.
Returns:

out: cf.FieldAncillary
Examples 2:
override_units(units, i=False)[source]

Override the units.

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. Therefore, this method should only be used when it is known that the data array values are correct but the units have incorrectly encoded.

Not to be confused with setting units or Units attributes to units which are equivalent to the original units.

See also

calendar, override_calendar, units, Units

Examples 1: 
>>> g = f.override_units('m')
Parameters:
units: str or cf.Units

The new units for the data array.

i: bool, optional

If True then update the field ancillary in place. By default a new field ancillary is created. In either case, a field ancillary is returned.
Returns:

out: cf.FieldAncillary
Examples 2: 
>>> f.Units
<CF Units: hPa>
>>> f.datum(0)
100000.0
>>> f.override_units('km')
>>> f.Units
<CF Units: km>
>>> f.datum(0)
100000.0
>>> f.override_units(cf.Units('watts'))
>>> f.Units
<CF Units: watts>
>>> f.datum(0)
100000.0
properties(props=None, clear=False, copy=True)[source]

Inspect or change the CF properties.

Examples 1: 
>>> f.properties()
Parameters:
props: dict, optional

Set field ancillary attributes from the dictionary of values. If the copy parameter is True then the values in the attrs dictionary are deep copied

clear: bool, optional

If True then delete all CF properties.

copy: bool, optional

If True then the values in the returned dictionary are deep copies of the field ancillary’s attribute values. By default they are not copied.
Returns:
out: dict

The CF properties prior to being changed, or the current CF properties if no changes were specified.
Examples 2:
range()[source]

The absolute difference between the maximum and minimum of the data array.

See also

collapse, max, mean, mid_range, min, sample_size, sd, sum, var

Examples 1: 
>>> d = f.range()
Returns:
out: cf.Data

The absolute difference between the maximum and minimum of the data array.
Examples 2: 
>>> f.data
<CF Data: [[[236.512756348, ..., 256.93371582]]] K>
>>> f.range()
112.515182495
>>> f.range().data
<CF Data: 112.515182495 K>
remove_data()[source]

Remove and return the data array.

Returns:
out: cf.Data or None

The removed data array, or None if there isn’t one.
Examples: 
>>> f._hasData
True
>>> f.data
<CF Data: [0, ..., 9] m>
>>> f.remove_data()
<CF Data: [0, ..., 9] m>
>>> f._hasData
False
>>> print f.remove_data()
None
rint(bounds=True, i=False)[source]

Round data array.

The scalar x is rounded to the nearest integer i.

New in version 1.0.

See also

ceil, floor, trunc

Examples 1: 
>>> g = f.rint()
Parameters:
bounds: optional

Ignored.

i: bool, optional

If True then update the field ancillary in place. By default a new field ancillary is created. In either case, a field ancillary is returned.
Returns:
out: cf.FieldAncillary

The field ancillary with rounded data array values.
Examples 2: 
>>> print f.array
[-1.9 -1.5 -1.1 -1.   0.   1.   1.1  1.5  1.9]
>>> print f.rint().array
[-2. -2. -1. -1.  0.  1.  1.  2.  2.]
>>> print f.array
[-1.9 -1.5 -1.1 -1.   0.   1.   1.1  1.5  1.9]
>>> print f.rint(i=True).array
[-2. -2. -1. -1.  0.  1.  1.  2.  2.]
>>> print f.array
[-2. -2. -1. -1.  0.  1.  1.  2.  2.]
roll(iaxis, shift, i=False)[source]

Roll the field ancillary along an axis.

See also

expand_dims, flip, squeeze, transpose

Parameters:

iaxis: int

i: bool, optional

If True then update the field ancillary in place. By default a new field ancillary is created. In either case, a field ancillary is returned.
Returns:

out: cf.FieldAncillary
Examples:
round(decimals=0, bounds=True, i=False)[source]

Round the data array.

Data elements are evenly rounded to the given number of decimals.

Note

Values exactly halfway between rounded decimal values are rounded to the nearest even value. Thus 1.5 and 2.5 round to 2.0, -0.5 and 0.5 round to 0.0, etc. Results may also be surprising due to the inexact representation of decimal fractions in the IEEE floating point standard and errors introduced when scaling by powers of ten.

New in version 1.1.4.

See also

ceil, floor, rint, trunc

Examples 1: 
>>> g = f.round(2)
Parameters:
decimals: int, optional

Number of decimal places to round to (0 by default). If decimals is negative, it specifies the number of positions to the left of the decimal point.

bounds: optional

Ignored.

i: bool, optional

If True then update the field ancillary in place. By default a new field ancillary is created. In either case, a field ancillary is returned.
Returns:
out: cf.FieldAncillary

The field ancillary with rounded data array values.
Examples 2: 
>>> print f.array
[-1.81, -1.41, -1.01, -0.91,  0.09,  1.09,  1.19,  1.59,  1.99])
>>> print f.round().array
[-2., -1., -1., -1.,  0.,  1.,  1.,  2.,  2.]
>>> print f.round(1).array
[-1.8, -1.4, -1. , -0.9,  0.1,  1.1,  1.2,  1.6,  2. ]
>>> print f.round(-1).array
[-0., -0., -0., -0.,  0.,  0.,  0.,  0.,  0.]
sample_size()[source]

The number of non-missing data elements in the data array.

See also

collapse, max, mean, mid_range, min, range, sd, sum, var

Examples 1: 
>>> d = f.sample_size()
Returns:
out: cf.Data

The number of non-missing data elements in the data array.
Examples 2: 
>>> f.data
<CF Data: [[[236.512756348, ..., 256.93371582]]] K>
>>> f.sample_size()
98304.0
>>> f.sample_size().data
<CF Data: 98304.0>
sd()[source]

The unweighted sample standard deviation of the data array.

See also

collapse, max, mean, mid_range, min, range, sample_size, sum, var

Examples 1: 
>>> d = f.sd()
Returns:
out: cf.Data

The unweighted standard deviation of the data array.
Examples 2: 
>>> f.data
<CF Data: [[[236.512756348, ..., 256.93371582]]] K>
>>> f.sd()
22.685052535
>>> f.sd().data
<CF Data: 22.685052535 K>
select(*args, **kwargs)[source]

cf.FieldAncillary.select has been deprecated.

Use cf.FieldAncillary.match to see if an individual field ancillary meets given criteria.

setprop(prop, value)[source]

Set a CF property.

See also

delprop, getprop, hasprop

Examples 1: 
>>> f.setprop('standard_name', 'time')
>>> f.setprop('foo', 12.5)
Parameters:
prop: str

The name of the CF property.

value:

The value for the property.
Returns:

None
sin(bounds=True, i=False)[source]

The trigonometric sine of the data array.

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

See also

cos, tan

Examples 1: 
>>> g = f.sin()
Parameters:
bounds: optional

Ignored.

i: bool, optional

If True then update the field ancillary in place. By default a new field ancillary is created. In either case, a field ancillary is returned.
Returns:
out: cf.FieldAncillary

The field ancillary with the sine of data array values.
Examples 2: 
>>> 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 --]]
squeeze(axes=None, i=False)[source]

Remove size 1 dimensions from the data array

See also

expand_dims, flip, transpose

Examples 1: 
>>> f.squeeze()
Parameters:
axes: (sequence of) int, optional

The size 1 axes to remove. By default, all size 1 axes are removed. Size 1 axes for removal are identified by their integer positions in the data array.

i: bool, optional

If True then update the field ancillary in place. By default a new field ancillary is created. In either case, a field ancillary is returned.
Returns:

out: cf.FieldAncillary
Examples: 
>>> f.squeeze(1)
>>> f.squeeze([1, 2])
sum()[source]

The sum of the data array.

See also

collapse, max, mean, mid_range, min, range, sample_size, sd, var

Examples 1: 
>>> d = f.sum()
Returns:
out: cf.Data

The sum of the data array.
Examples 2: 
>>> f.data
<CF Data: [[[236.512756348, ..., 256.93371582]]] K>
>>> f.sum()
27544016.7413
>>> f.sum().data
<CF Data: 27544016.7413 K>
tan(bounds=True, i=False)[source]

The trigonometric tangent of the data array.

Units are accounted for in the calculation, so that the the tangent of 180 degrees_east is 0.0, as is the sine of 3.141592653589793 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).

See also

cos, tan

Examples 1: 
>>> g = f.tan()
Parameters:
bounds: optional

Ignored.

i: bool, optional

If True then update the field ancillary in place. By default a new field ancillary is created. In either case, a field ancillary is returned.
Returns:
out: cf.FieldAncillary

The field ancillary with the tangent of data array values.
Examples 2: 
>>>
transpose(axes=None, i=False)[source]

Permute the dimensions of the data array.

See also

expand_dims, flip, squeeze

Examples 1:

g = f.transpose()

Parameters:
axes: (sequence of) int

The new axis order of the data array. By default the order is reversed. Each axis of the new order is identified by its original integer position.

i: bool, optional

If True then update the field ancillary in place. By default a new field ancillary is created. In either case, a field ancillary is returned.
Returns:

out: cf.FieldAncillary
Examples 2: 
>>> f.shape
(2, 3, 4)
>>> f.transpose()
>>> f.shape
(4, 3, 2)
>>> f.transpose([1, 2, 0])
>>> f.shape
(3, 2, 4)
>>> f.transpose((1, 0, 2))
>>> f.shape
(2, 3, 4)
trunc(bounds=True, i=False)[source]

Truncate the data array.

The truncated value of the scalar x, is the nearest integer i which is closer to zero than x is. I.e. the fractional part of the signed number x is discarded.

New in version 1.0.

See also

ceil, floor, rint

Examples 1: 
>>> g = f.trunc()
Parameters:
bounds: optional

Ignored.

i: bool, optional

If True then update the field ancillary in place. By default a new field ancillary is created. In either case, a field ancillary is returned.
Returns:
out: cf.FieldAncillary

The field ancillary with truncated data array values.
Examples 2: 
>>> print f.array
[-1.9 -1.5 -1.1 -1.   0.   1.   1.1  1.5  1.9]
>>> print f.trunc().array
[-1. -1. -1. -1.  0.  1.  1.  1.  1.]
>>> print f.array
[-1.9 -1.5 -1.1 -1.   0.   1.   1.1  1.5  1.9]
>>> print f.trunc(i=True).array
[-1. -1. -1. -1.  0.  1.  1.  1.  1.]
>>> print f.array
[-1. -1. -1. -1.  0.  1.  1.  1.  1.]
unique()[source]

The unique elements of the data array.

Examples 1: 
>>> f.unique()
Returns:
out: cf.Data

Returns the unique data array values in a one dimensional cf.Data object.
Examples 2: 
>>> print f.array
[[4 2 1]
 [1 2 3]]
>>> print f.unique().array
[1 2 3 4]
>>> f[1, -1] = cf.masked
>>> print f.array
[[4 2 1]
 [1 2 --]]
>>> print f.unique().array
[1 2 4]
var()[source]

The unweighted sample variance of the data array.

See also

collapse, max, mean, mid_range, min, range, sample_size, sd, sum

Examples 1: 
>>> d = f.var()
Returns:
out: cf.Data

The unweighted variance of the data array.
Examples 2: 
>>> f.data
<CF Data: [[[236.512756348, ..., 256.93371582]]] K>
>>> f.var()
514.611608515
>>> f.var().data
<CF Data: 514.611608515 K2>
where(condition, x=None, y=None, i=False)[source]

Set data array elements depending on a condition.

See also

cf.masked, hardmask, subspace

Returns:out: cf.FieldAncillary
Data

The cf.Data object containing the data array.

The use of this attribute does not guarantee that any missing data value that has been set is passed on to the cf.Data object. Use the data attribute to ensure that this is the case.

Examples: 
>>> f.Data
<CF Data: >
T

Always False.

See also

X, Y, Z

Examples: 
>>> print f.T
False
Units

The cf.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>

>>> f.Units
<CF Units: days since 2014-1-1 calendar=noleap>
X

Always False.

See also

T, Y, Z

Examples: 
>>> print f.X
False
Y

Always False.

See also

T, X, Z

Examples: 
>>> print f.Y
False
Z

Always False.

See also

T, X, Y

Examples: 
>>> print f.Z
False
add_offset

The add_offset CF property.

If present then this number is subtracted from the data prior to it being written to a file. If both scale_factor and add_offset properties are present, the offset is subtracted before the data are scaled. See http://cfconventions.org/latest.html for details.

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')
array

A numpy array deep copy of the data array.

Changing the returned numpy array does not change the data array.

See also

data, dtarray, dtvarray, varray

Examples 1: 
>>> f.data
<CF Data: [0, ... 4] kg m-1 s-2>
>>> 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]
>>> f.data
<CF Data: [0, ... 4] kg m-1 s-2>
binary_mask

A binary (0 and 1) 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.

Examples: 
>>> print f.mask.array
[[ True  False  True False]]
>>> b = f.binary_mask()
>>> print b.array
[[0 1 0 1]]
calendar

The calendar CF property.

The calendar used for encoding time data. See http://cfconventions.org/latest.html for details.

Examples: 
>>> f.calendar = 'noleap'
>>> f.calendar
'noleap'
>>> del f.calendar

>>> f.setprop('calendar', 'proleptic_gregorian')
>>> f.getprop('calendar')
'proleptic_gregorian'
>>> f.delprop('calendar')
comment

The comment CF property.

Miscellaneous information about the data or methods used to produce it. See http://cfconventions.org/latest.html for details.

Examples: 
>>> f.comment = 'This simulation was done on an HP-35 calculator'
>>> f.comment
'This simulation was done on an HP-35 calculator'
>>> del f.comment

>>> f.setprop('comment', 'a comment')
>>> f.getprop('comment')
'a comment'
>>> f.delprop('comment')
data

The cf.Data object containing the data array.

See also

array, cf.Data, hasdata, varray

Examples: 
>>> f.hasdata
True
>>> f.data
<CF Data: [[267.3, ..., 234.5]] K>
day

The day of each date-time data array element.

Only applicable to data arrays with reference time units.

See also

year, month, hour, minute, second`

Examples: 
>>> f.dtarray
[ 450-11-15 00:00:00  450-12-16 12:30:00  451-01-16 12:00:45]
>>> f.day.array
[15 16 16]
dtarray

An independent numpy array of date-time objects.

Only applicable for reference time units.

If the calendar has not been set then the CF default calendar will be used and the units will be updated accordingly.

The data type of the data array is unchanged.

See also

array, asdatetime, asreftime, dtvarray, varray

Examples:
dtvarray

A numpy array view the data array converted to date-time objects.

Only applicable for reference time units.

If the calendar has not been set then the CF default calendar will be used and the units will be updated accordingly.

See also

array, asdatetime, asreftime, dtarray, varray

Examples:
dtype

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 sub-arrays of the master data array may be safely cast without loss of information. For example, if the sub-arrays have data types ‘int64’ and ‘float32’ then the master data array’s data type will be ‘float64’; or if the sub-arrays have data types ‘int64’ and ‘int32’ then the master data array’s data type will be ‘int64’.

Setting the data type to a numpy.dtype object, or any object convertible to a numpy.dtype object, will cause the master data array elements to be recast to the specified type at the time that they are next accessed, and not before. This does not immediately change the master data array elements, so, for example, reinstating the original data type prior to data access results in no loss of information.

Deleting the data type forces the default behaviour. Note that if the data type of any sub-arrays has changed after dtype has been set (which could occur if the data array is accessed) then the reinstated default data type may be different to the data type prior to dtype being set.

Examples: 
>>> f.dtype
dtype('float64')
>>> type(f.dtype)
<type 'numpy.dtype'>

>>> 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.  1.  1.]

>>> print f.array
[0.5 1.5 2.5]
>>> f.dtype = int
>>> f.dtype = bool
>>> f.dtype = float
>>> print f.array
[ 0.5  1.5  2.5]
hardmask

Whether the mask is hard (True) or soft (False).

When the mask is hard, masked elements of the data array can not be unmasked by assignment, but unmasked elements may be still be masked.

When the mask is soft, masked entries of the data array may be unmasked by assignment and unmasked entries may be masked.

By default, the mask is hard.

See also

where, subspace, __setitem__

Examples: 
>>> f.hardmask = False
>>> f.hardmask
False
hasbounds

True if there are cell bounds.

If present, cell bounds are stored in the !bounds attribute.

Examples: 
>>> if c.hasbounds:
...     b = c.bounds
hasdata

True if there is a data array.

If present, the data array is stored in the data attribute.

See also

data, hasbounds

Examples: 
>>> if f.hasdata:
...     print f.data
history

The history CF property.

A list of the applications that have modified the original data. See http://cfconventions.org/latest.html for details.

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')
hour

The hour of each date-time data array element.

Only applicable to data arrays with reference time units.

See also

year, month, day, minute, second`

Examples: 
>>> f.dtarray
[ 450-11-15 00:00:00  450-12-16 12:30:00  451-01-16 12:00:45]
>>> f.hour.array
[ 0 12 12]
isauxiliary

True if the variable is an auxiliary coordinate object.

See also

isdimension, isdomainancillary, isfieldancillary, ismeasure

Examples: 
>>> f.isauxiliary
False
isdimension

True if the variable is a dimension coordinate object.

See also

isauxiliary, isdomainancillary, isfieldancillary, ismeasure

Examples: 
>>> f.isdimension
False
isdomainancillary

True if the variable is a domain ancillary object.

New in version DCH.

See also

isauxiliary, isdimension, isfieldancillary, ismeasure

Examples: 
>>> f.isdomainancillary
False
isfieldancillary

True, denoting that the variable is a field ancillary object.

New in version 2.0.

See also

isauxiliary, isdimension, isdomainancillary, ismeasure

Examples: 
>>> f.isfieldancillary
True
ismeasure

True if the variable is a cell measure object.

See also

isauxiliary, isdimension, isdomainancillary, isfieldancillary

Examples: 
>>> f.ismeasure
False
isscalar

True if the data array is scalar.

See also

hasdata, ndim

Examples: 
>>> f.ndim
0
>>> f.isscalar
True

>>> f.ndim >= 1
True
>>> f.isscalar
False

>>> f.hasdata
False
>>> f.isscalar
False
leap_month

The leap_month CF property.

Specifies which month is lengthened by a day in leap years for a user defined calendar. See http://cfconventions.org/latest.html for details.

Examples: 
>>> f.leap_month = 2
>>> f.leap_month
2
>>> del f.leap_month

>>> f.setprop('leap_month', 11)
>>> f.getprop('leap_month')
11
>>> f.delprop('leap_month')
leap_year

The leap_year CF property.

Provides an example of a leap year for a user defined calendar. It is assumed that all years that differ from this year by a multiple of four are also leap years. See http://cfconventions.org/latest.html for details.

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')
long_name

The long_name CF property.

A descriptive name that indicates a nature of the data. This name is not standardized. See http://cfconventions.org/latest.html for details.

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')
mask

The mask of the data array.

Values of True indicate masked elements.

See also

binary_mask

Examples: 
>>> f.shape
(12, 73, 96)
>>> m = f.mask
>>> m.long_name
'mask'
>>> m.shape
(12, 73, 96)
>>> m.dtype
dtype('bool')
>>> m.data
<CF Data: [[[True, ..., False]]] >
minute

The minute of each date-time data array element.

Only applicable to data arrays with reference time units.

See also

year, month, day, hour, second`

Examples: 
>>> f.dtarray
[ 450-11-15 00:00:00  450-12-16 12:30:00  451-01-16 12:00:45]
>>> f.minute.array
[ 0 30  0]
missing_value

The missing_value CF property.

A value used to represent missing or undefined data (deprecated by the netCDF user guide). See http://cfconventions.org/latest.html for details.

Note that this attribute is used primarily for writing data to disk and is independent of the missing data mask. It may, however, be used when unmasking data array elements.

The recommended way of retrieving the missing data value is with the fill_value method.

See also

_FillValue, fill_value

Examples: 
>>> f.missing_value = 1.0e30
>>> f.missing_value
1e+30
>>> del f.missing_value

Mask the data array where it equals a missing data value:

>>> f.setitem(cf.masked, condition=f.fill_value()) DCH
month

The month of each date-time data array element.

Only applicable to data arrays with reference time units.

See also

year, day, hour, minunte, second`

Examples: 
>>> f.dtarray
[ 450-11-15 00:00:00  450-12-16 12:30:00  451-01-16 12:00:45]
>>> f.month.array
[11 12  1]
month_lengths

The month_lengths CF property.

Specifies the length of each month in a non-leap year for a user defined calendar. See http://cfconventions.org/latest.html for details.

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')
ndim

The number of dimensions in the data array.

See also

data, hasdata, isscalar, shape

Examples: 
>>> f.hasdata
True
>>> f.shape
(73, 96)
>>> f.ndim
2

>>> f.shape
()
>>> f.ndim
0
scale_factor

The scale_factor CF property.

If present then the data are divided by this factor prior to it being written to a file. If both scale_factor and add_offset properties are present, the offset is subtracted before the data are scaled. See http://cfconventions.org/latest.html for details.

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')
second

The second of each date-time data array element.

Only applicable to data arrays with reference time units.

See also

year, month, day, hour, minute

Examples: 
>>> f.dtarray
[ 450-11-15 00:00:00  450-12-16 12:30:00  451-01-16 12:00:45]
>>> f.second.array
[ 0  0 45]
shape

A tuple of the data array’s dimension sizes.

See also

data, hasdata, ndim, size

Examples: 
>>> f.shape
(73, 96)
>>> f.ndim
2

>>> f.ndim
0
>>> f.shape
()

>>> f.hasdata
True
>>> len(f.shape) == f.dnim
True
>>> reduce(lambda x, y: x*y, f.shape, 1) == f.size
True
size

The number of elements in the data array.

See also

data, hasdata, ndim, shape

Examples: 
>>> f.shape
(73, 96)
>>> f.size
7008

>>> f.shape
()
>>> f.ndim
0
>>> f.size
1

>>> f.shape
(1, 1, 1)
>>> f.ndim
3
>>> f.size
1

>>> f.hasdata
True
>>> f.size == reduce(lambda x, y: x*y, f.shape, 1)
True
standard_name

The standard_name CF property.

A standard name that references a description of a data in the standard name table (http://cfconventions.org/standard-names.html). See http://cfconventions.org/latest.html for details.

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')
subspace

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:
units

The units CF property.

The units of the data. The value of the units property is a string that can be recognized by UNIDATA’s Udunits package (http://www.unidata.ucar.edu/software/udunits). See http://cfconventions.org/latest.html for details.

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')
unsafe_array
valid_max

The valid_max CF property.

The largest valid value of the data. See http://cfconventions.org/latest.html for details.

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')
valid_min

The valid_min CF property.

The smallest valid value of the data. See http://cfconventions.org/latest.html for details.

Examples: 
>>> f.valid_min = 8.0
>>> f.valid_min
8.0
>>> del f.valid_min

>>> f.setprop('valid_min', 8.0)
>>> f.getprop('valid_min')
8.0
>>> f.delprop('valid_min')
valid_range

The valid_range CF property.

The smallest and largest valid values the data. See http://cfconventions.org/latest.html for details.

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')
varray

A numpy array view of the data array.

Changing the elements of the returned view changes the data array.

See also

array, data, dtarray, dtvarray

Examples 1: 
>>> f.data
<CF Data: [0, ... 4] kg m-1 s-2>
>>> 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
[999 1 2 3 4]
>>> f.data
<CF Data: [999, ... 4] kg m-1 s-2>
year

The year of each date-time data array element.

Only applicable to data arrays with reference time units.

See also

month, day, hour, minunte, second`

Examples: 
>>> f.dtarray
[ 450-11-15 00:00:00  450-12-16 12:30:00  451-01-16 12:00:45]
>>> f.year.array
[450 450 451]