# 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 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 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.