source: nappy/trunk/doc/USAGE.txt @ 348

Subversion URL: http://proj.badc.rl.ac.uk/svn/ndg/nappy/trunk/doc/USAGE.txt@348
Revision 348, 10.5 KB checked in by selatham, 15 years ago (diff)

08/11/04 include Sue Latham's changes for bug fixes and new Write methods.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
Line 
1Usage documentation for nappy
2=============================
3
4Nappy provides the following functionality:
5
61. A set of I/O routines for most NASA Ames File Format Indices (FFIs).
7
82. An implicit checking facility for NASA Ames compliance - i.e. if the file is formatted incorrectly then a python error will be
9raised. This checking facility will eventually be made explicit to report NASA Ames specific errors.
10
113. Methods to interrogate the contents the contents of NASA Ames files (such as: naFile.getVariable(),
12naFile.getIndependentVariables(), naFile.getMissingValue() etc.).
13
144. A set of routines to allow conversion to and from NetCDF (for the most common FFIs) using the Climate Data Analysis Tools
15(CDAT) package. This functionality is only available on Unix/linux operating systems as CDAT has not been ported to Windows. Note
16that any CDAT-compatible format can potentially be converted to NASA Ames via these routines.
17
185. Some command line utilities for the format conversions in (4).
19
20----------------------------
21PYTHONPATH AND IMPORT ISSUES
22----------------------------
23
24The most common stumbling block for python users is getting to grips with PYTHONPATH (or sys.path), an environment variable used to tell
25python where it should look for modules and packages.
26
27In order for your python scripts, modules and interactive sessions to find the nappy package you must make the directory visible by pointing
28to it in one of the following ways.
29
30If the nappy directory has been installed at /my/nappy/location/nappy then the directory you need to tell python about is /my/nappy/location.
31
32Option 1. Append your nappy path to the PYTHONPATH environment variable:
33
34$ export PYTHONPATH=$PYTHONPATH:/my/nappy/location
35
36Option 2: Append your nappy path once within python:
37
38$ python
39>>> import sys   # Imports the sys module
40>>> sys.path.append("/my/nappy/location")   # Adds the directory to others used when searching for a module.
41
42You should then be able to import nappy with:
43
44>>> import nappy
45
46Note that if you have CDAT installed then you must also point to relevant CDAT directories with either the PYTHONPATH or sys.path variable.
47
48The following examples demonstrate and overview of nappy usage:
49
50-----------------------------------------------------
51Example 1: Opening and interrogating a NASA Ames file
52-----------------------------------------------------
53
54Open the python interactive prompt:
55
56$ python
57
58Import the nappy package:
59
60>>> import nappy
61
62Open a NASA Ames file (reading the header only):
63
64>>> myfile=nappy.openNAFile('some_nasa_ames_file.na')
65
66Query the methods on the 'myfile' objects:
67
68>>> dir(myfile)
69
70['A', 'AMISS', 'ANAME', 'ASCAL', 'DATE', 'DX', 'FFI', 'IVOL', 'LENA', 'LENX', 'MNAME', 'NAUXC', 'NAUXV', 'NCOM', 'NIV', 'NLHEAD', 'NNCOML', 'NSCOML', 'NV', 'NVOL', 'NVPM', 'NX', 'NXDEF', 'ONAME', 'ORG', 'RDATE', 'SCOM', 'SNAME', 'V', 'VMISS', 'VNAME', 'VSCAL', 'X', 'XNAME', '__doc__', '__getitem__', '__init__', '__module__', '_checkForBlankLines', '_normalizeIndVars', '_normalizedX', '_open', '_parseDictionary', '_readAuxVariablesHeaderSection', '_readCharAuxVariablesHeaderSection', '_readComments', '_readCommonHeader', '_readData1', '_readData2', '_readLines', '_readNormalComments', '_readSpecialComments', '_readTopLine', '_readVariablesHeaderSection', '_setupArrays', '_writeAuxVariablesHeaderSection', '_writeComments', '_writeCommonHeader', '_writeVariablesHeaderSection', 'auxToCdmsVariable', 'close', 'createCdmsAuxVariables', 'createCdmsAxes', 'createCdmsVariables', 'file', 'filename', 'floatFormat', 'getAuxMissingValue', 'getAuxScaleFactor', 'getAuxVariable', 'getAuxVariables', 'getFFI', 'getFileDates', 'getIndependentVariable', 'getIndependentVariables', 'getMissingValue', 'getMission', 'getNADict', 'getNormalComments', 'getNumHeaderLines', 'getOrg', 'getOrganisation', 'getOriginator', 'getScaleFactor', 'getSource', 'getSpecialComments', 'getVariable', 'getVariables', 'getVolumes', 'naDict', 'pattnBrackets', 'readData', 'readHeader', 'spacer', 'toCdmsAxis', 'toCdmsFile', 'toCdmsVariable', 'writeData', 'writeHeader']
71
72List the variables:
73
74>>> myfile.getVariables()
75[('Mean zonal wind', 'm/s', 200.0, 1.0)]
76
77List the independent variables (or dimension axes):
78
79>>> myfile.getIndependentVariables()
80[('Altitude', 'km'), ('Latitude', 'degrees North')]
81
82Get a dictionary of the file contents in the form of NASA Ames documentation:
83
84>>> myfile.getNADict()
85{'ASCAL': [1.0], 'NLHEAD': 43, 'NNCOML': 11, 'NCOM': ['The files included in this data set illustrate each of the 9 NASA Ames file', 'format indices (FFI). A detailed description of the NASA Ames format can be', 'found on the Web site of the British Atmospheric Data Centre (BADC) at', 'http://www.badc.rl.ac.uk/help/formats/NASA-Ames/', 'E-mail contact: badc@rl.ac.uk', 'Reference: S. E. Gaines and R. S. Hipskind, Format Specification for Data', 'Exchange, Version 1.3, 1998. This work can be found at', 'http://cloud1.arc.nasa.gov/solve/archiv/archive.tutorial.html', 'and a copy of it at', 'http://www.badc.rl.ac.uk/help/formats/NASA-Ames/G-and-H-June-1998.html', ''], 'DX': [20.0, 10.0], 'DATE': [1969, 1, 1], 'NXDEF': [1], 'ONAME': 'De Rudder, Anne', 'SNAME': 'Anemometer measurements averaged over longitude', 'MNAME': 'NERC Data Grid (NDG) project', 'NX': [9], 'NSCOML': 9, 'RDATE': [2002, 10, 31], 'AMISS': [2000.0], 'VSCAL': [1.0], 'NV': 1, 'NVOL': 13, 'X': [[], [0.0]], 'XNAME': ['Altitude (km)', 'Latitude (degrees North)'], 'VNAME': ['Mean zonal wind (m/s)'], 'SCOM': ['Example of FFI 2010 (b).', 'This example illustrating NASA Ames file format index 2010 is based on results', 'from Murgatroyd (1969) as displayed in Brasseur and Solomon, Aeronomy of the', 'Middle Atmosphere, Reidel, 1984 (p.36). It is representative of the mean zonal', 'wind distribution in the winter hemisphere as a function of latitude and height.', 'The first date on line 7 (1st of January 1969) is fictitious.', 'From line 10 (NXDEF = 1) we know that the latitude points are defined by', 'X(i) = X(1) + (i-1)DX1 for i = 1, ..., NX', 'with X(1) = 0 deg (line 11), DX1 = 10 deg (line 8) and NX = 9 (line 9).'], 'VMISS': [200.0], 'IVOL': 7, 'FFI': 2010, 'ORG': 'Rutherford Appleton Laboratory, Chilton OX11 0QX, UK - Tel.: +44 (0) 1235 445837', 'NIV': 2, 'ANAME': ['Pressure (hPa)'], 'NAUXV': 1}
86
87Grab the normal comments:
88
89>>> comm=myfile.naDict["NCOM"]
90>>> print comm
91['The files included in this data set illustrate each of the 9 NASA Ames file', 'format indices (FFI). A detailed description of the NASA Ames format can be', 'found on the Web site of the British Atmospheric Data Centre (BADC) at', 'http://www.badc.rl.ac.uk/help/formats/NASA-Ames/', 'E-mail contact: badc@rl.ac.uk', 'Reference: S. E. Gaines and R. S. Hipskind, Format Specification for Data', 'Exchange, Version 1.3, 1998. This work can be found at', 'http://cloud1.arc.nasa.gov/solve/archiv/archive.tutorial.html', 'and a copy of it at', 'http://www.badc.rl.ac.uk/help/formats/NASA-Ames/G-and-H-June-1998.html', '']
92>>>
93
94Use the file method to get the normal comments:
95
96>>> myfile.getNormalComments()
97['The files included in this data set illustrate each of the 9 NASA Ames file', 'format indices (FFI). A detailed description of the NASA Ames format can be', 'found on the Web site of the British Atmospheric Data Centre (BADC) at', 'http://www.badc.rl.ac.uk/help/formats/NASA-Ames/', 'E-mail contact: badc@rl.ac.uk', 'Reference: S. E. Gaines and R. S. Hipskind, Format Specification for Data', 'Exchange, Version 1.3, 1998. This work can be found at', 'http://cloud1.arc.nasa.gov/solve/archiv/archive.tutorial.html', 'and a copy of it at', 'http://www.badc.rl.ac.uk/help/formats/NASA-Ames/G-and-H-June-1998.html', '']
98
99Read the actual data:
100
101>>> myfile.readData()
102
103Inspect the data array ("V") in the NASA Ames dictionary:
104
105>>> print myfile.naDict["V"}
106[[[-3.0, -2.6000000000000001, -2.2999999999999998, 2.0, 4.7999999999999998, 4.5999999999999996, 4.5, 3.0, -0.90000000000000002], [-15.1, -4.2000000000000002, 6.9000000000000004, 12.800000000000001, 14.699999999999999, 20.0, 21.5, 18.0, 8.1999999999999993], [-29.0, -15.199999999999999, 3.3999999999999999, 28.199999999999999, 41.0, 39.100000000000001, 17.899999999999999, 8.0, 0.10000000000000001], [-10.0, 8.4000000000000004, 31.199999999999999, 59.899999999999999, 78.5, 77.700000000000003, 47.0, 17.600000000000001, 16.0], [200.0, 200.0, 200.0, 200.0, 200.0, 200.0, 200.0, 200.0, 200.0]]]
107
108[NOTE: We plan to implement a getVariableArray(var_name) to grab a specific variable from the above array.]
109
110-----------------------------------
111Example 2: Writing a NASA Ames file
112-----------------------------------
113
114Start the python interactive prompt:
115
116$ python
117
118Import the nappy package:
119
120>>> import nappy
121
122Pretend you have created a complete NASA Ames file contents in a dictionary called 'na_contents'.
123Write the data to a NASA Ames file:
124
125>>> nappy.openNAFile('my_file_to_write.na', 'w', na_contents)
126
127-------------------------------------------------------
128Example 3: Converting a NASA Ames file to a NetCDF file
129-------------------------------------------------------
130
131[Note: this utility is only available on Unix/linux platforms]
132
133Run the command-line utility in the /bin directory:
134
135$ na2nc -t "seconds since 1999-01-01 00:00:00" -i my_nasa_ames_file.na -o my_netcdf_file.nc
136
137Note that the '-t' argument allows you to pass a NetCDF-style data/time units description into your NetCDF that will allow software packages to identify the time axis correctly. This is required when the time unit string in your NASA Ames file is non-standard.
138
139For help on the command-line utility type:
140
141$ na2nc -h
142
143na2nc
144=====
145
146Converts a NASA Ames file to a NetCDF file.
147
148Usage
149=====
150
151   na2nc.py [<options>] -i <infilename> -o <outfilename>
152
153Where
154-----
155
156    infilename  - name of input file (NASA Ames).
157    outfilename - name of output file (NetCDF).
158    options     - list of options:
159                    -t <time_units_string>  (such as "hours since 2003-04-30 10:00:00")
160                   
161                   
162
163-------------------------------------------------------
164Example 4: Converting a NetCDF file to a NASA Ames file
165-------------------------------------------------------
166
167[Note: this utility is only available on Unix/linux platforms]
168
169Run the command-line utility in the /bin directory:
170
171$ nc2na -i my_netcdf_file.nc -o my_nasa_ames_file.na
172
173For help on the command-line utility type:
174
175cdms2na.py
176==========
177
178Converts a CdmsFile object into one a NASA Ames file.
179
180Usage
181=====
182
183    cdms2na.py [<options>] -i <infilename> -o <outfilename>
184
185Where
186-----
187
188    infilename  - name of input file (NetCDF).
189    outfilename - name of output file (NASA Ames).
190    options     - list of options [NOT YET IMPLEMENTED].
191
Note: See TracBrowser for help on using the repository browser.