source: nappy/tags/nappy_pre_refactor_feb2008/nappy/naFile.py @ 3313

#   Copyright (C) 2004 CCLRC & NERC( Natural Environment Research Council ).
#   This software may be distributed under the terms of the
#   Q Public License, version 1.0 or later. http://ndg.nerc.ac.uk/public_docs/QPublic_license.txt

"""
naFile.py
=========

A containter module for the mixin base class NAFile that is subclassed
for individual FFIs. Each FFI class is held in an individual file.

"""

# 08/05/04 updated by selatham for bug fixes and new write methods

# Imports from python standard library
import sys
import time
import re
import StringIO

# Imports from nappy package
import naCore
from textParser import *
from naError import *
import naToCdms

class NAFile(naCore.NACore, naToCdms.NAToCdms):

    """
    NAFile class is a sub-class of NACore and NAToCdms mixin classes.
    NAFile is also a mixin class and should not be called directly.
    
    NAFile holds all the methods are common to either all or more than
    one NASA Ames FFI class. These methods set up the main read and write
    functionality for the NASA Ames format.

    When a sub-class of NAFile is called with a read ('r' - default) or
    write ('w') mode the header in the file is automatically read or written.
    However, the user must explicitly read or write the data section with a
    call to the 'readData' or 'writeData' methods.

    """

    def __init__(self, filename, mode="r", naDict={}, spacer="    ", floatFormat="%8.3f"):
        """
        Initialization of class, decides if user wishes to read or write
        NASA Ames file.
        """
        naCore.NACore.__init__(self)
        self.naDict=naDict
        self.filename=filename
        self._open(mode)
        self.spacer=spacer
        self.floatFormat=floatFormat

        if mode=="r":
            self._normalizedX="yes"
            self.readHeader()
        elif mode=="w":
            self._parseDictionary()
            self.header=StringIO.StringIO()
            self.writeHeader()
            self.writeData()
        else:
            raise "Unknown file mode '%s'." % mode
        self.close()
        
    def _open(self, mode):
        "Wrapper to builtin open file function."
        self.file=open(self.filename, mode)

    def close(self):
        "Wrapper to builtin close file function."
        self.file.close()

    def _parseDictionary(self):
        """
        Parser for the optional naDict argument containing a dictionary
        of NASA Ames internal variables. These are saved as instance attributes
        with the name used in the NASA Ames documentation.
        """
        for i in self.naDict.keys():
            setattr(self, i, self.naDict[i])

    def _readTopLine(self):
        """
        Reads number of header lines and File Format Index from top line.
        Also assigns a value to NIV for the number of independent variables
        based on the first character in the FFI.

        Returns NLHEAD and FFI in a tuple.
        """
        (self.NLHEAD, self.FFI)=readItemsFromLine(self.file.readline(), 2, int)
        self.NIV=int(self.FFI/1000)
        return (self.NLHEAD, self.FFI)

    def _readLines(self, nlines):
        "Reads nlines lines from a file and returns them in a list."
        lines=[]
        for i in range(nlines):
            lines.append(self.file.readline().strip())
        return lines

    def _checkForBlankLines(self, datalines):
        """
        Searches for empty lines in the middle of the data section and raises
        as error if found. It ignores empty lines at the end of the file but
        strips them out before returning a list of lines for reading.
        """
        empties=None
        count=0
        rtlines=[]
        for line in datalines:
            #if re.match(r"^[\s\n\t\r]*$", line):
            if not line.strip(): #looks for blank line, quicker than reg ex
                empties=1
            else:
                if empties==1:   # If data line found after empty line then raise
                    raise "Empty line found in data section at line: %s" % count
                else:
                    rtlines.append(line)
            count=count+1
        return rtlines

    def _readCommonHeader(self):
        """
        Reads the header section common to all NASA Ames files.
        """
        self._readTopLine()
        self.ONAME=readItemFromLine(self.file.readline(), str)
        self.ORG=readItemFromLine(self.file.readline(), str)
        self.SNAME=readItemFromLine(self.file.readline(), str)
        self.MNAME=readItemFromLine(self.file.readline(), str)
        (self.IVOL, self.NVOL)=readItemsFromLine(self.file.readline(), 2, int)
        dates=readItemsFromLine(self.file.readline(), 6, int)
        (self.DATE, self.RDATE)=(dates[:3], dates[3:])

    def _writeCommonHeader(self):
        """
        Writes the header section common to all NASA Ames files.
        """
        self.header.write("%s    %s\n" % (self.NLHEAD, self.FFI))
        self.header.write("%s\n" % self.ONAME)
        self.header.write("%s\n" % self.ORG)
        self.header.write("%s\n" % self.SNAME)
        self.header.write("%s\n" % self.MNAME)
        self.header.write("%s    %s\n" % (self.IVOL, self.NVOL))
        self.header.write("%s %s %s    %s %s %s\n" % (self.DATE[0], self.DATE[1], self.DATE[2], self.RDATE[0], self.RDATE[1], self.RDATE[2]))

    def _readVariablesHeaderSection(self):
        """
        Reads the variables section of the header.
        Assumes we are at the right point in the file.
        """
        self.NV=readItemFromLine(self.file.readline(), int)
        self.VSCAL=readItemsFromUnknownLines(self.file, self.NV, float)
        self.VMISS=readItemsFromUnknownLines(self.file, self.NV, float)
        self.VNAME=readItemsFromLines(self._readLines(self.NV), self.NV, str)

    def _writeVariablesHeaderSection(self):
        """
        Writes the variables section of the header.
        Assumes we are at the right point in the file.
        """        
        self.header.write("%s\n" % self.NV)
        self.header.write(("%s "*self.NV+"\n") % tuple(self.VSCAL))
        self.header.write(("%s "*self.NV+"\n")  % tuple(self.VMISS))
        self.header.write("%s\n"*self.NV % tuple(self.VNAME))

    def _readAuxVariablesHeaderSection(self):
        """
        Reads the auxiliary variables section of the header.
        Assumes we are at the right point in the file.
        """
        self.NAUXV=readItemFromLine(self.file.readline(), int)
        if self.NAUXV>0:        
            self.ASCAL=readItemsFromUnknownLines(self.file, self.NAUXV, float)
            self.AMISS=readItemsFromUnknownLines(self.file, self.NAUXV, float)
            self.ANAME=readItemsFromLines(self._readLines(self.NAUXV), self.NAUXV, str)

    def _writeAuxVariablesHeaderSection(self):
        """
        Writes the auxiliary variables section of the header.
        Assumes we are at the right point in the file.
        """
        self.header.write("%s\n" % self.NAUXV)
        if self.NAUXV>0:
            self.header.write(("%s "*self.NAUXV+"\n")  % tuple(self.ASCAL))
            self.header.write(("%s "*self.NAUXV+"\n")  % tuple(self.AMISS))
            self.header.write("%s\n"*self.NAUXV % tuple(self.ANAME))                    #08/11/04 selatham

    def _readCharAuxVariablesHeaderSection(self):
        """
        Reads the character-encoded auxiliary variables section of the header.
        Assumes we are at the right point in the file.
        """
        self.NAUXV=readItemFromLine(self.file.readline(), int)
        self.NAUXC=readItemFromLine(self.file.readline(), int)
        nonCharAuxVars=self.NAUXV-self.NAUXC
        if self.NAUXV>0:
            self.ASCAL=readItemsFromUnknownLines(self.file, nonCharAuxVars, float)
            self.AMISS=readItemsFromUnknownLines(self.file, nonCharAuxVars, float)
            self.LENA=readItemsFromUnknownLines(self.file, self.NAUXC, int)
            for i in range(nonCharAuxVars):
                self.LENA.insert(0, None)
            self.AMISS=self.AMISS+readItemsFromUnknownLines(self.file, self.NAUXC, str)    
            self.ANAME=readItemsFromLines(self._readLines(self.NAUXV), self.NAUXV, str)        
            
    def _readComments(self):
        """
        Reads the special and normal comments sections.
        Assumes we are at the right point in the file.
        """        
        self.NSCOML=readItemFromLine(self.file.readline(), int)
        self._readSpecialComments()
        self.NNCOML=readItemFromLine(self.file.readline(), int)
        self._readNormalComments()

    def _writeComments(self):
        """
        Writes the special and normal comments sections.
        Assumes we are at the right point in the file.
        """  
        self.header.write("%s\n" % self.NSCOML)
        self.header.write("%s\n"*self.NSCOML % tuple(self.SCOM))
        self.header.write("%s\n" % self.NNCOML)
        self.header.write("%s\n"*self.NNCOML % tuple(self.NCOM))

    def _fixHeaderLength(self, header):
        """
        Takes the header StringIO object and counts the number of lines to
        return a list of lines with the correct number of header lines in 
        the top line.
        """
        header.seek(0)
        lines=header.readlines()
        headlength=len(lines)
        lines[0]="%s    %s\n" % (headlength, self.FFI)
        return lines

    def _readSpecialComments(self):
        """
        Reads the special comments section.        
        Assumes that we are at the right point in the file and that NSCOML
        variable is known.
        """
        self.SCOM=self._readLines(self.NSCOML)
        return self.SCOM

    def _readNormalComments(self):
        """
        Reads the normal comments section.        
        Assumes that we are at the right point in the file and that NNCOML
        variable is known.
        """
        self.NCOM=self._readLines(self.NNCOML)
        return self.NCOM

    def readData(self):
        """
        Reads the data section of the file. This method actually calls a number
        of FFI specific methods to setup the data arrays (lists of lists) and
        read the various data sections.

        This method can be called directly by the user.
        """
        self._setupArrays()
        datalines=open(self.filename).readlines()[self.NLHEAD:]
        datalines=self._checkForBlankLines(datalines)

        # Set up loop over unbounded indpendent variable
        m=0   # Unbounded independent variable mark        
        while len(datalines)>0:
            datalines=self._readData1(datalines, m)
            datalines=self._readData2(datalines, m)
            m=m+1