1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
|
.. currentmodule:: cf
.. default-role:: obj
Further examples
================
Reading files
-------------
The `cf.read` function will read `CF-netCDF
<http://cf-pcmdi.llnl.gov/documents/cf-conventions/1.6/cf-conventions.html>`_
and `CFA-netCDF <http://www.met.reading.ac.uk/~david/cfa/0.3/>`_ files
(or URLs if DAP access is enabled) and Met Office (UK) PP files and
fields files from disk and return their contents as a field or a
:ref:`field list <fs_field_list>`, i.e. an ordered collection of
fields stored in a `cf.FieldList` object:
>>> f = cf.read('data.nc')
>>> 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>
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 a field or field list to a
CF-netCDF or CFA-netCDF file on disk:
>>> 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 be included as data variable
properties in a CF compliant netCDF file (such as
`~Field.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 `~Field.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 `~Field.setprop`,
`~Field.getprop` and `~Field.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 `~cf.Field.match` and
`~cf.Field.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('air')
[False, True]
>>> g = f.select('air_temperature', items={'longitude': 0})
>>> g
[<CF Field: air_temperature(time(12), grid_latitude(73), grid_longitude(96)) K>]
The data array
--------------
The field's data array may be retrieved as an independent numpy array
with the field's `~Field.array` attribute:
>>> print f.array
[[ 2. 4.]
[ 5. 1.]]
A particular element of the data array may be retrieved with the
field's `~cf.Field.datum` method:
>>> f.datum(0)
2.0
>>> f.datum(-1)
1.0
>>> f.datum(0, 1)
4.0
Coordinates
-----------
A dimension or auxiliary coordinate object of the field's domain may
be returned by the field's `~cf.Field.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:
Creating a field
----------------
A new field may be created by initializing a new `cf.Field`
instance. See the section on :ref:`field creation <field_creation>`
for details.
|
