cf.Field¶

class
cf.
Field
(properties=None, source=None, copy=True, _use_data=True)[source]¶ Bases:
cf.mixin.propertiesdata.PropertiesData
,cfdm.field.Field
A field construct of the CF data model.
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 a field construct or some element of the CF field construct. The field construct contains all the data and metadata which can be extracted from the file using the CF conventions.
The field construct consists of a data array and the definition of its domain (that describes the locations of each cell of the data array), field ancillary constructs containing metadata defined over the same domain, and cell method constructs to describe how the cell values represent the variation of the physical quantity within the cells of the domain. The domain is defined collectively by the following constructs of the CF data model: domain axis, dimension coordinate, auxiliary coordinate, cell measure, coordinate reference and domain ancillary constructs.
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).
NetCDF interface
The netCDF variable name of the construct may be accessed with the
nc_set_variable
,nc_get_variable
,nc_del_variable
andnc_has_variable
methods.The selection of properties to be written as netCDF global attributes may be accessed with the
nc_global_attributes
,nc_clear_global_attributes
andnc_set_global_attribute
methods.Initialization
Parameters:  properties:
dict
, optional Set descriptive properties. The dictionary keys are property names, with corresponding values. Ignored if the source parameter is set.
 Parameter example:
properties={'standard_name': 'air_temperature'}
Properties may also be set after initialisation with the
set_properties
andset_property
methods. source: optional
Initialize the properties, data and metadata constructs from those of source.
 copy:
bool
, optional If False then do not deep copy input parameters prior to initialization. By default arguments are deep copied.
 properties:
Inspection¶
Methods
dump 
A full description of the field construct. 
identity 
Return the canonical identity. 
identities 
Return all possible identities. 
Attributes
construct_type 
Return a description of the construct type. 
id 
A canonical identity. 
Selection¶
Methods
match_by_construct 
Whether or not metadata constructs satisfy conditions. 
match_by_identity 
Whether or not the construct identity satisfies conditions. 
match_by_naxes 
Whether or not the data has a given dimensionality. 
match_by_ncvar 
Whether or not the construct has a netCDF variable name. 
match_by_property 
Whether or not properties satisfy conditions. 
match_by_rank 
Whether or not the number of domain axis constructs satisfy conditions. 
match_by_units 
Whether or not the construct has given units. 
Properties¶
Methods
del_property 
Remove a property. 
get_property 
Get a CF property. 
has_property 
Whether a property has been set. 
set_property 
Set a property. 
properties 
Return all properties. 
clear_properties 
Remove all properties. 
set_properties 
Set properties. 
Attributes
add_offset 
The add_offset CF property. 
calendar 
The calendar CF property. 
cell_methods 
Return cell method constructs. 
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. 
Units¶
override_units 
Override the units. 
override_calendar 
Override the calendar of datetime units. 
Units 
The cf.Units object containing the units of the data array. 
Data¶
Methods
del_data 
Remove the data. 
get_data 
Return the data. 
has_data 
Whether a data has been set. 
set_data 
Set the field construct data. 
del_data_axes 
Remove the keys of the domain axis constructs spanned by the data of the field or of a metadata construct. 
get_data_axes 
Return the keys of the domain axis constructs spanned by the data of a metadata construct. 
has_data_axes 
Whether the domain axis constructs spanned by the data of the field or of a metadata construct have been set. 
set_data_axes 
Set the domain axis constructs spanned by the data of the field or of a metadata construct. 
Attributes
array 
A numpy array deep copy of the data array. 
data 
The Data object containing the data array. 
datetime_array 
An independent numpy array of datetime objects. 
datum 
Return an element of the data array as a standard Python scalar. 
dtype 
The numpy data type of the 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. 
Rearranging elements
anchor 
Roll a cyclic axis so that the given value lies in the first coordinate cell. 
flatten 
Flatten axes of the field. 
flip 
Flip (reverse the direction of) axes of the field. 
insert_dimension 
Insert a size 1 axis into the data array. 
roll 
Roll the field along a cyclic axis. 
squeeze 
Remove size1 axes from the data array. 
swapaxes 
Interchange two axes of the data. 
transpose 
Permute the axes of the data array. 
unsqueeze 
Insert size 1 axes into the data array. 
Data array mask
fill_value 
Return the data array missing data value. 
binary_mask 
A binary (0 and 1) missing data mask of the data array. 
count 
Count the nonmasked elements of the data. 
count_masked 
Count the masked elements of the data. 
hardmask 
Whether the mask is hard (True) or soft (False). 
mask 
The mask of the data array. 
mask_invalid 
Mask the array where invalid values occur. 
Changing data values
__setitem__ 
Called to implement assignment to x[indices]=value 
indices 
Create indices that define a subspace of the field construct. 
mask_invalid 
Mask the array where invalid values occur. 
subspace 
Create a subspace of the field construct. 
where 
Assign to data elements depending on a condition. 
Miscellaneous data operations¶
Methods
chunk 
Partition the data array. 
close 
Close all files referenced by the field. 
cyclic 
Set the cyclicity of an axis. 
files 
Return the names of any files containing parts of the data array. 
Metadata constructs¶
Methods
construct 
Select a metadata construct by its identity. 
construct_key 
Select the key of a metadata construct by its identity. 
del_construct 
Remove a metadata construct. 
get_construct 
Return a metadata construct. 
has_construct 
Whather a metadata construct exisits. 
set_construct 
Set a metadata construct. 
replace_construct 
Replace a metadata construct. 
del_data_axes 
Remove the keys of the domain axis constructs spanned by the data of the field or of a metadata construct. 
get_data_axes 
Return the keys of the domain axis constructs spanned by the data of a metadata construct. 
has_data_axes 
Whether the domain axis constructs spanned by the data of the field or of a metadata construct have been set. 
set_data_axes 
Set the domain axis constructs spanned by the data of the field or of a metadata construct. 
auxiliary_coordinate 
Return an auxiliary coordinate construct, or its key. 
cell_measure 
Select a cell measure construct by its identity. 
cell_method 
Select a cell method construct by its identity. 
coordinate 
Return a dimension coordinate construct, or its key. 
coordinate_reference 
Return a coordinate reference construct, or its key. 
dimension_coordinate 
Return a dimension coordinate construct, or its key. 
domain_ancillary 
Return a domain ancillary construct, or its key. 
domain_axis 
Return a domain axis construct, or its key. 
domain_axis_key 
Return the key of the domain axis construct that is spanned by 1d coordinate constructs. 
domain_axis_position 
Return the position in the data of a domain axis construct. 
field_ancillary 
Return a field ancillary construct, or its key. 
Attributes
constructs 
Return the metdata constructs. 
auxiliary_coordinates 
Return auxiliary coordinate constructs. 
cell_measures 
Return cell measure constructs. 
cell_methods 
Return cell method constructs. 
coordinates 
Return dimension and auxiliary coordinate constructs. 
coordinate_references 
Return coordinate reference constructs. 
dimension_coordinates 
Return dimension coordinate constructs. 
domain_ancillaries 
Return domain ancillary constructs. 
domain_axes 
Return domain axis constructs. 
axes 
Return domain axis constructs. 
field_ancillaries 
Return field ancillary constructs. 
Miscellaneous¶
Methods
copy 
Return a deep copy of the field construct. 
equals 
Whether two instances are the same. 
convert 
Convert a metadata construct into a new field construct. 
creation_commands 
Return the commands that would create the field construct. 
radius 
Return the radius used for calculating cell areas in spherical polar coordinates. 
cf.Field.concatenate 
Join a sequence of fields together. 
cf.Field.example_field 
Return an example field construct. 
Attributes
Flags 
A Flags object containing selfdescribing CF flag values. 
has_bounds 
Whether or not 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 
True if and only if the data are coordinates for a CF ‘T’ axis. 
X 
Always False. 
Y 
Always False. 
Z 
Always False. 
NetCDF¶
Methods
nc_del_variable 
Remove the netCDF variable name. 
nc_get_variable 
Return the netCDF variable name. 
nc_has_variable 
Whether the netCDF variable name has been set. 
nc_set_variable 
Set the netCDF variable name. 
nc_global_attributes 
Return the selection of properties to be written as netCDF global attributes. 
nc_clear_global_attributes 
Remove the selection of properties to be written as netCDF global attributes. 
nc_set_global_attribute 
Select a property to be written as a netCDF global attribute. 
dataset_compliance 
A report of problems encountered whilst reading the field construct from a dataset. 
Domain axes¶
autocyclic 
Set dimensions to be cyclic. 
axes 
Return domain axis constructs. 
cf.Field.axes_sizes 

axis 
Alias of cf.Field.domain_axis . 
axis_name 
Return the canonical name for an axis. 
axis_size 
Return the size of a domain axis construct. 
cyclic 
Set the cyclicity of an axis. 
data_axes 
Return the domain axes for the data array dimensions. 
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. 
Subspacing¶
__getitem__ 
Return a subspace of the field construct defined by indices. 
subspace 
Create a subspace of the field construct. 
indices 
Create indices that define a subspace of the field construct. 
Mathematical operations¶
Trigonometrical functions
cos 
Take the trigonometric cosine of the data, elementwise. 
sin 
The trigonometric sine of the data, elementwise. 
tan 
The trigonometric tangent of the data, elementwise. 
Rounding and truncation
ceil 
The ceiling of the data, elementwise. 
clip 
Limit the values in the data. 
floor 
Floor the data array, elementwise. 
rint 
Round the data to the nearest integer, elementwise. 
round 
Round the data to the given number of decimals. 
trunc 
Truncate the data, elementwise. 
Statistical collapses
collapse 
Collapse axes of the field. 
cell_area 
Return a field containing horizontal cell areas. 
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. 
Exponential and logarithmic functions
exp 
The exponential of the data, elementwise. 
log 
The logarithm of the data array. 
Derivatives
derivative 
Return the derivative along the specified axis. 
Convolution filters
convolution_filter 
Return the field convolved along the given axis with the specified filter. 
Cumulative sums
cumsum 
Return the field cumulatively summed along the given axis. 
Binning operations
bin 
Collapse the data values that lie in Ndimensional bins. 
digitize 
Return the indices of the bins to which each value belongs. 
percentile 
Compute percentiles of the data along the specified axes. 
Data array operations¶
Adding and removing elements
unique 
The unique elements of the data. 
Miscellaneous data array operations
chunk 
Partition the data array. 
isscalar 
True if the data array is scalar. 
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. 
datetime_array 
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 elements evaluate to True. 
any 
Test whether any data elements evaluate to True. 
Comparison
allclose 
Test whether all data are elementwise equal to other, broadcastable data. 
equals 
Whether two instances are the same. 
equivalent 
True if two fields are equivalent, False otherwise. 
cf.Field.equivalent_data 

cf.Field.equivalent_domain 
Set operations
unique 
The unique elements of the data. 
Aliases¶
Methods
aux 
Alias for cf.Field.auxiliary_coordinate . 
auxs 
Alias for cf.Field.auxiliary_coordinates . 
axis 
Alias of cf.Field.domain_axis . 
coord 
Alias for cf.Field.coordinate . 
coords 
Alias for cf.Field.coordinates . 
dim 
Alias for cf.Field.dimension_coordinate . 
dims 
Alias for cf.Field.dimension_coordinates . 
domain_anc 
Alias for cf.Field.domain_ancillary . 
domain_ancs 
Alias for cf.Field.domain_ancillaries . 
field_anc 
Alias for cf.Field.field_ancillary . 
field_ancs 
Alias for cf.Field.field_ancillaries . 
item 
Alias for cf.Field.construct` . 
items 
Alias for c.Field.constructs.filter_by_data . 
key 
Alias for cf.Field.construct_key . 
match 
Alias for match_by_identity . 
measure 
Alias for cf.Field.cell_measure . 
measures 
Alias for cf.Field.cell_measures . 
ref 
Alias for cf.Field.coordinate_reference . 
refs 
Alias for cf.Field.coordinate_references . 
Attributes
dtarray 
Alias for datetime_array . 
Arithmetic and comparison operations¶
Arithmetic, bitwise and comparison operations are defined on a field construct as elementwise operations on its data which yield a new field construct or, for augmented assignments, modify the field construct’s data inplace.
Relational 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 function. 
__getitem__ 
Return a subspace of the field construct defined by indices. 
__repr__ 
Called by the repr builtin function. 
__str__ 
Called by the str builtin function. 