cf.Field

class cf.Field(properties={}, attributes={}, data=None, domain=None, flags=None, ancillary_variables=None, axes=None, auto_cyclic=True, copy=True)

Bases: cf.variable.Variable

A field construct according to the CF data model.

A field is a container for a data array and metadata comprising properties to describe the physical nature of the data and a coordinate system (called a domain) which describes the positions of each element of the data array.

The field’s domain may contain dimensions and auxiliary coordinate and cell measure objects (which themselves contain data arrays and properties to describe them) and coordinate reference objects.

All components of a field are optional.

Miscellaneous

Field objects are picklable.

Initialization

Parameters:

properties : dict, optional

Provide the new field with CF properties from the dictionary’s key/value pairs.

data : cf.Data, optional

Provide the new field with an N-dimensional data array in a cf.Data object.

domain : cf.Domain, optional

Provide the new field with a coordinate system in a cf.Domain object. By default an empty domain is created.

attributes : dict, optional

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

flags : cf.Flags, optional

Provide the new field with self-describing flag values.

ancillary_variables : cf.FieldList, optional

Provide the new field with ancillary variable fields.

axes : sequence of str, optional

A list of domain axis identifiers ('dimN'), stating the axes, in order, of field’s data array. By default these axis identifiers will be the sequence of consecutive axis identifiers 'dim0' up to 'dimM', where M is the number of axes of the data array, or an empty sequence if the data array is a scalar.

If an axis of the data array already exists in the domain then the it must have the same size as the domain axis. If it does not exist in the domain then a new axis will be created.

By default the axes will either be those defined for the data array by the domain or, if these do not exist, the domain axis identifiers whose sizes unambiguously match the data array.

auto_cyclic : bool, optional

If False then do not auto-detect cyclic axes. By default cyclic axes are auto-detected with the autocyclic method.

copy : bool, optional

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

CF Properties

add_offset	The add_offset CF property.
calendar	The calendar CF property.
cell_methods	The cf.CellMethods object containing the CF cell methods of the data array.
comment	The comment CF property.
Conventions	The Conventions CF property.
_FillValue	The _FillValue CF property.
flag_masks	The flag_masks CF property.
flag_meanings	The flag_meanings CF property.
flag_values	The flag_values CF property.
history	The history CF property.
institution	The institution CF property.
leap_month	The leap_month CF property.
leap_year	The leap_year CF property.
long_name	The long_name CF property.
missing_value	The missing_value CF property.
month_lengths	The month_lengths CF property.
references	The references CF property.
scale_factor	The scale_factor CF property.
source	The source CF property.
standard_error_multiplier	The standard_error_multiplier CF property.
standard_name	The standard_name CF property.
title	The title CF property.
units	The units CF property.
valid_max	The valid_max CF property.
valid_min	The valid_min CF property.
valid_range	The valid_range CF property.

Setting, retrieving and deleting non-standard (and reserved) CF properties.

delprop	Delete a CF property.
getprop	Get a CF property.
hasprop	Return True if a CF property exists, otherise False.
properties	A dictionary of the CF properties.
setprop	Set a CF property.

Domain operations

Domain axes

autocyclic	Set axes to be cyclic if they meet conditions.
axes	Return domain axis identifiers from the field.
axes_sizes	{def_axes_sizes}
axis	{def_axis}
axis_name	Return the canonical name for an axis.
axis_size	Return the size of a domain axis.
cyclic	Set the cyclicity of an axis.
data_axes	Return the domain axis identifiers for the data array dimensions.
insert_axis	Insert an axis into the domain in place.
iscyclic	Returns True if the given axis is cyclic.
item_axes	Return the axes of a domain item of the field.
items_axes	Return the axes of domain items of the field.
period	Return the period of an axis.
remove_axes	Remove and return axes from the field.
remove_axis	Remove and return a unique axis from the field.

Domain items

A domain item is a dimension coordinate, auxiliary coordinate, cell measure or coordinate reference object.

aux	Return an auxiliary coordinate object, or its domain identifier.
auxs	Return auxiliary coordinate objects.
coord	Return a dimension or auxiliary coordinate object, or its domain identifier.
coords	Return dimension and auxiliary coordinate objects of the domain.
dim	Return a dimension coordinate object, or its domain identifier.
dims	Return dimension coordinate objects.
insert_aux	Insert an auxiliary coordinate object into the domain in place.
insert_dim	Insert a dimension coordinate object into the domain in place.
insert_measure	Insert an cell measure object into the domain in place.
insert_ref	Insert a coordinate reference object into the domain in place.
item	Return an item, or its domain identifier, from the field.
items	Return domain items from the field.
measure	Return a cell measure object, or its domain identifier.
measures	Return cell measure objects.
ref	Return a coordinate reference object, or its domain identifier.
refs	Return coordinate reference objects.
remove_item	Remove and return a domain item from the field.
remove_items	Remove and return domain items from the domain.

Subspacing

indices	Create data array indices based on domain metadata.
subspace	Return a new object which will get or set a subspace of the field.

Mathematical functions

Trigonometry

cos	Take the trigonometric cosine of the data array.
sin	Take the trigonometric sine of the data array.
tan	Take the trigonometric tangent of the data array.

Exponents and logarithms

exp	The exponential of the data array.
log	The logarithm of the data array.

Rounding

ceil	The ceiling of the data array.
floor	Floor the data array.
rint	round data array.
trunc	Truncate the data array.

Statistics

collapse	Collapse axes of the field.
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.
range	The absolute difference between the maximum and minimum of the data array.
sample_size	The number of non-missing data elements in the data array.
sum	The sum of the data array.
sd	The unweighted sample standard deviation of the data array.
var	The unweighted sample variance of the data array.

Miscellaneous mathematical functions

clip	Clip (limit) the values in the data array in place.

Data array operations

Data array access

array	A numpy array deep copy of the data array.
data	The cf.Data object containing the data array.
dtype	The numpy data type of the data array.
hasdata	True if there is a data array.
ndim	The number of dimensions in the data array.
shape	A tuple of the data array’s dimension sizes.
size	The number of elements in the data array.
Units	The cf.Units object containing the units of the data array.
varray	A numpy array view of the data array.

Order and number of dimensions

expand_dims	Insert a size 1 axis into the data array.
squeeze	Remove size 1 axes from the data array.
transpose	Permute the axes of the data array.
unsqueeze	Insert size 1 axes into the data array.

Adding and removing elements

unique

The unique elements of the data array.

Rearranging elements

anchor	Roll a cyclic axis so that the given value lies in the first coordinate cell.
flip	Flip (reverse the direction of) axes of the field.
roll	Roll the field along a cyclic axis.

Miscellaneous data array operations

isscalar

True if the data array is scalar.

Regridding operations

regrids

Returns the field regridded onto a new latitude-longitude grid.

Date-time operations

asdatetime	Convert the internal representation of data array elements to date-time objects.
asreftime	Convert the internal representation of data array elements to numeric reference times.

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.
hour	The hour of each date-time data array element.
minute	The minute of each date-time data array element.
month	The month of each date-time data array element.
second	The second of each date-time data array element.
year	The year of each date-time data array element.

Logic functions

Truth value testing

all	Test whether all data array elements evaluate to True.
any	Return True if any data array elements evaluate to True.

Comparison

allclose	Returns True if two broadcastable fields have equal array values to within numerical tolerance.
equals	True if two fields are equal, False otherwise.
equivalent	True if two fields are equivalent, False otherwise
equivalent_data	Return True if two fields have equivalent data arrays.
equivalent_domain	Return True if two fields have equivalent data domains.

Set operations

unique

The unique elements of the data array.

Miscellaneous

binary_mask	Return a binary (0 and 1) missing data mask of the data array.
chunk	Partition the data array.
close	Close all files referenced by the field.
cf.Field.concatenate	Join a sequence of fields together.
copy	Return a deep copy.
datum	Return an element of the data array as a standard Python scalar.
dump	Print or return a string containing a description of the field.
fill_value	Return the data array missing data value.
identity	Return the identity.
insert_data	Insert a new data array into the field in place.
mask_invalid	Mask the array where invalid values occur (NaN or inf).
match	Test whether or not the field satisfies the given conditions.
name	Return a name.
override_units	Override the data array units.
cf.Field.override_calendar
promote	Create an independent field from a domain item.
remove_data	Remove and return the data array of the field.
select	Return the field if it satisfies the given conditions.
weights	Return weights for the data array values.
where	Set data array elements depending on a condition.

attributes	A dictionary of the attributes which are not CF properties.
domain	The cf.Domain object containing the field’s domain.
Flags	A cf.Flags object containing self-describing CF flag values.
hardmask	Whether the mask is hard (True) or soft (False).
hasbounds	True if there are cell bounds.
isauxiliary	True if the variable is an auxiliary coordinate object.
isdimension	True if the variable is a dimension coordinate object.
ismeasure	True if the variable is a cell measure object.
mask	A variable containing the mask of the data array.
rank	The number of axes in the domain.
T	Returns False.
X	Returns False.
Y	Returns False.
Z	Returns False.

List-like operations

These methods view the field as a single element field list, e.g. f.count(g) is equivalent to cf.FieldList(f).count(g).

count	Emulate
index	L.index(value, [start, [stop]]) – return first index of value.
reverse	L.reverse() – reverse IN PLACE
sort	Sort the field, viewed as a single element field list, in place.
__contains__	Called to implement membership test operators.
__getitem__	Called to implement evaluation of f[index].
__len__	Called by the len built-in function.

Arithmetic and comparison operations

Arithmetic, bitwise and comparison operations are defined on a field as element-wise operations on its data array which yield a new cf.Field object or, for augmented assignments, modify the field’s data array in-place.

Comparison operators

__lt__	The rich comparison operator <
__le__	The rich comparison operator <=
__eq__	The rich comparison operator ==
__ne__	The rich comparison operator !=
__gt__	The rich comparison operator >
__ge__	The rich comparison operator >=

Binary arithmetic operators

__add__	The binary arithmetic operation +
__sub__	The binary arithmetic operation -
__mul__	The binary arithmetic operation *
__div__	The binary arithmetic operation /
__truediv__	The binary arithmetic operation / (true division)
__floordiv__	The binary arithmetic operation //
__pow__	The binary arithmetic operations ** and pow
__mod__	The binary arithmetic operation %

Binary arithmetic operators with reflected (swapped) operands

__radd__	The binary arithmetic operation + with reflected operands
__rsub__	The binary arithmetic operation - with reflected operands
__rmul__	The binary arithmetic operation * with reflected operands
__rdiv__	The binary arithmetic operation / with reflected operands
__rtruediv__	The binary arithmetic operation / (true division) with reflected
__rfloordiv__	The binary arithmetic operation // with reflected operands
__rpow__	The binary arithmetic operations ** and pow with reflected
__rmod__	The binary arithmetic operation % with reflected operands

Augmented arithmetic assignments

__iadd__	The augmented arithmetic assignment +=
__isub__	The augmented arithmetic assignment -=
__imul__	The augmented arithmetic assignment *=
__idiv__	The augmented arithmetic assignment /=
__itruediv__	The augmented arithmetic assignment /= (true division)
__ifloordiv__	The augmented arithmetic assignment //=
__ipow__	The augmented arithmetic assignment **=
__imod__	The binary arithmetic operation %=

Unary arithmetic operators

__neg__	The unary arithmetic operation -
__pos__	The unary arithmetic operation +
__abs__	The unary arithmetic operation abs

Binary bitwise operators

__and__	The binary bitwise operation &
__or__	The binary bitwise operation |
__xor__	The binary bitwise operation ^
__lshift__	The binary bitwise operation <<
__rshift__	The binary bitwise operation >>

Binary bitwise operators with reflected (swapped) operands

__rand__	The binary bitwise operation & with reflected operands
__ror__	The binary bitwise operation | with reflected operands
__rxor__	The binary bitwise operation ^ with reflected operands
__rlshift__	The binary bitwise operation << with reflected operands
__rrshift__	The binary bitwise operation >> with reflected operands

Augmented bitwise assignments

__iand__	The augmented bitwise assignment &=
__ior__	The augmented bitwise assignment |=
__ixor__	The augmented bitwise assignment ^=
__ilshift__	The augmented bitwise assignment <<=
__irshift__	The augmented bitwise assignment >>=

Unary bitwise operators

__invert__

The unary bitwise operation ~

Special methods

__deepcopy__	Called by the copy.deepcopy standard library function.
__repr__	Called by the repr built-in function.
__str__	Called by the str built-in function.