source: nappy/tags/nappy_pre_refactor_feb2008/nappy/naCore.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

"""
naCore.py
=========

Holds the NACore class that holds the None type version
of all the possible NASA Ames variables described in the Gaines
and Hipkind documents. It also holds a number of useful methods
for accessing metadata within the file.

"""

# Imports from standard python library
import re

class NACore:
    """
    Abstract class to hold the empty NASA Ames contents and 
    a number of methods to access information in files. This
    class is sub-classed by all NAFile classes.
    """
    
    pattnBrackets=re.compile("^\s*(.*)\((.+?)\)(.*)\s*$")

    def __init__(self):
        """
        Creates an instance variable of every type used in all
        NA formats. All are set to None until/unless defined.
        """

        self.A=None
        self.AMISS=None
        self.ANAME=None
        self.ASCAL=None
        self.DATE=None
        self.DX=None
        self.FFI=None
        self.IVOL=None
        self.LENA=None
        self.LENX=None
        self.MNAME=None
        self.NAUXC=None
        self.NAUXV=None
        self.NCOM=None
        self.NIV=None
        self.NLHEAD=None
        self.NNCOML=None
        self.NSCOML=None
        self.NV=None
        self.NVOL=None
        self.NVPM=None
        self.NX=None
        self.NXDEF=None
        self.ONAME=None
        self.ORG=None
        self.RDATE=None
        self.SCOM=None
        self.SNAME=None
        self.V=None
        self.VMISS=None
        self.VNAME=None
        self.VSCAL=None
        self.X=None
        self.XNAME=None        


    def getNADict(self):
        """
        Returns a dictionary of the contents of a NASA Ames file.
        """
        allNAVars={"A":self.A, "AMISS":self.AMISS, "ANAME":self.ANAME,
                     "ASCAL":self.ASCAL, "DATE":self.DATE, "DX":self.DX,
                     "FFI":self.FFI, "IVOL":self.IVOL, "LENA":self.LENA,
                     "LENX":self.LENX, "MNAME":self.MNAME, "NAUXC":self.NAUXC,
                     "NAUXV":self.NAUXV, "NCOM":self.NCOM, "NIV":self.NIV,
                     "NLHEAD":self.NLHEAD, "NNCOML":self.NNCOML,
                     "NSCOML":self.NSCOML, "NV":self.NV, "NVOL":self.NVOL,
                     "NVPM":self.NVPM, "NX":self.NX, "NXDEF":self.NXDEF,
                     "ONAME":self.ONAME, "ORG":self.ORG, "RDATE":self.RDATE,
                     "SCOM":self.SCOM, "SNAME":self.SNAME, "V":self.V,
                     "VMISS":self.VMISS, "VNAME":self.VNAME, "VSCAL":self.VSCAL,
                     "X":self.X, "XNAME":self.XNAME}
        self.naDict={}
        for i in allNAVars.keys():
            if allNAVars[i]!=None:
                self.naDict[i]=allNAVars[i]
        return self.naDict


    def __getitem__(self, item):
        """
        Dictionary item access to NASA Ames contents, called NAFileObj['NIV']
        will return NAFileObj.NIV.
        
        Note: In future this might return whatever user wants and to translate
        NASA Ames variables such as 'NIV' to explanatory strings
        such as 'number_of_independent_variables'. Need a map for
        this defined at top of the nasaAmesData.py module
        """
        if hasattr(self, item):
            return getattr(self, item)
        else:
            return "Item '%s' not found." % item


    def getVariable(self, var_number): 
        """
        Returns variable metadata corresponding to the var_number argument in the 
        list of varibles. Tuple of (variable_name, units, missing_value, scale_factor)
        is returned.
        """
        match=NACore.pattnBrackets.match(self.VNAME[var_number])
        if match:
            (v1, units, v2)=match.groups()
            variable=v1+" "+v2
        else:
            (variable, units)=(self.VNAME[var_number], None)
        miss=self.getMissingValue(var_number)
        scale=self.getScaleFactor(var_number)
        return (variable.strip(), units, miss, scale)


    def getIndependentVariable(self, ivar_number):
        """
        Returns an independent variable name and units in a tuple corresponding to
        the ivar_number index in the list.
        """
        match=NACore.pattnBrackets.match(self.XNAME[ivar_number])
        if match:
            (v1, units, v2)=match.groups()
            variable=v1+" "+v2
        else:
            (variable, units)=(self.XNAME[ivar_number], None)
        return (variable.strip(), units)


    def getAuxVariable(self, avar_number):        
        """
        Returns an auxiliary variable name and units in a tuple corresponding to
        the ivar_number index in the list.
        """
        match=NACore.pattnBrackets.match(self.ANAME[avar_number])
        if match:
            (v1, units, v2)=match.groups()
            variable=v1+" "+v2
        else:
            (variable, units)=(self.ANAME[avar_number], None)
        miss=self.getAuxMissingValue(avar_number)
        scale=self.getAuxScaleFactor(avar_number)
        return (variable.strip(), units, miss, scale)    


    def getVariables(self):
        """
        Returns metadata for all main (non-auxiliary or independent) variables.
        """
        vars=[]
        for i in range(self.NV):
            vars.append(self.getVariable(i))
        return vars

    def getIndependentVariables(self):
        """
        Returns metadata for all independent variables.
        """
        ivars=[]
        for i in range(self.NIV):
            ivars.append(self.getIndependentVariable(i))
        return ivars

    def getAuxVariables(self):
        """
        Returns metadata for all auxiliary variables.
        """
        avars=[]
        if not hasattr(self, "NAUXV"):
            for i in range(self.NAUXV):
                avars.append(self.getAuxVariable(i))
        else:
            avars=[]
        return avars


    def getMissingValue(self, var_number):
        """
        Returns a missing value for a given variable.
        """
        return self.VMISS[var_number]


    def getScaleFactor(self, var_number):
        """
        Returns a scale factor for a given variable.
        """
        return self.VSCAL[var_number]
        

    def getAuxMissingValue(self, avar_number):
        """
        Returns the missing value of an auxiliary variable.
        """
        return self.AMISS[avar_number]


    def getAuxScaleFactor(self, avar_number):
        """
        Returns the scale factor of an auxiliary variable.
        """ 
        return self.ASCAL[avar_number]


    def getNumHeaderLines(self):
        """
        Returns the number of header lines.
        """
        return self.NLHEAD


    def getFFI(self):
        """
        Returns the File Format Index for the file.
        """
        return self.FFI


    def getOriginator(self):
        """
        Returns the Originator (ONAME) string.
        """
        return self.ONAME


    def getOrganisation(self):
        """
        Returns the Organisation (ORG) string.
        """
        return self.ORG


    def getOrg(self):
        """
        Returns the Organisation (ORG) string.
        """
        return self.getOrganisation()


    def getSource(self):
        """
        Returns the Source (SOURCE) string.
        """
        return self.SNAME


    def getMission(self):
        """
        Returns the mission (MNAME) string.     
        """
        return self.MNAME


    def getVolumes(self):
        """
        Returns the volume numbers (IVOL and NVOL).
        """
        return (self.IVOL, self.NVOL)


    def getFileDates(self):
        """
        Returns the first valid date in the data (DATE) and the 
        Revision Date (RDATE).
        """
        return (self.DATE, self.RDATE)


    def getNormalComments(self):
        """
        Returns the Normal Comment (NCOM) lines.
        """
        return self.NCOM


    def getSpecialComments(self):
        """
        Returns the Special Comments (SCOM) lines.
        """
        return self.SCOM