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 CFnetCDF data variable with all of its metadata. All CFnetCDF 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 incf.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 incf.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
objectsDimension coordinate Domain cell locations stored in cf.DimensionCoordinate
objectsAuxiliary coordinate Domain cell locations stored in cf.AuxiliaryCoordinate
objectsCoordinate reference Domain coordinate systems stored in cf.CoordinateReference
objectsDomain ancillary Cell locations in alternative coordinate systems stored in cf.DomainAncillary
objectsCell measure Domain cell size or shape stored in cf.CellMeasure
objectsAll 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 selfdescribing 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'
, whereM
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 autodetect cyclic axes. By default cyclic axes are autodetected with the
autocyclic
method. copy:
bool
, optional If False then do not deep copy arguments prior to initialization. By default arguments are deep copied.
 properties:
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 nonstandard (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 builtin function. 
__str__ 
Called by the str builtin 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 nonmissing 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 datetime units. 
Data array mask
binary_mask 
A binary (0 and 1) missing data mask of the data array. 
count 
Count the nonmasked 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 size1 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 latitudelongitude grid. 
Datetime operations¶
day 
The day of each datetime data array element. 
dtarray 
An independent numpy array of datetime objects. 
hour 
The hour of each datetime data array element. 
minute 
The minute of each datetime data array element. 
month 
The month of each datetime data array element. 
second 
The second of each datetime data array element. 
year 
The year of each datetime 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 selfdescribing 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 elementwise operations on its data array which yield a new
cf.Field
object or, for augmented assignments, modify the field’s
data array inplace.
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 operands 
__rfloordiv__ 
The binary arithmetic operation // with reflected operands 
__rpow__ 
The binary arithmetic operations ** and pow with reflected operands 
__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. 