cf.Field

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

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 object

domain The cf.Domain object containing the field’s domain.

Domain axes

autocyclic Set axes to be cyclic if they meet conditions.
axes Return domain axis identifiers from the field.
axes_sizes Return the sizes of domain axes.
axis Return a domain axis identifier from the field.
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.
weights Return weights for the data array values.

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.
datum Return an element of the data array as a standard Python scalar.
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.
varray A numpy array view of the data array.

Data array units

calendar The calendar CF property.
units The units CF property.
Units The cf.Units object containing the units of the data array.
override_units Override the units.
override_calendar Override the calendar of date-time units.

Data array mask

binary_mask A binary (0 and 1) missing data mask of the data array.
hardmask Whether the mask is hard (True) or soft (False).
mask The mask of the data array.
fill_value Return the data array missing data value.

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.

Changing data array values

indices Create data array indices based on domain metadata.
mask_invalid Mask the array where invalid values occur (NaN or inf).
subspace Return a new object which will get or set a subspace of the field.
where Set data array elements depending on a condition.

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

chunk Partition the data array.
insert_data Insert a new data array into the field in place.
isscalar True if the data array is scalar.
remove_data Remove and return the data array.

Regridding operations

regridc Returns the field with the specified Cartesian axes regridded onto a new grid.
regrids Returns the field regridded onto a new latitude-longitude grid.

Date-time operations

day The day of each date-time data array element.
dtarray An independent numpy array of 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.
convert_reference_time Convert reference time data values to have new units.

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

close Close all files referenced by the field.
cf.Field.concatenate Join a sequence of fields together.
copy Return a deep copy.
dump Print or return a string containing a description of the field.
field Create an independent field from a domain item.
files Return the names of any files containing parts of the data array.
HDF_chunks Specify HDF5 chunks for the data array.
identity Return the identity.
match Test whether or not the field satisfies the given conditions.
name Return a name.
select Return the field if it satisfies the given conditions.
unlimited Todo ...
attributes A dictionary of the attributes which are not CF properties.
Flags A cf.Flags object containing self-describing CF flag values.
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.
rank The number of axes in the domain.
T Always False.
X Always False.
Y Always False.
Z Always 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.