source: nappy/trunk/doc/00README.txt @ 344

Subversion URL: http://proj.badc.rl.ac.uk/svn/ndg/nappy/trunk/doc/00README.txt@344
Revision 344, 5.4 KB checked in by astephen, 15 years ago (diff)

* empty log message *

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
Line 
1nappy
2=====
3
4NASA Ames Package in Python.
5
6Description:
7============
8
9A NASA Ames IO package - A python input/output package for NASA Ames file formats
10
11
12Version history:
13================
14
15Most recent version
16
17Version 0.9.7.2: Original - Ag Stephens, 14th May 2004.
18
19
20Planning Notes:
21===============
22
23Software written with reference to:
24
25'Format Specification for Data Exchange' paper by Gaines and Hipkind (1998).
26makeheader.f fortran application to write NASA Ames headers, Anne de Rudder (2000).
27Ames python library developed by Bryan Lawrence (2003).
28
29Conventions:
30==============
31
32The basic NASAAmes class holds a dictionary called naVars which holds all the
33variables described in the Gaines and Hipkind document and these are all named
34using CAPITAL LETTERS for compliance/reference with that document.
35
36For example the number of independent variables is held in the instance variable:
37
38self["NIV"]
39
40Return values are being calculated for many functions/methods are often prefixed with
41'rt' symbolising 'return'.
42
43
44CDMS-link
45=========
46
47At the start, there are a number of formats that are not compatible with the CDMS format:
48
492110 - changing second independent variable length at each first independent variable value.
502160 - Character independent and auxiliary variables - would need a map to implement in CDMS so not intended.
512310 - changing second independent variable length at each first independent variable value.
52
53The following are unlikely, but can be done:
54
551020 - with NVPM (implied independent variable values) - we can allow it but low priority to implement.
56
57FFIs that need to be converted:
58
591001, 1010, 2010, 3010, 4010.
60
61The following have already been done:
62
631001, 2010, 3010, 4010.
64
65Current Status of the software
66==============================
67
68All read classes should now work.
69
70Use the test/testReadAllFFIs.py scripts to try and read them.
71
72Note that the data sections may not be reading properly for some FFIs.
73
74The FFI classes for 2010, 3010 and 4010 all follow the same code exactly.
75
76Write classes should be working for: 1001, 2010, 3010 and 4010.
77
78You can test these using:
79
80test/testWrites.py
81
82You can write cdat output files to the following formats (i.e. any that you can write to from nappy):
83
841001, 2010, 3010, 4010.
85
86Test with:
87
88test/testCmdsWrite.py
89
90
91Reversing the independent variable marks
92========================================
93
94I have reversed the contents of the X, XNAME, DX, NX and NXDEF arrays as they are
95recorded in the NASA Ames documentation as Fortran-style arrays. These are indexed
96from the most-changing variable first whereas Python and C-style arrays are indexed
97from the least-changing variable first. These have therefore been reversed on input
98and may not match the documentation accordingly. However, when writing output to
99NASA Ames they are reversed again so that the files themselves will not be affected.
100
101/bin directory
102==============
103The /bin directory holds to python scripts to convert CDMS-compatible files to and
104from NASA Ames format. Note that CDMS can read Grads format (including GRIB), NetCDF,
105HDF (not as standard) and other formats and can therefore convert these files to NASA
106Ames.
107
108/doc directory
109==============
110
111Contains information on the package as well the original specification document for NASA Ames.
112
113
114Windows version
115===============
116
117The main package has been written without dependencies on other packages so instead of
118using Numeric arrays only lists are used. Whilst making a slight performance sacrifice
119this makes the package portable quickly to more platforms. In particular it can be used
120on Windows.
121
122Both the NASA Ames file classes and the conversion tools in the /bin directory contain
123calls to CDAT (cdms package) but an error is raised to inform users of Windows that this
124is not available. However, the read and write NASA Ames routines are not affected.
125
126
127
128Plans for improving nappy
129=========================
130
131
132•       Split the code into individual FFI files (naFile1001, naFile1010 etc). - Ag
133    ALL SPLIT AND READS APPEAR TO BE WORKING.
134•       Document code – Ag  - MAINLY DONE
135•       Write a NASA Ames compliance document by working through the Gaines and Hipkind guide and listing all the requirements of a file conforming to the NASA Ames standard – Wendy.
136•       Test all the input/output routines – Sue.
137•       Write additional output routines for FFI 1010, 1020, 2310, 2160, 2110. – Sue.
138•       Write a manual for the package - Ag
139•       Create a standard mapping file between cdat and nappy so that global attributes convert appropriately. This should be xml and should be a local table for various centres – Sue and Ag.
140•       Put the cdms stuff in the a class called NACdms and put that in cdmsTools/cdmsOut.py -> CdmsOut().
141        NOT DONE DUE TO ANNOYING MULTIPLE RECURSIVE IMPORT DEPENDENCIES!!!
142•       Make the /bin directory and put the scripts in there called cdms2na.py, na2nc.py, also make nc2na.py that is just a pointer to cdms2na.py (just there to simplify things for dummies).
143
144- routines should not automatically read or write the DATA section.
145   DONE FOR READING, IS IT NEEDED FOR WRITING - you either write or you don't.
146- strip out _recursiveList operators so that they can be used elsewhere (and any other generic funcs) - maybe put in listManipulators.py
147    DONE TELL SUE.
148- Organise the underscores leading func names to be coherent.
149    DONE
150- Start including exceptions everywhere for checking.
151- history doesn't map properly from netcdf.
152- delimiters - let the user decide how to space items.
153- output formatting - let user decide eg %s, %4.3f etc
154
155
156
157
Note: See TracBrowser for help on using the repository browser.