File: a_first_example.rst.NEW

package info (click to toggle)
cf-python 1.3.2+dfsg1-4
  • links: PTS, VCS
  • area: main
  • in suites: sid, stretch
  • size: 7,996 kB
  • sloc: python: 51,733; ansic: 2,736; makefile: 78; sh: 2
file content (141 lines) | stat: -rw-r--r-- 3,695 bytes parent folder | download
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
.. currentmodule:: cf
.. default-role:: obj

A first example
===============

The cf package allows a data array and its associated metadata to be
contained and manipulated as a single entity called a *field*, which
is stored in a `cf.Field` object.

Much of the basic field manipulation syntax can be seen in this simple
read-modify-write example which:

    * Reads a field from a file on disk and find out information about
      it.

    * Modifies a CF property and the units of its data.

    * Modifies the data values.

    * Modifies a subspace of the data values.

    * Writes it out to another file on disk.

The example may be reproduced by downloading the :download:`sample
netCDF file (file.nc) <../file.nc>` (taking care not to overwrite an
existing file with that name) [#f1]_.

**1.** Import the cf package.

>>> import cf

**2.** Read a field from disk and find a summary of its contents.

>>> f = cf.read('file.nc')[0]
>>> type(f)
cf.field.Field
>>> f
<CF Field: air_temperature(latitude(4), longitude(5)) K>
>>> print f
air_temperature field summary
-----------------------------
Data           : air_temperature(latitude(4), longitude(5)) K
Cell methods   : time: mean
Axes           : time(1) = [2000-01-16 00:00:00] 360_day
               : height(1) = [2.0] m
               : latitude(4) = [-2.5, ..., 5.0] degrees_north
               : longitude(5) = [0.0, ..., 15.0] degrees_east

**3.** Find all of the field's CF properties and its data array as a
numpy array.

>>> f.properties
{'Conventions': 'CF-1.5',
 '_FillValue': 1e+20,
 'experiment_id': 'stabilization experiment (SRES A1B)',
 'long_name': 'Air Temperature',
 'standard_name': 'air_temperature',
 'title': 'SRES A1B'}
>>> print f.array
[[ 274.15,  276.15,  275.15,  277.15,  278.15],
 [ 274.15,  275.15,  276.15,  277.15,  276.15],
 [ 277.15,  275.15,  278.15,  274.15,  278.15],
 [ 276.15,  274.15,  275.15,  277.15,  274.15]]

**4.**. Modify the field's long name CF property and change the field's
data from units of Kelvin to Celsius.

.. note:: Changing the units automatically changes the data when it is
          next accessed.

>>> f.long_name
'Air Temperature'
>>> f.long_name = 'Surface Air Temperature'
>>> f.long_name
'Surface Air Temperature'
>>> print f.Units
K
>>> f.Units -= 273.15
>>> print f.Units       
K @ 273.15
>>> print f.array
[[ 1.  3.  2.  4.  5.]
 [ 1.  2.  3.  4.  3.]
 [ 4.  2.  5.  1.  5.]
 [ 3.  1.  2.  4.  1.]]

**5.** Check that the field has 'air_temperature' as its standard name
       and that at least one of its latitude coordinate values is
       greater than 0.0.

>>> f.match('air_temperature', items={'latitude' : cf.gt(0)})
True

**6.** Modify the data values.

>>> g = f + 100
>>> print g.array
[[ 101.  103.  102.  104.  105.]
 [ 101.  102.  103.  104.  103.]
 [ 104.  102.  105.  101.  105.]
 [ 103.  101.  102.  104.  101.]]
>>> g = f + f
>>> print g.array
[[  2.   6.   4.   8.  10.]
 [  2.   4.   6.   8.   6.]
 [  8.   4.  10.   2.  10.]
 [  6.   2.   4.   8.   2.]]
>>> g = f / cf.Data(2, 'seconds')
>>> print g.array
[[0.5 1.5 1.0 2.0 2.5]
 [0.5 1.0 1.5 2.0 1.5]
 [2.0 1.0 2.5 0.5 2.5]
 [1.5 0.5 1.0 2.0 0.5]]
>>> print g.Units
s-1.K

**7.** Access and modify a subspace of the data values.

>>> g = f.subspace[0::2, 2:4]
>>> print g.array
[[ 2.  4.]
 [ 5.  1.]]
>>> f.subspace[0::2, ...] = -10
>>> print f.array
[[-10. -10. -10.  -10.  -10.]
 [  1.   2.   3.    4.    3.]
 [-10. -10. -10.  -10.  -10.]
 [  3.   1.   2.    4.    1.]]

**8.** Write the modified field to disk.

>>> cf.write(f, 'newfile.nc')

----

.. rubric:: Footnotes

.. [#f1] This file may be also found in the ``docs/build/_downloads/``
         directory of the installation.