cf.Field

class cf.Field(properties={}, attributes={}, data=None, flags=None, field_anc=None, dim=None, aux=None, measure=None, ref=None, domain_anc=None, auto_cyclic=True, source=None, copy=True)

Bases: cf.variable.Variable

A CF field construct.

The field construct is central to the CF data model, and includes all the other constructs. A field corresponds to a CF-netCDF data variable with all of its metadata. All CF-netCDF elements are mapped to some element of the CF field construct and the field constructs completely contain all the data and metadata which can be extracted from the file using the CF conventions.

The field construct consists of a data array (stored in a cf.Data object) and the definition of its domain, ancillary metadata fields defined over the same domain (stored in cf.DomainAncillary objects), and cell methods constructs to describe how the cell values represent the variation of the physical quantity within the cells of the domain (stored in cf.CellMethod objects).

The domain is defined collectively by various other constructs included in the field:

Domain construct	Description
Domain axis	Independent axes of the domain stored in cf.DomainAxis objects
Dimension coordinate	Domain cell locations stored in cf.DimensionCoordinate objects
Auxiliary coordinate	Domain cell locations stored in cf.AuxiliaryCoordinate objects
Coordinate reference	Domain coordinate systems stored in cf.CoordinateReference objects
Domain ancillary	Cell locations in alternative coordinate systems stored in cf.DomainAncillary objects
Cell measure	Domain cell size or shape stored in cf.CellMeasure objects

All of the constructs contained by the field construct are optional.

The field construct also has optional properties to describe aspects of the data that are independent of the domain. These correspond to some netCDF attributes of variables (e.g. units, long_name and standard_name), and some netCDF global file attributes (e.g. history and institution).

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 a data array.

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.

axes: sequence of str, optional

A list of domain axis identifiers ('dimN'), stating the axes, in order, of the 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	Inspect or change the CF properties.
setprop	Set a CF property.

Inspection

__repr__	Called by the repr built-in function.
__str__	Called by the str built-in function.
constructs	Return all of the data model constructs of the field.
dump	A full description of the field.
files	Return the names of any files containing parts of the data array.
identity	Return the identity of the field.
match	Test whether or not the field satisfies the given conditions.
name	Return a name for the field.

Domain axes

autocyclic	Set axes to be cyclic if they meet conditions.
axes	Return domain axis identifiers from the field.
cf.Field.axes_sizes
axis	Return a domain 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 axes for the data array dimensions.
insert_axis	Insert a domain axis into the field.
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 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.

Field items

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

aux	Return an auxiliary coordinate object.
auxs	Return auxiliary coordinate objects.
coord	Return a dimension or auxiliary coordinate object.
coords	Return dimension and auxiliary coordinate objects of the field.
dim	Return a dimension coordinate object, or its identifier.
dims	Return dimension coordinate objects.
domain_anc	Return a domain ancillary object, or its identifier.
domain_ancs	Return domain ancillary objects.
field_anc	Return a field ancillary object.
field_ancs	Return ancillary variable objects.
insert_aux	Insert an auxiliary coordinate object into the field.
insert_cell_methods	Insert one or more cell method objects into the field.
insert_dim	Insert a dimension coordinate object into the field.
insert_domain_anc	Insert a domain ancillary object into the field.
insert_field_anc	Insert a field ancillary object into the field.
insert_measure	Insert a cell measure object into the field.
insert_ref	Insert a coordinate reference object into the field.
item	Return a field item.
items	Return items of the field.
measure	Return a cell measure object, or its identifier.
measures	Return cell measure objects.
ref	Return a coordinate reference object.
refs	Return coordinate reference objects.
remove_item	Remove and return an item from the field.
remove_items	Remove and return items from the field.

Subspacing

subspace

Create a subspace of the field.

__getitem__	f.__getitem__(indices) <==> f[indices]
indices	Create data array indices based on domain metadata.

Mathematical functions

Trigonometry

cos	Take the trigonometric cosine of the data array.
sin	The trigonometric sine of the data array.
tan	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

cell_area	Return a field containing horizontal cell areas.
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	Limit the values in the data array.

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

__setitem__	Called to implement assignment to x[indices]=value
indices	Create data array indices based on domain metadata.
mask_invalid	Mask the array where invalid values occur.
subspace	Create 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 data array into the field.
isscalar	True if the data array is scalar.
remove_data	Remove and return the data array.

Regridding operations

regridc	Return the field with the specified Cartesian axes regridded onto a new grid.
regrids	Return 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.
cf.Field.equivalent_domain

Set operations

unique

The unique elements of the data array.

Miscellaneous

attributes	Inspect or change attributes which are not CF properties.
close	Close all files referenced by the field.
cf.Field.concatenate	Join a sequence of fields together.
copy	Return a deep copy.
field	Create an independent field from a domain item.
HDF_chunks	Specify HDF5 chunks for the data array.
unlimited	Todo …

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.

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.