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)[source]

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 indices based on domain metadata that define a subspace of the field.

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.
derivative Return the centred finite difference along the specified axis.

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.
count Count the non-masked elements of the 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 indices based on domain metadata that define a subspace of the field.
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.