Field creation

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

For many field initializations, there is no need to provide, nor have any knowledge of, internal identifiers for dimensions, coordinates, cell measures and transforms. These internal identifiers are unique strings such as 'dim1', 'aux0', 'cm2' and 'trans0'. 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.

Domain creation

Creating a domain possibly comprises the largest part of field creation, because the domain itself is composed of many interrelated items (dimensions, coordinates, cell measures and transforms). It is not, however, difficult and is essentially a methodical assembly of components. Domain initialization is described, with examples, in the documention of the cf.Domain object.

Inserting and removing components

To ensure internal consistency, it is recommended that as much as possible of the field is created during an initialization of a cf.Field instance. Inserting field and domain components after initialization is not problematic, however, provided the appropriate methods are used:

cf.Domain.insert_aux_coordinate	Insert a new auxiliary coordinate into the domain in place, preserving internal consistency.
cf.Domain.insert_cell_measure	Insert a new cell measure into the domain in place, preserving internal consistency.
cf.Domain.insert_dim_coordinate	Insert a new dimension coordinate to the domain in place, preserving internal consistency.
cf.Domain.insert_dimension	Insert a new dimension to the domain in place, preserving internal consistency.
cf.Domain.insert_transform	Insert a new transform into the domain in place, preserving internal consistency.
cf.Field.insert_data	Insert a new data array into the field in place, preserving internal consistency.

There are also methods to remove components from a field which preserve internal consistency:

cf.Domain.remove_cell_measure	Remove a cell measure from the domain in place, preserving internal consistency.
cf.Domain.remove_coordinate	Remove a coordinate from the domain in place, preserving internal consistency.
cf.Domain.remove_dimension	Remove a dimension from the domain in place, preserving internal consistency.
cf.Domain.remove_transform	Remove a transform from the domain in place, preserving internal consistency.
cf.Field.remove_data	Remove the fields’s data array in-place, preserving internal consistency.

Examples

To improve readability, it is generally 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.Coordinate(data=cf.Data(range(10), 'degrees_north'),
...                      properties={'standard_name': 'latitude'})
...
>>> dim1 = cf.Coordinate(data=cf.Data(range(9), 'degrees_east'))
>>> dim1.standard_name = 'longitude'
>>> domain = cf.Domain(dims=[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 a string-valued auxiliary coordinate and a cell method to the previously created field may be done with the relevent method and by simple assignment respectively (note that these coordinate values are just for illustration):

>>> aux0 = cf.Coordinate(data=cf.Data(['alpha','beta','gamma','delta','epsilon',
...                                    'zeta','eta','theta','iota','kappa']))
...
>>> aux0.long_name = 'extra'
>>> f.domain.insert_aux_coordinate(aux0, dimensions=['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 relevent method and by simple deletion respectively:

>>> f.domain.remove_coordinate('aux0')
>>> 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
#---------------------------------------------------------------
# Create a grid_latitude dimension coordinate
dim0 = cf.Coordinate(properties={'standard_name': 'grid_latitude'},
                     data=cf.Data(numpy.arange(10.), 'degrees'))

# Create a grid_longitude dimension coordinate
dim1 = cf.Coordinate(data=cf.Data(numpy.arange(9.), 'degrees'))
dim1.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')))
dim2 = cf.Coordinate(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
aux0 = cf.Coordinate(data=cf.Data(numpy.arange(90).reshape(10, 9), 'degrees_north'))
aux0.standard_name = 'latitude'

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

# Create a rotated_latitude_longitude grid mapping transform
trans0 = cf.Transform(grid_mapping_name='rotated_latitude_longitude',
                      grid_north_pole_latitude=38.0,
                      grid_north_pole_longitude=190.0)

# Create the field's domain from the previously created components
domain = cf.Domain(dims=[dim0, dim1, dim2],
                   aux0=aux0, aux1=aux1,
                   trans0=trans0,
                   dimensions={'aux1': ['dim1', 'dim0']},
                   transform_map={'trans0': ['dim0', 'dim1']})

#---------------------------------------------------------------
# 2. 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,
             dimensions=['dim1', 'dim0'])

print "The new field:\n"
print f

Note that the default dimension order is not applicable to the aux1 auxiliary coordinate nor field’s data array, but does apply to the aux0 auxiliary coordinate.

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
Dimensions      : grid_latitude(10) = [0, ..., 9] degrees
                : grid_longitude(9) = [0, ..., 8] degrees
                : time(1) = [1] days since 2000-1-1
Auxiliary coords: latitude(grid_latitude(10), grid_longitude(9)) = [[0, ..., 89]] degrees_north
                : longitude(grid_longitude(9), grid_latitude(10)) = [[1, ..., 90]] degrees_east
Transforms      : <CF Transform: rotated_latitude_longitude>