cf.BoundedVariable

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

Bases: cf.variable.Variable

Base class for CF dimension coordinate, auxiliary coordinate and domain ancillary objects.

Initialization

Parameters:
Parameters:
properties: dict, optional

Initialize a new instance with CF properties from a dictionary’s key/value pairs.

attributes: dict, optional

Provide the new instance with attributes from a dictionary’s key/value pairs.

data: cf.Data, optional

Provide the new instance with an N-dimensional data array.

bounds: cf.Data or cf.Bounds, optional

Provide the new instance with cell bounds.

source: cf.BoundedVariable, optional

Take the attributes, CF properties and data array from the source object. Any attributes, CF properties or data array specified with other parameters are set after initialisation from the source instance.

copy: bool, optional

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

Initialization

Parameters:
Parameters:
properties: dict, optional

Initialize a new instance with CF properties from a dictionary’s key/value pairs.

attributes: dict, optional

Provide the new instance with attributes from a dictionary’s key/value pairs.

data: cf.Data, optional

Provide the new instance with an N-dimensional data array.

bounds: cf.Data or cf.Bounds, optional

Provide the new instance with cell bounds.

source: cf.BoundedVariable, optional

Take the attributes, CF properties and data array from the source object. Any attributes, CF properties or data array specified with other parameters are set after initialisation from the source instance.

copy: bool, optional

If False then do not 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 bounded variables 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 bounded variable.
concatenate(variables[, axis, _preserve]) Join a sequence of variables together.
contiguous([overlap]) Return True if a {+variable} has contiguous cells.
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.
direction() Return None, indicating that it is not specified whether the values are increasing or decreasing.
dump([display, omit, field, key, _level, _title]) Return a string containing a full description of the variable.
equals(other[, rtol, atol, …]) True if two bounded variables are equal, False otherwise.
equivalent(other[, rtol, atol, traceback]) True if two bounded variables 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 and bounds 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 bounded variable.
index(x[, start, stop]) L.index(value, [start, [stop]]) – return first index of value.
insert_bounds(bounds[, copy]) Insert cell bounds.
insert_data(data[, bounds, copy]) Insert a new data array.
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 bounded variable.
override_calendar(calendar[, i]) Override the calendar of date-time units.
override_units(new_units[, i])

New in version 2.0.
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 bounded variable 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.BoundedVariable.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.
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.

Attributes

Data The cf.Data object containing the data array.
T Always False.
Units The Units object containing the units of the data array.
X Always False.
Y Always False.
Z Always False.
add_offset The add_offset CF property.
array A numpy array deep copy of the data array.
binary_mask A binary (0 and 1) missing data mask of the data array.
bounds The cf.Bounds object containing the cell bounds.
calendar The calendar CF property.
cellsize A cf.Data object containing the variable cell sizes.
comment The comment CF property.
data The cf.Data object containing the data array.
day The day of each date-time data array element.
dtarray An independent numpy array of date-time objects.
dtvarray A numpy array view the data array converted to date-time objects.
dtype Numpy data-type of the data array.
hardmask Whether the mask is hard (True) or soft (False).
hasbounds True if there are cell bounds.
hasdata True if there is a data array.
history The history CF property.
hour The hour of each date-time data array element.
isauxiliary True if the variable is an auxiliary coordinate object.
isdimension True if the variable is a dimension coordinate object.
isdomainancillary True if the variable is a domain ancillary object.
isfieldancillary True if the variable is a field ancillary object.
ismeasure True if the variable is a cell measure object.
isperiodic

New in version 2.0.
isscalar True if the data array is scalar.
leap_month The leap_month CF property.
leap_year The leap_year CF property.
long_name The long_name CF property.
lower_bounds The lower cell bounds.
mask The mask of the data array.
minute The minute of each date-time data array element.
missing_value The missing_value CF property.
month The month of each date-time data array element.
month_lengths The month_lengths CF property.
ndim The number of dimensions in the data array.
reference_datetime
scale_factor The scale_factor CF property.
second The second of each date-time data array element.
shape A tuple of the data array’s dimension sizes.
size The number of elements in the data array.
standard_name The standard_name CF property.
subspace Return a new bounded variable whose data and bounds are subspaced in a consistent manner.
units The units CF property.
unsafe_array
upper_bounds The upper cell bounds.
valid_max The valid_max CF property.
valid_min The valid_min CF property.
valid_range The valid_range CF property.
varray A numpy array view of the data array.
year The year of each date-time data array element.
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 bounded variable. 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 bounded variables 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.BoundedVariable.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 bounded variables 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 bounded variable in place. By default a new bounded variable is created. In either case, a bounded variable is returned.
Returns:

out: cf.BoundedVariable
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 bounded variables 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 bounded variable in place. By default a new bounded variable is created. In either case, a bounded variable is returned.
Returns:

out: cf.BoundedVariable
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 bounded variable 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 bounded variable’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 bounded variable with the ceiling of the data:

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

If True then update the bounded variable in place. By default a new bounded variable is created. In either case, a bounded variable is returned.
Returns:
out: cf.BoundedVariable

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

New in version 2.0.

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 bounded variable in place. By default a new bounded variable is created. In either case, a bounded variable is returned.
Returns:

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

Close all files referenced by the bounded variable.

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

axis: int, optional

_preserve: bool, optional
Returns:

out: cf.BoundedVariable
classmethod contiguous(overlap=True)[source]

Return True if a {+variable} has contiguous cells.

A {+variable} is contiguous if its cell boundaries match up, or overlap, with the boundaries of adjacent cells.

In general, it is only possible for a zero, 1 or 2 dimensional {+variable} with bounds to be contiguous. A size 1 {+variable} with any number of dimensions is always contiguous.

An exception occurs if the {+variable} is multdimensional and has more than one element.

New in version 2.0.

Parameters:
overlap : bool, optional

If False then overlapping cell boundaries are not considered contiguous. By default cell boundaries are considered contiguous.
Returns:
out: bool

Whether or not the {+variable} is contiguous.
Raises:
ValueError:

If the {+variable} has more than one dimension.
Examples: 
>>> c.hasbounds
False
>>> c.contiguous()
False

>>> print c.bounds[:, 0]
[  0.5   1.5   2.5   3.5 ]
>>> print c.bounds[:, 1]
[  1.5   2.5   3.5   4.5 ]
>>> c.contiuous()
True

>>> print c.bounds[:, 0]
[  0.5   1.5   2.5   3.5 ]
>>> print c.bounds[:, 1]
[  2.5   3.5   4.5   5.5 ]
>>> c.contiuous()
True
>>> c.contiuous(overlap=False)
False
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: 
>>> d = c.convert_reference_time()
Parameters:
units: cf.Units, optional

The reference time units to convert to. By default the units are “days since the original reference time in 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 bounded variable in place. By default a new bounded variable is created. In either case, a bounded variable is returned.
Returns:
out: cf.BoundedVariable

The bounded variable with converted reference time data values.
Examples 2: 
>>> print c.Units
months since 2000-1-1
>>> print c.array
[1 3]
>>> print c.dtarray
[datetime.datetime(2000, 1, 31, 10, 29, 3, 831197)
 datetime.datetime(2000, 4, 1, 7, 27, 11, 493645)]
>>> print c.bounds.array
[[ 0  2]
 [ 2  4]]
>>> print c.bounds.dtarray
[[datetime.datetime(2000, 1, 1, 0, 0) datetime.datetime(2000, 3, 1, 20, 58, 7, 662441)]
 [datetime.datetime(2000, 3, 1, 20, 58, 7, 662441) datetime.datetime(2000, 5, 1, 17, 56, 15, 324889)]]
>>> c.convert_reference_time(calendar_months=True, i=True)
>>> print c.Units
days since 2000-1-1
>>> print c.array
[  31.,  91.]
>>> print c.dtarray
[datetime.datetime(2000, 2, 1, 0, 0)
 datetime.datetime(2000, 4, 1, 0, 0)]
>>> print c.bounds.dtarray
[[datetime.datetime(2000, 1, 1, 0, 0) datetime.datetime(2000, 3, 1, 0, 0)]
 [datetime.datetime(2000, 3, 1, 0, 0) datetime.datetime(2000, 5, 1, 0, 0)]]
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.BoundedVariable

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 bounded variable in place. By default a new bounded variable is created. In either case, a bounded variable is returned.
Returns:
out: cf.BoundedVariable

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

New in version 2.0.

See also

getprop, hasprop, setprop

Parameters:
prop : str

The name of the CF property.
Returns:

None
Examples: 
>>> c.delprop('standard_name')
>>> c.delprop('foo')
AttributeError: BoundedVariable doesn't have CF property 'foo'
direction()[source]

Return None, indicating that it is not specified whether the values are increasing or decreasing.

New in version 2.0.

Returns:None
Examples: 
>>> print c.direction()
None
dump(display=True, omit=(), field=None, key=None, _level=0, _title=None)[source]

Return a string containing a full description of the variable.

New in version 2.0.

Parameters:
display: bool, optional

If False then return the description as a string. By default the description is printed, i.e. c.dump() is equivalent to print c.dump(display=False).

omit: sequence of str

Omit the given CF properties from the description.
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 bounded variables 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 bounded variables differ.

ignore: tuple, optional

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

Whether or not the two bounded variables 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 bounded variables 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 bounded variable in place. By default a new bounded variable is created. In either case, a bounded variable is returned.
Returns:
out: cf.BoundedVariable

The bounded variable 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 bounded variable in place. By default a new bounded variable is created. In either case, a bounded variable 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 and bounds in place.

The trailing dimension of the bounds is flipped if and only if the bounded variable is 1 or 0 dimensional.

New in version 2.0.

Parameters:
axes : (sequence of) int, optional

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

i: bool, optional

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

out : cf.BoundedVariable
Examples: 
>>> c.flip()
>>> c.flip(1)

>>> d = c[::-1, :, ::-1, :]
>>> c.flip([2, 0]).equals(d)
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 bounded variable in place. By default a new bounded variable is created. In either case, a bounded variable is returned.
Returns:
out: cf.BoundedVariable

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

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 bounded variable 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_bounds(bounds, copy=True)[source]

Insert cell bounds.

New in version 2.0.

Parameters:

bounds: data-like

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.

copy: bool, optional
Returns:

None
insert_data(data, bounds=None, copy=True)[source]

Insert a new data array.

A bounds data array may also inserted if given with the bounds keyword. Bounds may also be inserted independently with the insert_bounds method.

New in version 2.0.

Parameters:

data : cf.Data

bounds : cf.Data, optional

copy : bool, optional
Returns:

None
inspect()[source]

Inspect the object for debugging.

See also

cf.inspect

Examples 1: 
>>> f.inspect()
Returns:None
log(base=None, 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 bounded variable in place. By default a new bounded variable is created. In either case, a bounded variable is returned.
Returns:
out: cf.BoundedVariable

The bounded variable 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 bounded variable in place. By default a new bounded variable is created. In either case, a bounded variable is returned.
Returns:

out: cf.BoundedVariable
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 bounded variable.

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

New in version 2.1.14.

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

The new calendar.

i: bool, optional

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

out: cf.BoundedVariable
Examples 2:
override_units(new_units, i=False)[source]
New in version 2.0:
i: bool, optional
If True then update the bounded variable in place. By default a new bounded variable is created. In either case, a bounded variable is returned.
properties(props=None, clear=False, copy=True)[source]

Inspect or change the CF properties.

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

Set bounded variable 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 bounded variable’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 bounded variable in place. By default a new bounded variable is created. In either case, a bounded variable is returned.
Returns:
out: cf.BoundedVariable

The bounded variable 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 bounded variable along an axis.

See also

expand_dims, flip, squeeze, transpose

Parameters:

iaxis: int

i: bool, optional

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

out: cf.BoundedVariable
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 bounded variable in place. By default a new bounded variable is created. In either case, a bounded variable is returned.
Returns:
out: cf.BoundedVariable

The bounded variable 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.BoundedVariable.select has been deprecated.

Use cf.BoundedVariable.match to see if an individual bounded variable meets given criteria.

setprop(prop, value)[source]

Set a CF property.

New in version 2.0.

See also

delprop, getprop, hasprop

Parameters:
prop : str

The name of the CF property.

value :

The value for the property.
Returns:

None
Examples: 
>>> c.setprop('standard_name', 'time')
>>> c.setprop('foo', 12.5)
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 bounded variable in place. By default a new bounded variable is created. In either case, a bounded variable is returned.
Returns:
out: cf.BoundedVariable

The bounded variable 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 bounded variable in place. By default a new bounded variable is created. In either case, a bounded variable is returned.
Returns:

out: cf.BoundedVariable
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 bounded variable in place. By default a new bounded variable is created. In either case, a bounded variable is returned.
Returns:
out: cf.BoundedVariable

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

Permute the dimensions of the data.

New in version 2.0.

See also

expand_dims, flip, squeeze

Parameters:
axes : (sequence of) int, optional

The new order of the data array. By default, reverse the dimensions’ order, otherwise the axes are permuted according to the values given. The values of the sequence comprise the integer positions of the dimensions in the data array in the desired order.

i: bool, optional

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

out : cf.BoundedVariable
Examples: 
>>> c.ndim
3
>>> c.transpose()
>>> c.transpose([1, 2, 0])
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 bounded variable in place. By default a new bounded variable is created. In either case, a bounded variable is returned.
Returns:
out: cf.BoundedVariable

The bounded variable 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.BoundedVariable
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 Units object containing the units of the data array.

New in version 2.0.

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

The cf.Bounds object containing the cell bounds.

New in version 2.0.

See also

lower_bounds, upper_bounds

Examples: 
>>> c
<CF {+Variable}: latitude(64) degrees_north>
>>> c.bounds
<CF Bounds: latitude(64, 2) degrees_north>
>>> c.bounds = b
AttributeError: Can't set 'bounds' attribute. Consider the insert_bounds method.
>>> c.bounds.max()
<CF Data: 90.0 degrees_north>
>>> c.bounds -= 1
AttributeError: Can't set 'bounds' attribute. Consider the insert_bounds method.
>>> b = c.bounds
>>> b -= 1
>>> c.bounds.max()       
<CF Data: 89.0 degrees_north>
calendar

The calendar CF property.

This property is a mirror of the calendar stored in the Units attribute.

New in version 2.0.

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

>>> c.setprop('calendar', 'proleptic_gregorian')
>>> c.getprop('calendar')
'proleptic_gregorian'
>>> c.delprop('calendar')
cellsize

A cf.Data object containing the variable cell sizes.

New in version 2.0.

Examples: 
>>> print c.bounds
<CF {+Variable}: latitude(47, 2) degrees_north>
>>> print c.bounds.array
[[-90. -87.]
 [-87. -80.]
 [-80. -67.]]
>>> print d.cellsize
<CF Data: [3.0, ..., 13.0] degrees_north>
>>> print d.cellsize.array
[  3.   7.  13.]
>>> print c.sin().cellsize.array
[ 0.00137047  0.01382178  0.0643029 ]

>>> del c.bounds
>>> c.cellsize
AttributeError: Can't get cell sizes when cells have no bounds
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

Numpy data-type of the data array.

New in version 2.0.

Examples: 
>>> c.dtype
dtype('float64')
>>> import numpy
>>> c.dtype = numpy.dtype('float32')
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 if the variable is a field ancillary object.

New in version DCH.

See also

isauxiliary, isdimension, isdomainancillary, ismeasure

Examples: 
>>> f.isfieldancillary
False
ismeasure

True if the variable is a cell measure object.

See also

isauxiliary, isdimension, isdomainancillary, isfieldancillary

Examples: 
>>> f.ismeasure
False
isperiodic

New in version 2.0.

>>> print c.period()
None
>>> c.isperiodic
False
>>> c.period(cf.Data(360, 'degeres_east'))
None
>>> c.isperiodic
True
>>> c.period(None)
<CF Data: 360 degrees_east>
>>> c.isperiodic
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')
lower_bounds

The lower cell bounds.

The lower cell bounds are returned in a cf.Data object.

Note that c.lower_bounds is equivalent to c.bounds.data.min(axes=-1).

New in version 2.0.

See also

bounds, upper_bounds

Examples: 
>>> print c.bounds.array
[[ 5  3]
 [ 3  1]
 [ 1 -1]]
>>> c.lower_bounds
<CF Data: [3, ..., -1]>
>>> print c.lower_bounds.array
[ 3  1 -1]
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.

New in version 2.0.

Examples: 
>>> c.standard_name = 'time'
>>> c.standard_name
'time'
>>> del c.standard_name

>>> c.setprop('standard_name', 'time')
>>> c.getprop('standard_name')
'time'
>>> c.delprop('standard_name')
subspace

Return a new bounded variable whose data and bounds are subspaced in a consistent manner.

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.

New in version 2.0.

Examples:
units

The units CF property.

This property is a mirror of the units stored in the Units attribute.

New in version 2.0.

Examples: 
>>> c.units = 'degrees_east'
>>> c.units
'degree_east'
>>> del c.units

>>> c.setprop('units', 'days since 2004-06-01')
>>> c.getprop('units')
'days since 2004-06-01'
>>> c.delprop('units')
unsafe_array
upper_bounds

The upper cell bounds.

The upper cell bounds are returned in a cf.Data object.

Note that c.upper_bounds is equivalent to c.bounds.data.max(axes=-1).

New in version 2.0.

See also

bounds, lower_bounds

Examples: 
>>> print c.bounds.array
[[ 5  3]
 [ 3  1]
 [ 1 -1]]
>>> c.upper_bounds      
<CF Data: [5, ..., 1]>
>>> c.upper_bounds.array     
array([5, 3, 1])
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]