Creating cf.Field objects

A new field may be created by initializing a new cf.Field instance. Data and metadata are provided with the following keyword parameters, all of which are optional:

Keyword Description
ancillary_variables Provide the new field with ancillary variable fields in a cf.AncillaryVariables object
attributes Provide the new field with attributes in a dictionary
data Provide the new field with a data array in a cf.Data object
dimensions Provide the new field with a data array dimensions
domain Provide the new field with a coordinate system in a cf.Domain object
flags Provide the new field with self-describing flag values in a cf.Flags object
properties Provide the new field with CF properties in a dictionary

Domain creation

Creating a domain possibly comprises the largest part of field creation, because the domain itself is composed of many interrelated items (dimension and auxiliary coordinate, cell measure and coordinate reference objects). It is not, however, difficult and is essentially a methodical assembly of components. Domain initialization is fully described in the documention of the cf.Domain object.

Each component of the field’s domain has an internal identifier (unique strings such as 'dim1', 'aux0', 'msr2' and 'ref0'), but for many field initializations, there is no need to provide, nor have any knowledge of these. However, they are easy to set if required (which may be the case if, for example, two multidimensional auxiliary coordinates span the same dimensions but in different orders) or if desired for clarity.

Inserting and removing components

Inserting field components after initialization is done with the following methods:

cf.Field.insert_aux Insert an auxiliary coordinate object into the domain in place.
cf.Field.insert_axis Insert an axis into the domain in place.
cf.Field.insert_data Insert a new data array into the field in place.
cf.Field.insert_dim Insert a dimension coordinate object into the domain in place.
cf.Field.insert_measure Insert an cell measure object into the domain in place.
cf.Field.insert_ref Insert a coordinate reference object into the domain in place.

For example:

>>> coord
<CF DimensionCoordinate: time(12) days since 2003-12-1>
>>> f.domain.insert_dim(coord)

Note that inserting domain items during field initialization is likely to be faster than using the insertion methods afterwards.

Removing field components is done with the following methods:

cf.Field.remove_axis Remove and return a unique axis from the field.
cf.Field.remove_axes Remove and return axes from the field.
cf.Field.remove_data Remove and return the data array.
cf.Field.remove_item Remove and return a domain item from the field.
cf.Field.remove_items Remove and return domain items from the domain.

For example:

>>> f.domain.remove_item('forecast_reference_time')

Examples

To improve readability, it is recommended that the construction of a field is done by first creating the components separately (data, coordinates, properties, etc.), and then combining them to make the field (as in example 3 and example 4), although this may not be necessary for very simple fields (as in example 1 and example 2).

Example 1

An empty field:

>>> f = cf.Field()
>>> print f
 field summary
--------------

Example 2

A field with just CF properties:

>>> f = cf.Field(properties={'standard_name': 'air_temperature',
...                          'long_name': 'temperature of air'})
...
>>> print f
air_temperature field summary
-----------------------------

Example 3

A field with a simple domain. Note that in this example the data and coordinates are generated using range and numpy.arange simply for the sake of having some numbers to play with. In practice it is likely the values would have been read from a file in some arbitrary format:

>>> import numpy
>>> data = cf.Data(numpy.arange(90.).reshape(10, 9), 'm s-1')
>>> properties = {'standard_name': 'eastward_wind'}
>>> dim0 = cf.DimensionCoordinate(data=cf.Data(range(10), 'degrees_north'),
...                               properties={'standard_name': 'latitude'})
...
>>> dim1 = cf.DimensionCoordinate(data=cf.Data(range(9), 'degrees_east'))
>>> dim1.standard_name = 'longitude'
>>> domain = cf.Domain(dim=[dim0, dim1])
>>> f = cf.Field(properties=properties, data=data, domain=domain)
>>> print f
eastward_wind field summary
---------------------------
Data            : eastward_wind(latitude(10), longitude(9)) m s-1
Dimensions      : latitude(10) = [0, ..., 9] degrees_north
                : longitude(9) = [0, ..., 8] degrees_east

Note that the default dimension order of ['dim0', 'dim1'] is applicable to the field’s data array.

Adding an auxiliary coordinate to the “latitude” axis and a cell method may be done with the relevant method and by simple assignment respectively (note that these coordinate values are just for illustration):

>>> aux = cf.AuxiliaryCoordinate(data=cf.Data(['alpha','beta','gamma','delta','epsilon',
...                                             'zeta','eta','theta','iota','kappa']))
...
>>> aux.long_name = 'extra'
>>> print f.items()
{'dim0': <CF DimensionCoordinate: latitude(10) degrees_north>,
 'dim1': <CF DimensionCoordinate: longitude(9) degrees_east>}
>>> f.insert_aux(aux, axes=['dim0'])
'aux0'
>>> f.cell_methods = cf.CellMethods('latitude: point')
>>> f.long_name = 'wind'
>>> print f
eastward_wind field summary
---------------------------
Data            : eastward_wind(latitude(10), longitude(9)) m s-1
Cell methods    : latitude: point
Dimensions      : latitude(10) = [0, ..., 9] degrees_north
                : longitude(9) = [0, ..., 8] degrees_east
Auxiliary coords: long_name:extra(latitude(10)) = ['alpha', ..., 'kappa']

Removing the auxiliary coordinate and the cell method that were just added is also done with the relevant method and by simple deletion respectively:

>>> f.remove_item({'long_name': 'extra'})
<CF AuxiliaryCoordinate: long_name:extra(10)>
>>> del f.cell_methods
>>> print f
eastward_wind field summary
---------------------------
Data            : eastward_wind(latitude(10), longitude(9)) m s-1
Dimensions      : latitude(10) = [0, ..., 9] degrees_north
                : longitude(9) = [0, ..., 8] degrees_east

Example 4

A more complicated field is created by the following script. Note that in this example the data and coordinates are generated using numpy.arange simply for the sake of having some numbers to play with. In practice it is likely the values would have been read from a file in some arbitrary format:

import cf
import numpy

#---------------------------------------------------------------------
# 1. CREATE the field's domain items
#---------------------------------------------------------------------
# Create a grid_latitude dimension coordinate
Y = cf.DimensionCoordinate(properties={'standard_name': 'grid_latitude'},
                              data=cf.Data(numpy.arange(10.), 'degrees'))

# Create a grid_longitude dimension coordinate
X = cf.DimensionCoordinate(data=cf.Data(numpy.arange(9.), 'degrees'))
X.standard_name = 'grid_longitude'

# Create a time dimension coordinate (with bounds)
bounds = cf.CoordinateBounds(
    data=cf.Data([0.5, 1.5], cf.Units('days since 2000-1-1', calendar='noleap')))
T = cf.DimensionCoordinate(properties=dict(standard_name='time'),
                           data=cf.Data(1, cf.Units('days since 2000-1-1',
                                                    calendar='noleap')),
                           bounds=bounds)

# Create a longitude auxiliary coordinate
lat = cf.AuxiliaryCoordinate(data=cf.Data(numpy.arange(90).reshape(10, 9),
                                          'degrees_north'))
lat.standard_name = 'latitude'

# Create a latitude auxiliary coordinate
lon = cf.AuxiliaryCoordinate(properties=dict(standard_name='longitude'),
                             data=cf.Data(numpy.arange(1, 91).reshape(9, 10),
                                          'degrees_east'))

# Create a rotated_latitude_longitude grid mapping coordinate reference
grid_mapping = cf.CoordinateReference('rotated_latitude_longitude',
                                      grid_north_pole_latitude=38.0,
                                      grid_north_pole_longitude=190.0)

# --------------------------------------------------------------------
# 2. Create the field's domain from the previously created items
# --------------------------------------------------------------------
domain = cf.Domain(dim=[T, Y, X],
                   aux=[lat, lon],
                   ref=grid_mapping)

#---------------------------------------------------------------------
# 3. Create the field
#---------------------------------------------------------------------
# Create CF properties
properties = {'standard_name': 'eastward_wind',
              'long_name'    : 'East Wind',
              'cell_methods' : cf.CellMethods('latitude: point')}

# Create the field's data array
data = cf.Data(numpy.arange(90.).reshape(9, 10), 'm s-1')

# Finally, create the field
f = cf.Field(properties=properties,
             domain=domain,
             data=data)

print "The new field:\n"
print f

Running this script produces the following output:

The new field:

eastward_wind field summary
---------------------------
Data           : eastward_wind(grid_longitude(9), grid_latitude(10)) m s-1
Cell methods   : latitude: point
Axes           : time(1) = [2000-01-02 00:00:00] noleap
               : grid_longitude(9) = [0.0, ..., 8.0] degrees
               : grid_latitude(10) = [0.0, ..., 9.0] degrees
Aux coords     : latitude(grid_latitude(10), grid_longitude(9)) = [[0, ..., 89]] degrees_north
               : longitude(grid_longitude(9), grid_latitude(10)) = [[1, ..., 90]] degrees_east
Coord refs     : <CF CoordinateReference: rotated_latitude_longitude>

Example 5

Example 4 would be slightly more complicated if the grid_longitude and grid_latitude axes were to have the same size. In this case the domain needs be told which axes, and in which order, are spanned by the two dimensional auxiliary coordinates (latitude and longitude) and the field needs to know which axes span the data array:

import cf
import numpy


#---------------------------------------------------------------------
# 1. CREATE the field's domain items
#---------------------------------------------------------------------
# Create a grid_latitude dimension coordinate
Y = cf.DimensionCoordinate(properties={'standard_name': 'grid_latitude'},
                              data=cf.Data(numpy.arange(10.), 'degrees'))

# Create a grid_longitude dimension coordinate
X = cf.DimensionCoordinate(data=cf.Data(numpy.arange(10.), 'degrees'))
X.standard_name = 'grid_longitude'

# Create a time dimension coordinate (with bounds)
bounds = cf.CoordinateBounds(
    data=cf.Data([0.5, 1.5], cf.Units('days since 2000-1-1', calendar='noleap')))
T = cf.DimensionCoordinate(properties=dict(standard_name='time'),
                           data=cf.Data(1, cf.Units('days since 2000-1-1',
                                                    calendar='noleap')),
                           bounds=bounds)

# Create a longitude auxiliary coordinate
lat = cf.AuxiliaryCoordinate(data=cf.Data(numpy.arange(100).reshape(10, 10),
                                          'degrees_north'))
lat.standard_name = 'latitude'

# Create a latitude auxiliary coordinate
lon = cf.AuxiliaryCoordinate(properties=dict(standard_name='longitude'),
                             data=cf.Data(numpy.arange(1, 101).reshape(10, 10),
                                          'degrees_east'))

# Create a rotated_latitude_longitude grid mapping coordinate reference
grid_mapping = cf.CoordinateReference('rotated_latitude_longitude',
                                      grid_north_pole_latitude=38.0,
                                      grid_north_pole_longitude=190.0)

# --------------------------------------------------------------------
# 2. Create the field's domain from the previously created items
# --------------------------------------------------------------------
domain = cf.Domain(dim=[T, Y, X],
                   aux={'aux0': lat, 'aux1': lon},
                   ref=grid_mapping,
                   assign_axes={'aux0': ['grid_latitude', 'grid_longitude'],
                                'aux1': ['grid_longitude', 'grid_latitude']})

#---------------------------------------------------------------------
# 3. Create the field
#---------------------------------------------------------------------
# Create CF properties
properties = {'standard_name': 'eastward_wind',
              'long_name'    : 'East Wind',
              'cell_methods' : cf.CellMethods('latitude: point')}

# Create the field's data array
data = cf.Data(numpy.arange(90.).reshape(9, 10), 'm s-1')

# Finally, create the field
f = cf.Field(properties=properties,
             domain=domain,
             data=data,
             axes=['grid_latitude', 'grid_longitude'])

print "The new field:\n"
print f

Running this script produces the following output:

eastward_wind field summary
---------------------------
Data           : eastward_wind(grid_latitude(10), grid_longitude(10)) m s-1
Cell methods   : latitude: point
Axes           : time(1) = [2000-01-02 00:00:00] noleap
               : grid_longitude(10) = [0.0, ..., 9.0] degrees
               : grid_latitude(10) = [0.0, ..., 9.0] degrees
Aux coords     : latitude(grid_latitude(10), grid_longitude(10)) = [[0, ..., 99]] degrees_north
               : longitude(grid_longitude(10), grid_latitude(10)) = [[1, ..., 100]] degrees_east
Coord refs     : <CF CoordinateReference: rotated_latitude_longitude>