cf.Field¶
-
class
cf.
Field
(properties=None, source=None, copy=True, _use_data=True)[source]¶ Bases:
cf.mixin.fielddomain.FieldDomain
,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 CF-netCDF data variable with all of its metadata. All CF-netCDF 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 may be accessed with the
nc_set_variable
,nc_get_variable
,nc_del_variable
, andnc_has_variable
methods.The netCDF variable group structure may be accessed with the
nc_set_variable
,nc_get_variable
,nc_variable_groups
,nc_clear_variable_groups
, andnc_set_variable_groups
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.The netCDF group attributes may be accessed with the
nc_group_attributes
,nc_clear_group_attributes
,nc_set_group_attribute
, andnc_set_group_attributes
methods.The netCDF geometry variable name and group structure may be accessed with the
nc_set_geometry_variable
,nc_get_geometry_variable
,nc_geometry_variable_groups
,nc_clear_variable_groups
, andnc_set_geometry_variable_groups
methods.Some components exist within multiple constructs, but when written to a netCDF dataset the netCDF names associated with such components will be arbitrarily taken from one of them. The netCDF variable, dimension and sample dimension names and group structures for such components may be set or removed consistently across all such components with the
nc_del_component_variable
,nc_set_component_variable
,nc_set_component_variable_groups
,nc_clear_component_variable_groups
,nc_del_component_dimension
,nc_set_component_dimension
,nc_set_component_dimension_groups
,nc_clear_component_dimension_groups
,nc_del_component_sample_dimension
,nc_set_component_sample_dimension
,nc_set_component_sample_dimension_groups
,nc_clear_component_sample_dimension_groups
methods.CF-compliance issues for field constructs read from a netCDF dataset may be accessed with the
dataset_compliance
method.Initialisation
- 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
Convert source, which can be any type of object, to a
Field
instance.All other parameters, apart from copy, are ignored and their values are instead inferred from source by assuming that it has the
Field
API. Any parameters that can not be retrieved from source in this way are assumed to have their default value.Note that if
x
is also aField
instance thencf.Field(source=x)
is equivalent tox.copy()
.- copy:
bool
, optional If True (the default) then deep copy the input parameters prior to initialisation. By default the parameters are not deep copied.
- properties:
Inspection¶
Methods
A full description of the field construct. |
|
Return the canonical identity. |
|
Return all possible identities. |
|
Inspect the object for debugging. |
Attributes
Return a description of the construct type. |
|
An identity for the Field object. |
Selection¶
Methods
Whether or not the construct identity satisfies conditions. |
|
Whether or not the data has a given dimensionality. |
|
Whether or not the netCDF variable name satisfies conditions. |
|
Whether or not properties satisfy conditions. |
|
Whether or not the number of domain axis constructs satisfies conditions. |
|
Whether or not the construct has given units. |
|
Whether or not there are particular metadata constructs. |
Properties¶
Methods
Remove a property. |
|
Get a CF property. |
|
Whether a property has been set. |
|
Set a property. |
|
Return all properties. |
|
Remove all properties. |
|
Remove properties. |
|
Set properties. |
Attributes
The add_offset CF property. |
|
The calendar CF property. |
|
|
Return cell method constructs. |
The comment CF property. |
|
The Conventions CF property. |
|
True if the field contains a collection of discrete sampling geometries. |
|
The _FillValue CF property. |
|
The featureType CF property. |
|
The flag_masks CF property. |
|
The flag_meanings CF property. |
|
The flag_values CF property. |
|
The history CF property. |
|
The institution CF property. |
|
The leap_month CF property. |
|
The leap_year CF property. |
|
The long_name CF property. |
|
The missing_value CF property. |
|
The month_lengths CF property. |
|
The references CF property. |
|
The scale_factor CF property. |
|
The source CF property. |
|
The standard_error_multiplier CF property. |
|
The standard_name CF property. |
|
The title CF property. |
|
The units CF property. |
|
The valid_max CF property. |
|
The valid_min CF property. |
|
The valid_range CF property. |
Units¶
Override the units. |
|
Override the calendar of date-time units. |
The |
|
The reference date-time of units of elapsed time. |
Data¶
Methods
Remove the data. |
|
Return the data. |
|
Whether or not the construct has data. |
|
Set the field construct data. |
|
Removes the keys of the axes spanned by the construct data. |
|
Gets the keys of the axes spanned by the construct data. |
|
Whether the axes spanned by the construct data have been set. |
|
Sets the axes spanned by the construct data. |
Attributes
A numpy array deep copy of the data. |
|
The |
|
An independent numpy array of date-time objects. |
|
Return an element of the data array as a standard Python scalar. |
|
The |
|
The number of data dimensions. |
|
A tuple of the data array’s dimension sizes. |
|
The number elements in the data. |
|
Convert the data to a |
|
A numpy array view of the data array. |
Rearranging elements
Roll a cyclic axis so that the given value lies in the first coordinate cell. |
|
Flatten axes of the field. |
|
Flip (reverse the direction of) axes of the field. |
|
Insert a size 1 axis into the data array. |
|
Roll the field along a cyclic axis. |
|
Remove size 1 axes from the data. |
|
Interchange two axes of the data. |
|
Permute the axes of the data array. |
|
Insert size 1 axes into the data array. |
Expanding the data
Expand the field construct by adding a halo to its data. |
|
Pad an axis with missing data. |
Data array mask
Apply masking as defined by the CF conventions. |
|
Count the non-masked elements of the data. |
|
Count the masked elements of the data. |
|
Return the data array missing data value. |
|
Mask the array where invalid values occur (NaN or inf). |
A binary (0 and 1) missing data mask of the data array. |
|
Whether the mask is hard (True) or soft (False). |
|
The mask of the data array. |
Changing data values
Called to implement assignment to x[indices]=value. |
|
Create a subspace of the field construct. |
|
Create indices that define a subspace of the field construct. |
|
Assign to data elements depending on a condition. |
|
Apply masking as defined by the CF conventions. |
|
Mask the array where invalid values occur (NaN or inf). |
Searching and counting
Return the indices of the maximum values along an axis. |
|
Return the indices of the minimum values along an axis. |
|
Assign to data elements depending on a condition. |
Miscellaneous data operations¶
Methods
Get or set the cyclicity of an axis. |
|
Return or set the period of the data. |
|
The names of files containing the original data and metadata. |
|
Close all files referenced by the field construct. |
|
Change the chunk structure of the data. |
|
Persist the underlying dask array into memory. |
Metadata constructs¶
Methods
Return auxiliary coordinate constructs. |
|
Select an auxiliary coordinate construct. |
|
Select cell connectivity constructs. |
|
Select a cell connectivity construct. |
|
Return cell measure constructs. |
|
Select a cell measure construct. |
|
Return cell method constructs. |
|
Select a cell method construct. |
|
Return dimension and auxiliary coordinate constructs. |
|
Select a dimension or auxiliary coordinate construct. |
|
Return coordinate reference constructs. |
|
Return a coordinate reference construct, or its key. |
|
Return dimension coordinate constructs. |
|
Select a dimension coordinate construct. |
|
Return domain ancillary constructs. |
|
Select a domain ancillary construct. |
|
Return domain axis constructs. |
|
Select a domain axis construct. |
|
Return domain topology constructs. |
|
Select a domain topology construct. |
|
Return field ancillary constructs. |
|
Select a field ancillary construct. |
|
Return a metadata construct. |
|
Return a metadata construct and its identifier. |
|
Return the identifier of a metadata construct. |
|
Remove a metadata construct. |
|
Return a metadata construct. |
|
Whether a unique metadata construct exists. |
|
Set a metadata construct. |
|
Replace a metadata construct. |
|
Removes the keys of the axes spanned by the construct data. |
|
Gets the keys of the axes spanned by the construct data. |
|
Whether the axes spanned by the construct data have been set. |
|
Sets the axes spanned by the construct data. |
|
Move auxiliary coordinates to a dimension coordinate construct. |
|
Move dimension coordinates to an auxiliary coordinate construct. |
|
Return the domain axes that apply to a coordinate reference construct. |
|
Return a coordinate reference construct. |
|
Set a coordinate reference construct. |
|
Remove a coordinate reference construct and all of its domain ancillary constructs. |
|
Returns the domain axis key spanned by 1-d coordinates. |
|
Return the position in the data of a domain axis construct. |
|
Return a boolean field that is True where criteria are met. |
|
Remove a domain axis construct. |
|
Map the axis identifiers of the field to their equivalent axis identifiers of another. |
|
Return all axes which are climatological time axes. |
Attributes
Return the metadata constructs. |
Domain¶
Methods
Return the domain. |
Attributes
Return the domain. |
Miscellaneous¶
Methods
Return a deep copy. |
|
Compute non-parametric vertical coordinates. |
|
Return the dataset compliance report. |
|
Whether two instances are the same. |
|
Compress the field construct. |
|
Convert a metadata construct into a new field construct. |
|
Return the commands that would create the field construct. |
|
Return the radius of a latitude-longitude plane defined in spherical polar coordinates. |
|
Bring data on disk into memory. |
|
Uncompress the field construct. |
|
Join a sequence of fields together. |
|
Return a FieldList of m dimensional sections of a Field of n dimensions, where M <= N. |
Attributes
A |
|
Whether or not there are cell bounds. |
|
Return whether or not any coordinates have cell geometries. |
|
The number of axes in the domain. |
|
|
|
Always False. |
|
Always False. |
|
Always False. |
NetCDF¶
Methods
Remove the netCDF variable name. |
|
Return the netCDF variable name. |
|
Whether the netCDF variable name has been set. |
|
Set the netCDF variable name. |
|
Returns properties to write as netCDF global attributes. |
|
Removes properties to write as netCDF global attributes. |
|
Select a property to be written as a netCDF global attribute. |
|
Set properties to be written as netCDF global attributes. |
|
|
Groups¶
Methods
Return the netCDF variable group hierarchy. |
|
Set the netCDF variable group hierarchy. |
|
Remove the netCDF variable group hierarchy. |
|
Returns properties to write as netCDF group attributes. |
|
Removes properties to write as netCDF group attributes. |
|
Select a property to be written as a netCDF group attribute. |
|
Set properties to be written as netCDF group attributes. |
CFA¶
Methods
The locations of files containing parts of the data. |
|
Add a new file location in-place. |
|
Remove a file location in-place. |
|
Remove all of the CFA-netCDF file name substitutions. |
|
Remove a CFA-netCDF file name substitution. |
|
Return the CFA-netCDF file name substitutions. |
|
Set CFA-netCDF file name substitutions. |
Geometries¶
Methods
Remove the netCDF geometry container variable name. |
|
Return the netCDF geometry container variable name. |
|
Whether a netCDF geometry container variable has a name. |
|
Set the netCDF geometry container variable name. |
|
Return the netCDF geometry variable group hierarchy. |
|
Set the netCDF geometry variable group hierarchy. |
|
Remove the netCDF geometry variable group hierarchy. |
Components¶
Methods
Remove the netCDF variable name of components. |
|
Set the netCDF variable name for components. |
|
Set the netCDF variable groups of components. |
|
Remove the netCDF variable groups of components. |
|
Remove the netCDF dimension name of components. |
|
Set the netCDF dimension name of components. |
|
Set the netCDF dimension groups of components. |
|
Remove the netCDF dimension groups of components. |
|
Remove the netCDF sample dimension name of components. |
|
Set the netCDF sample dimension name of components. |
|
Set the netCDF sample dimension groups of components. |
|
Remove the netCDF sample dimension groups of components. |
Domain axes¶
Select a domain axis construct. |
|
Return domain axis constructs. |
|
Analyse a domain. |
|
Set dimensions to be cyclic. |
|
Alias for |
|
Return canonical identities for each domain axis construct. |
|
|
|
Alias for |
|
Return the canonical name for an axis. |
|
Return the size of a domain axis construct. |
|
Get or set the cyclicity of an axis. |
|
Return the domain axes for the data array dimensions. |
|
Whether or not a domain axis is increasing. |
|
Return a dictionary mapping all domain axes to their directions. |
|
Returns True if the specified axis is cyclic. |
|
True if a given axis is periodic. |
|
Return the axes of a domain item of the field. |
|
Return the axes of items of the field. |
Subspacing¶
Return a subspace of the field construct defined by indices. |
|
Create indices that define a subspace of the field construct. |
Create a subspace of the field construct. |
Mathematical operations¶
Trigonometrical and hyperbolic functions
Take the trigonometric inverse cosine of the data element- wise. |
|
Take the inverse hyperbolic cosine of the data element-wise. |
|
Take the trigonometric inverse sine of the data element-wise. |
|
Take the inverse hyperbolic sine of the data element-wise. |
|
Take the trigonometric inverse tangent of the data element- wise. |
|
Take the inverse hyperbolic tangent of the data element-wise. |
|
Take the trigonometric cosine of the data element-wise. |
|
Take the hyperbolic cosine of the data element-wise. |
|
Take the trigonometric sine of the data element-wise. |
|
Take the hyperbolic sine of the data element-wise. |
|
Take the trigonometric tangent of the data element-wise. |
|
Take the hyperbolic tangent of the data array. |
Rounding and truncation
The ceiling of the data, element-wise. |
|
Limit the values in the data. |
|
Floor the data array, element-wise. |
|
Round the data to the nearest integer, element-wise. |
|
Round the data to the given number of decimals. |
|
Truncate the data, element-wise. |
Statistical collapses
Collapse axes of the field. |
|
Perform moving window calculations along an axis. |
|
Return the horizontal cell areas. |
|
Alias for |
|
The unweighted mean the data array. |
|
The unweighted average of the maximum and minimum of the data array. |
|
Alias for |
|
The absolute difference between the maximum and minimum of the data array. |
|
The number of non-missing data elements in the data array. |
|
The sum of the data array. |
|
Alias for |
|
Alias for |
|
Return weights for the data array values. |
|
The unweighted sample standard deviation of the data array. |
|
The unweighted sample variance of the data array. |
|
The maximum of the data array. |
|
The minimum of the data array. |
Exponential and logarithmic functions
The exponential of the data, element-wise. |
|
The logarithm of the data array. |
Differential operators
Calculate the derivative along the specified axis. |
|
Calculate the (X, Y) gradient vector. |
|
Calculate the Laplacian in X-Y coordinates. |
Convolution filters
Convolve the field construct along the given axis with the specified filter. |
|
Perform moving window calculations along an axis. |
Cumulative sums
Return the field cumulatively summed along the given axis. |
Binning operations
Collapse the data values that lie in N-dimensional bins. |
|
Return the indices of the bins to which each value belongs. |
|
Return a multi-dimensional histogram of the data. |
|
Compute percentiles of the data along the specified axes. |
Data array operations¶
Adding and removing elements
The unique elements of the data. |
Miscellaneous data array operations
True if the data array is scalar. |
Regridding operations¶
Regrid the field to a new Cartesian grid. |
|
Regrid the field to a new latitude and longitude grid. |
Date-time operations¶
The day of each date-time data array element. |
|
An independent numpy array of date-time objects. |
|
The hour of each date-time data array element. |
|
The minute of each date-time data array element. |
|
The month of each date-time data array element. |
|
The second of each date-time data array element. |
|
The year of each date-time data array element. |
Convert reference time data values to have new units. |
Logic functions¶
Truth value testing
Test whether all data elements evaluate to True. |
|
Test whether any data elements evaluate to True. |
Comparison
Test whether all data are element-wise equal to other, broadcastable data. |
|
Whether two instances are the same. |
|
True if two fields are equivalent, False otherwise. |
|
|
|
|
Set operations
The unique elements of the data. |
Aliases¶
Methods
Alias for |
|
Alias for |
|
Alias for |
|
Alias for |
|
Alias for |
|
Alias for |
|
Alias for |
|
Alias for |
|
Alias for |
|
Alias for |
|
Alias for |
|
Return a domain item of the field. |
|
Return domain items as (construct key, construct) pairs. |
|
Alias for |
|
Alias for |
|
Alias for |
|
Alias for |
|
Alias for |
|
Alias for |
Attributes
Alias for |
Arithmetic and comparison operations¶
Arithmetic, bitwise and comparison operations are defined on a field construct as element-wise operations on its data which yield a new field construct or, for augmented assignments, modify the field construct’s data in-place.
Relational operators
The rich comparison operator |
|
The rich comparison operator |
|
The rich comparison operator |
|
The rich comparison operator |
|
The rich comparison operator |
|
The rich comparison operator |
Binary arithmetic operators
The binary arithmetic operation |
|
The binary arithmetic operation |
|
The binary arithmetic operation |
|
The binary arithmetic operation |
|
The binary arithmetic operation |
|
The binary arithmetic operation |
|
The binary arithmetic operations |
|
The binary arithmetic operation |
Binary arithmetic operators with reflected (swapped) operands
The binary arithmetic operation |
|
The binary arithmetic operation |
|
The binary arithmetic operation |
|
The binary arithmetic operation |
|
The binary arithmetic operation |
|
The binary arithmetic operation |
|
The binary arithmetic operations |
|
The binary arithmetic operation |
Augmented arithmetic assignments
The augmented arithmetic assignment |
|
The augmented arithmetic assignment |
|
The augmented arithmetic assignment |
|
The augmented arithmetic assignment |
|
The augmented arithmetic assignment |
|
The augmented arithmetic assignment |
|
The augmented arithmetic assignment |
|
The binary arithmetic operation |
Unary arithmetic operators
The unary arithmetic operation |
|
The unary arithmetic operation |
|
The unary arithmetic operation |
Binary bitwise operators
The binary bitwise operation |
|
The binary bitwise operation |
|
The binary bitwise operation |
|
The binary bitwise operation |
|
The binary bitwise operation |
Binary bitwise operators with reflected (swapped) operands
The binary bitwise operation |
|
The binary bitwise operation |
|
The binary bitwise operation |
|
The binary bitwise operation |
|
The binary bitwise operation |
Augmented bitwise assignments
The augmented bitwise assignment |
|
The augmented bitwise assignment |
|
The augmented bitwise assignment |
|
The augmented bitwise assignment |
|
The augmented bitwise assignment |
Unary bitwise operators
The unary bitwise operation |
Groups¶
Methods
Return the netCDF variable group hierarchy. |
|
Set the netCDF variable group hierarchy. |
|
Remove the netCDF variable group hierarchy. |
|
Returns properties to write as netCDF group attributes. |
|
Select a property to be written as a netCDF group attribute. |
|
Set properties to be written as netCDF group attributes. |
|
Removes properties to write as netCDF group attributes. |
|
Return the netCDF geometry variable group hierarchy. |
|
Set the netCDF geometry variable group hierarchy. |
|
Remove the netCDF geometry variable group hierarchy. |
Special¶
Methods
Called by the |
|
Return a subspace of the field construct defined by indices. |
|
Called by the |
|
Called by the |
|
Returns a numpy array representation of the data. |
|
Returns a new reference to the data. |
|
Query interface method for an “is close” condition. |
Deprecated¶
Methods
Deprecated at version 3.0.0. |
|
Deprecated at version 3.0.0. |
|
Return the canonical name for an axis. |
|
Partition the data array. |
|
Return the domain axes for the data array dimensions. |
|
Deprecated at version 3.0.0, use method |
|
True if two fields are equivalent, False otherwise. |
|
Return an example field construct. |
|
Insert a size 1 axis into the data array. |
|
Create an independent field from a domain item. |
|
Return the names of the files containing the data. |
|
Deprecated at version 3.0.0, use method |
|
Deprecated at version 3.0.0. |
|
Deprecated at version 3.0.0, use method |
|
Insert an auxiliary coordinate object into the field. |
|
Insert a domain axis into the field. |
|
Insert one or more cell method objects into the field. |
|
Insert a data array into the field. |
|
Insert a domain ancillary object into the field. |
|
Insert a field ancillary object into the field. |
|
Insert an item into the field. |
|
Insert a cell measure object into the field. |
|
Insert a coordinate reference object into the field. |
|
Deprecated at version 3.7.0, use |
|
Deprecated at version 3.7.0, use |
|
Deprecated at version 3.7.0, use |
|
Deprecated at version 3.7.0, use |
|
Deprecated at version 3.7.0, use |
|
Return the axes of a domain item of the field. |
|
Return an item, or its identifier, from the field. |
|
Mask the array where invalid values occur. |
|
Deprecated at version 3.0.0, use method ‘identity’ instead. |
|
Return a new, unused construct key. |
|
Remove and return axes from the field. |
|
Remove and return a unique axis from the field. |
|
Remove and return the data array. |
|
Remove and return an item from the field. |
|
Remove and return items from the field. |
|
Deprecated at version 3.0.0. |
|
Deprecated at version 3.0.0, use method |
|
Permute the axes of a field item data array. |
|
Deprecated at version 3.0.0. |
Attributes
Deprecated at version 3.0.0. |
|
Return domain axis constructs. |
|
Return cell method constructs. |
|
Return cell method constructs. |
|
Deprecated at version 3.0.0, use |
|
Deprecated at version 3.0.0. |
|
Deprecated at version 3.0.0, use |
|
Deprecated at version 3.0.0, use |
|
Return domain items as (construct key, construct) pairs. |
|
Deprecated at version 3.0.0, use |