Further examples

Reading files

The cf.read function will read CF-netCDF and CFA-netCDF files (or URLs if DAP access is enabled) and Met Office (UK) PP format files from disk and return their contents as a field list, i.e. an ordered collection of fields stored in a cf.FieldList object:

>>> f = cf.read('data.nc')
>>> type(f)
<class 'cf.field.FieldList'>
>>> f
[<CF Field: air_pressure(grid_latitude(30), grid_longitude(24)) Pa>,
 <CF Field: x_wind(height(19), grid_latitude(29), grid_longitude(24)) m s-1>,
 <CF Field: y_wind(height(19), grid_latitude(29), grid_longitude(24)) m s-1>,
 <CF Field: air_potential_temperature(height(19), grid_latitude(30), grid_longitude(24)) K>]
>>> f[-1]
<CF Field: air_potential_temperature(height(19), grid_latitude(30), grid_longitude(24)) K>

The cf.read function always returns a field list as opposed to a field. If a single field as a cf.Field object is required, then the cf.read function (or rather its returned field list) may be indexed:

>>> f = cf.read('file1.nc')[0]

Multiple files may be read at once by using Unix shell wildcard characters in file names or providing a sequence of files:

>>> f = cf.read('~/file.nc')
>>> f = cf.read('file[1-9a-c].nc')
>>> f = cf.read('dir*/*.pp')
>>> f = cf.read(['file1.nc', 'file2.nc', 'file3*.nc'])

File names may use environment variables and ~ expansion:

>>> f = cf.read('~/*.nc')
>>> f = cf.read('$DATA/*.nc')
>>> f = cf.read('$DATA/${MORE_DATA}/*.nc')
>>> f = cf.read('~/$DATA/${MORE_DATA}/*.nc')

For each file, the file format is inferred from the file contents, not from the file name suffix.

Writing files

The cf.write function will write fields to a CF-netCDF or CFA-netCDF file on disk:

>>> type(g)
<class 'cf.field.Field'>
>>> cf.write(g, 'newfile.nc')
>>> type(f)
<class 'cf.field.FieldList'>
>>> cf.write(f, 'newfile.nc')

A sequence of fields and field lists may be written to the same file:

>>> cf.write([f, g], 'newfile.nc')

All of the input fields are written to the same output file, but if metadata (such as coordinates) are identical in two or more fields then that metadata is only written once to the output file.

Output file names are arbitrary (in particular, they do not require a suffix).

CF properties and attributes

The field’s CF properties are those which are intended to be essential metadata for the data array and would, for example, be included as properties in a CF compliant file (such as standard_name). The field’s attributes are any other attributes, such as the names of the files containing the data array values.

The CF properties are returned by the field’s properties attribute:

>>> f.properties
{'_FillValue': 1e+20,
 'cell_methods': <CF CellMethods: time: mean>,
 'standard_name': 'air_temperature',
 'units': 'K'}

A CF property recognised by the CF conventions or an attribute may be set, retrieved and deleted as standard python object attributes:

>>> f.standard_name = 'air_temperature'
>>> f.standard_name
'air_temperature'
>>> del f.standard_name
>>> getattr(f, 'standard_name')
AttributeError: Field doesn't have CF property 'long_name'
>>> getattr(f, 'standard_name', 'air_pressure')
'air_pressure'
>>> setattr(f, 'standard_name', 'air_pressure')

>>> f.ncvar = 'tas'
>>> getattr(f, 'ncvar')
'tas'
>>> del f.ncvar

Any CF property (recognised by the CF conventions or not) may be set, retrieved and deleted with the field’s setprop, getprop and delprop methods:

>>> f.properties
{}
>>> f.setprop('long_name', 'temperature at 1.5m')
>>> f.getprop('long_name')
'temperature at 1.5m'
>>> f.delprop('long_name')
>>> f.getprop('long_name')
AttributeError: Field doesn't have CF property 'long_name'
>>> f.getprop('long_name', 'pressure')
'pressure'
>>> f.setprop('long_name', 'pressure')
>>> f.setprop('foo', 'bar')
>>> f.properties
{'foo': 'bar',
'long_name': 'pressure'}}

Selecting fields

Fields may be selected with the match and select methods. These methods take conditions on field CF properties, attributes and coordinates as inputs:

>>> f
[<CF Field: x_wind(grid_latitude(110), grid_longitude(106)) m s-1>,
 <CF Field: air_temperature(time(12), grid_latitude(73), grid_longitude(96)) K>]

>>> f.match('temperature', regex=True)
[False, True]
>>> g = f.select('air_temperature, cvalue={'longitude': 0})>>> 
g
[<CF Field: air_temperature(time(12), grid_latitude(73), grid_longitude(96)) K>]

The data array

The fields data array may be retrieved as an independent numpy array with the field’s array attribute:

>>> print f.array
[[ 2.  4.]
 [ 5.  1.]]

The first and last elements of the data array may be retrieved with the field’s datum method:

>>> f.datum(0)
2.0
>>> f.datum(-1)
1.0

Coordinates

A dimension or auxiliary coordinate object of the field’s domain may be returned by the field’s coord method. A coordinate object has the same CF property and data access principles as a field:

>>> c = f.coord('time')
>>> c
<CF DimensionCoordinate: time(12)>
>>> c.properties
{'_FillValue': None,
 'axis': 'T',
 'bounds': <CF CoordinateBounds: time_bnds(12, 2)>,
 'calendar': 'noleap',
 'long_name': 'time',
 'standard_name': 'time',
 'units': 'days since 0000-1-1'}
>>> c.Units
<CF Units: days since 0000-1-1 calendar=noleap>
>>> print c.array
[  0  30  60  90 120 150 180 210 240 270 300 330]

Creating a field

A new field may be created by initializing a new cf.Field instance. See the section on field creation for details.