Changeset 3267 for TI02-CSML


Ignore:
Timestamp:
25/01/08 14:05:32 (11 years ago)
Author:
domlowe
Message:

Documenting CSML code - not complete

Location:
TI02-CSML/trunk/csml/API
Files:
9 edited

Legend:

Unmodified
Added
Removed
  • TI02-CSML/trunk/csml/API/csmlContainer.py

    r2774 r3267  
     1'''Container that can store features before building a CSML Dataset. Used when subsetting several features for building a new CSML document on the fly''' 
     2 
    13import csml 
    24OUTPUTDIR=None 
     
    1012    '''CSMLContainer object is used to hold features before generating a CSML document. This is useful because it allows you to subset several features sequentially then build a single CSML document containing all the subsetted features ''' 
    1113     
    12     def __init__(self,outputdir, csmlname='myfile.xml',docID='none',metadata='unspecified', datasetName='unspecified'): 
     14    def __init__(self,outputdir, csmlname='csmlfile.xml',docID='none',metadata='unspecified', datasetName='unspecified'): 
     15        ''' 
     16        @param outputdir:   Directory name for output csml document (string) 
     17        @param csmlname:    Optional name of output document. 
     18        @param docID:   ID to put in CSML document Dataset id attribute 
     19        @param metadata:    Metadata string to put in csml document 'metaDataProperty' tag 
     20        @param datasetName:     String to put in csml document 'name' tag - name of the CSML dataset. 
     21        ''' 
    1322        self.outputdir =outputdir 
    1423        globalContainer.OUTPUTDIR=outputdir 
     
    5059        ''' Append File Extract to Dataset ''' 
    5160        #append to Dataset instance 
     61        #Not implemented 
    5262        pass 
    5363     
    5464    def appendFeature(self, feature): 
    55         ''' Append feature to FeatureCollection''' 
    56         #append to FeatureCollection instance 
     65        ''' Append feature to FeatureCollection 
     66        @param feature:     A feature instance''' 
    5767        self.fm.append(feature) 
    5868     
    5969    def attachNetCDFFile(self, ncfile): 
    60         ''' Attach a NetCDF file to the container object. Multiple NetCDF files can be referenced from multiple features and returned with the CSML document''' 
    61         #append NetCDF file path to containerContents 
     70        ''' Attach a NetCDF file to the container object. Multiple NetCDF files can be referenced from multiple features and returned with the CSML document 
     71        @param ncfile:    File path to the netcdf file 
     72        ''' 
    6273        self.ncfiles.append(ncfile) 
    6374     
    6475    def attachDescriptor(self, descriptor): 
     76        ''' 
     77        Attach an ArrayDescriptor (e.g. A NetCDFExtract) to the CSMLStorageDescriptor 
     78        @param descriptor: ArrayDescriptor instance 
     79        ''' 
    6580        self.sd.append(descriptor) 
    6681 
    6782    def add(self, featureplusfileplusdescriptor): 
    68         #featureplusfileplusdescriptor should be a feature, and a filepath to the netcdf file, and a storage descriptor 
     83        ''' Attach a feature, file and corresponding storageDescriptor' 
     84        @param featureplusfileplusdescriptor:    featureplusfileplusdescriptor should be a feature, and a filepath to the netcdf file, and a storage descriptor  in a list (in that order) ''' 
    6985        self.appendFeature(featureplusfileplusdescriptor[0]) 
    7086        self.attachNetCDFFile(featureplusfileplusdescriptor[1])        
     
    7894    
    7995    def getContents(self): 
     96        ''' 
     97        Return the contents of the Container 
     98        @return:    a list containing paths to the completed csml file and the associated netcdf files 
     99        ''' 
    80100        self.ds.storageDescriptor=csml.parser.CSMLStorageDescriptor(descriptors=self.sd) 
    81101        self.ds.featureCollection=csml.parser.CSMLFeatureCollection(featureMembers=self.fm) 
  • TI02-CSML/trunk/csml/API/csmlbbox.py

    r2890 r3267  
    1  
     1''' Contains implementation of a CSML bounding box with methods for getting the times, CRS and bounding points''' 
    22class CSMLBoundingBox(object): 
    3     """ class to represent an EnvelopeWithTimePeriod Bounding Box """ 
     3    """ Class to represent an EnvelopeWithTimePeriod Bounding Box """ 
    44    def __init__(self, envelope): 
    55        self.envelope=envelope 
     
    1010     
    1111    def getCRSName(self): 
     12        '''  
     13        Get the name of the coordinate reference system for this bounding box 
     14        @return:    string containing name of crs 
     15        ''' 
    1216        return self.envelope.srsName      
    1317      
    1418    def getBox(self): 
     19        ''' 
     20        Get the bounding box values 
     21        @return:    a list of the form [minX, minY, maxX, maxY] 
     22        ''' 
    1523        return [self.minX, self.minY, self.maxX, self.maxY] 
    1624     
    1725    def getTimeLimits(self): 
     26        '''  
     27        Get the start and end times of the bounding box 
     28        @return:    a list of strings: ['starttime', 'endtime'] 
     29        ''' 
    1830        return [self.envelope.beginPosition.CONTENT,self.envelope.endPosition.CONTENT] 
    1931        
  • TI02-CSML/trunk/csml/API/csmlutils.py

    r2741 r3267  
    1 '''csml utils contains useful  utility functions''' 
     1'''csml utils contains useful utility functions that don't belong anywhere else''' 
    22import csml 
    33 
    44def listify(item): 
    5     ''' listify checks if an item is a list, if it isn't it puts it inside a list and returns it. Always returns a list object''' 
     5    ''' listify checks if an item is a list, if it isn't it puts it inside a list and returns it.  
     6    @return:   A lways returns a list object''' 
    67    if type(item) is list: 
    78        return item 
    89    else: 
    9         return [item] 
     10        return [item]     
    1011     
    11      
    12      
    13 #deal with longitude requests 
    14 #if the request is in -ve,+ve eg (-30,30) but the data is in (0,360) need to handle this by changing the args. 
    1512def fixLongitude(request, kwargs): 
     13    ''' 
     14    deals with longitude requests 
     15    if the request is in -ve,+ve eg (-30,30) but the data is in (0,360) need to handle this by changing the args. 
     16    @param kwargs:   dictionary of kwargs representing a selection e.g. {'longitude':(0,30), 'latitude':(-20,20)} 
     17    @return:    dictionary of kwargs, altered from input to fix longitude values 
     18    ''' 
    1619    def _anyitemlessthanzero(listofitems): 
    1720        for item in listofitems: 
     
    4750         
    4851        minBound and maxBound added as options. 
    49         If a value is outside of minBound or maxBound it is nudged so that it is within. 
     52        If a value is outside of minBound or maxBound it is nudged so that it is within.        
    5053         
    51         TODO - rewrite this so it is legible! 
    52          
     54        @param value:    value to check 
     55        @param axisValues:    array of values 
     56        @param minBound:    minimum return value 
     57        @param minBound:    maxmimum return value 
     58        @return:    nearest neighbour of value 
    5359        """ 
    5460        bounds=False 
    5561        reverseBounds=False 
    56          
     62        #TODO - rewrite this so it is legible! 
    5763        #determine if bounds have been provided and if they are of the form (-30,30)  or (330, 30) 
    5864        if minBound!=None: 
  • TI02-CSML/trunk/csml/API/existDB.py

    r2492 r3267  
    1 # Code inspired by example on eXist website. 
     1''' Exist XML database access inspired by example on eXist website ''' 
    22import urllib2, base64, urllib, urlparse, httplib, xmlrpclib, types 
    33 
  • TI02-CSML/trunk/csml/API/genSubset.py

    r3068 r3267  
    1 '''#getSubset.py contains generic subsetting code that can be reused for multiple features 
     1'''getSubset.py contains generic subsetting code that can be reused for multiple features 
    22Dominic Lowe, CCLRC, 31/01/2007''' 
    33 
     
    88 
    99def checkNeighbours(domain, **kwargs): 
    10     #for any non-range requests, get nearest neighbour 
    11     #e.g if 'latitude': (11) requested, latitude=12 may be the nearest value 
     10    ''' 
     11    Compares a subset request (kwargs) to the feature domain and gets nearest neighbour 
     12    e.g if 'latitude': (11) requested, latitude=12 may be the nearest value, calls nudgeSingleValuesToAxisValues 
     13    @param domain:   dictionary 
     14    @param kwargs: dictionary 
     15    returns:    modified kwargs 
     16     
     17    ''' 
    1218    for key in kwargs: 
    1319        #handle single values 
     
    3137def subsetDomain(timeaxis,times, domain,**kwargs): 
    3238    '''takes the domain and returns a subset according to the keyword selection criteria 
    33     time = name of time dimension 
    34     times = string of times 
    35     '''        
     39    @param timeaxis:  name of time dimension 
     40    @param times:    string of times 
     41    @param domain:     feature domain dictionary 
     42    @param kwargs:      keyword selection 
     43    @return:    subsetted domain (dictionary) and a totalArraySize (integer) 
     44   '''        
    3645    #reduce requests with same max and min eg (45,45) down to single value. 
    3746    for kw in kwargs: 
     
    133142 
    134143def _getTimes(timeSelection, timeName, domain): 
     144    ''' Given a selection of times (min_t, max_t) or (t1, t2, t3,...tn) or just 't' and the name of the time axis in the CRS, and the domain, returns subset of times 
     145    @param timeSelection:  times - in one of 3 forms: (min_t, max_t) or (t1, t2, t3,...tn) or just 't'  
     146    @param timeName:      name of the time axis 
     147    @param domain:        the domain dictionary 
     148    @return:     subset of times. e.g if a range is selected, returns all the times in that range. Times are correctly formatted. 
     149    ''' 
    135150    #currently supporting domain subsetting only by CRS name  
    136151    #(but should be easy to extend later) 
     
    162177 
    163178def _getTimeToFileRatio(feature,domain, timeName): 
     179    ''' Calculates the ratio of times to files... i.e are there 5 times in each data file? 500 times?  
     180    @param feature: a feature instance 
     181    @param domain: the domain dictonary 
     182    @param timeName: the name of the time axis in the domain dictionary 
     183    @return:    ratio of times to files (integer) 
     184    ''' 
     185     
    164186    if hasattr(feature.value.rangeSet, 'valueArray'): 
    165187        if hasattr(feature.value.rangeSet.valueArray.valueComponent, 'insertedExtract'):             
     
    177199 
    178200def getCoordTransformTable(domainSubset, crs, frame): 
     201    ''' 
     202    Given a domainSubset and a crs and a temporal reference fram returns a csml.parser.coordTransformTable object 
     203    @param domainSubset:    dictionary 
     204    @param crs:    a crs identifier 
     205    @param frame:      a temporal reference system identifier 
     206    ''' 
    179207    cTT=csml.parser.GridCoordinatesTable() 
    180208    ords =[] 
     
    204232 
    205233def getTheData(feature, selection, times,timeName, timeAxis): 
     234    ''' 
     235    Wraps a lot of the detail involved in making a request for data 
     236    @param feature:    a feature instance 
     237    @param selection:    the selection object 
     238    @param times:       the times to select 
     239    @param timeName:     the name of the time axis 
     240    @param timeaxis: TODO REMOVE THIS. 
     241    @return:  times, axisorder, units, fulldata, fillvalue, where fulldata contains the actual data array, and the rest is ancilliary info about the data. 
     242    ''' 
     243     
    206244    #SOME OF THIS SHOULD PROBABLY BE IN THE DATA IO LAYER 
    207245    #add time range back into the selection  
     
    245283                except: 
    246284                    files.append(comp.fileName.CONTENT) 
    247                  
    248  
    249              
    250285            if fulldata is None: 
    251286                fulldata=data 
     
    262297 
    263298def genericSubset(feature, outputdir, ncname, domain, kwargs): 
     299    '''  
     300    High level wrapper method for subsetting features, calls most of the other functions in this module. 
     301    @param feature:   a feature instance 
     302    @param outputdir:    outputdir to write files 
     303    @param  ncname:    name of netcdf file to create 
     304    @param domain:      domain of feature(dictionary) 
     305    @param kwargs:       subset request (dictionary) 
     306    ''' 
     307     
    264308    if outputdir is not None: 
    265309        pathToSubsetNetCDF=outputdir+'/' +ncname 
  • TI02-CSML/trunk/csml/API/ops_AbstractFeature.py

    r2979 r3267  
    1 ''' ops_AbstractFeature  contains operations for AbstractFeatures''' 
     1''' ops_AbstractFeature  contains operations for AbstractFeatures 
     2These methods are attached to AbstractFeature instances at runtime. 
     3Therefore they are inherited by all feature instances (unless they are overwritten''' 
    24import string 
    35import cdtime 
     
    79 
    810def testmethod(self): 
     11    '''test method''' 
    912    print 'testmethod for abstract feature' 
    1013    return 'testmethod abstract feature' 
    1114 
    1215def getAllowedSubsettings(self): 
     16    '''get the allowed operations 
     17    @return:    list of operations''' 
    1318    return ['none'] 
    1419 
    1520def getDomainUnits(self): 
     21    '''  get the units used in the domain''' 
    1622    return None 
    1723     
    1824def getLongitudeAxis(self): 
     25    ''' get the index of the longitude axis, if one exists''' 
    1926    return None 
    2027 
    2128def getLatitudeAxis(self): 
     29    ''' get the index of the latitude axis, if one exists''' 
    2230    return None 
    2331 
    2432def getTimeAxis(self): 
     33    ''' get the index of the time axis, if one exists''' 
    2534    return None 
    2635 
    2736def getAxisLabels(self): 
     37    ''' get the names of all the axes''' 
    2838    return None 
    2939 
    3040def getBoundingBox(self): 
     41    ''' get the simple boundingBox ''' 
    3142    return None 
    3243 
    3344def getCSMLBoundingBox(self): 
    34     #returns a complete boundingBox object including temporal domain and crs 
     45    ''' returns a complete boundingBox object including temporal domain and crs''' 
    3546    if hasattr(self, 'boundedBy'): 
    3647        return csml.API.csmlbbox.CSMLBoundingBox(self.boundedBy) 
     
    3950     
    4051def getNativeCRS(self): 
    41     #returns the crs of the feature 
     52    ''' returns the crs of the feature ''' 
    4253    return None 
    4354 
    4455def getSliceIndices(self, selection): 
    45     ''' Calculates indices to use in slicing (eg for RawFileExtracts) and adds them to the selection dictionary 
    46     #Doesn't work fully due to lack of proper CRS cataloguing so returns empty lists if error is encountered 
     56    ''' Calculates indices to use in slicing (eg for RawFileExtracts) and adds them to the selection dictionary. Doesn't work fully due to lack of proper CRS cataloguing so returns empty lists if error is encountered 
    4757    ''' 
    4858    selLower=[] 
  • TI02-CSML/trunk/csml/API/ops_FileExtract.py

    r3117 r3267  
    1 ''' ops_AbstractFileExtract  contains operations for AbstractFileExtracts''' 
     1''' ops_AbstractFileExtract  contains operations for AbstractFileExtracts which are inherited by any FileExtracts - eg NetCDFExtracts. Methods are attached on the fly.''' 
    22import csml.csmllibs.csmldataiface 
    33import sys 
     
    77 
    88class DataContainer(object): 
     9    ''' A container to wrap some of the inconsistencies of Numeric/MA etc 
     10    Should convert to Numpy in future''' 
    911    #dataArray needs to be the standards data container     
    1012    def __init__(self, data=None): 
     
    2224           
    2325def testmethod(self): 
     26    '''test method''' 
    2427    print 'testmethod for AbstractFileExtract feature' 
    2528    return 'testmethod AbstractFileExtract' 
     
    3033 
    3134def getData(self,  fileposition=None,**kwargs): 
     35    ''' 
     36    get data for a particular file in the file extract. 
     37    @param fileposition:    position (optional) of file in filelist (of paths) 
     38    @param kwargs:    a subset request dictionary 
     39    @return:    dataArray, fillvalue, axisorder, units - array of data and ancilliary info. 
     40    ''' 
     41     
    3242    if csml.API.csmlContainer.globalContainer.OUTPUTDIR is not None: 
    3343        directory=csml.API.csmlContainer.globalContainer.OUTPUTDIR 
     
    99109         
    100110def getDataFromChunks(self, minIdx, maxIdx): 
    101     '''given a list of files of unknown length and an index range spanning some or all of those files, retuns the data from that index range. Only works with single dimensional data.''' 
     111    '''given a list of files of unknown length and an index range spanning some or all of those files, retuns the data from that index range. Only works with single dimensional data. 
     112    e.g. used for QXF 
     113    @param minIdx:   start index 
     114    @param maxIndex:    end index 
     115    @return:     dataarray, fillvalue     
     116    ''' 
    102117     
    103118    minIndex=minIdx 
     
    176191         
    177192def __calendar(file,timedim): 
    178     #open the file 
     193    ''' given a file and the name of the time dimension returns the name of the calendar and units used. eg 360day, days since 2001:01:01 
     194    @param file:   filepath 
     195    @param timedim:     name of time dimension 
     196    @return:    calendar name, calendar units 
     197    ''' 
    179198    DI = csmldataiface.DataInterface() 
    180199    DI=DI.getUnknownInterfaceType(file) 
  • TI02-CSML/trunk/csml/API/ops_GridFeature.py

    r1025 r3267  
    1 ''' ops_GridFeature  contains operations for GridFeatures''' 
     1''' ops_GridFeature  contains operations for GridFeatures. These methods are attached to GridFeature instances at runtime.''' 
    22 
    33def testmethod(self): 
     4    ''''testmethod for grid feature''' 
    45    print 'testmethod for grid feature' 
    56    return 'testmethod - grid' 
  • TI02-CSML/trunk/csml/API/ops_GridSeriesFeature.py

    r3226 r3267  
    1 ''' ops_GridSeriesFeature  contains operations for GridSeriesFeatures''' 
     1''' ops_GridSeriesFeature  contains operations for GridSeriesFeatures. These methods are attached to GridFeature instances at runtime.''' 
    22 
    33import csml.parser 
     
    1010import csmlutils 
    1111 
    12  
    13 import sys  #remove later 
    14  
    1512def testmethod(self): 
    16     #print 'testmethod for gridseries feature' 
     13    ''' testmethod for gridseries feature''' 
    1714    return 'testmethod - gridseries' 
    1815 
    1916def getAllowedSubsettings(self): 
     17    '''get the allowed operations 
     18    @return:    list of operations''' 
    2019    return ['subsetToGridSeries', 'subsetToProfileSeries']  #other operations 
    2120 
    2221 
    2322def getBoundingBox(self): 
     23    ''' get the simple boundingBox ''' 
    2424    try: 
    2525        lower1=eval(bbox.boundedBy.lowerCorner.CONTENT.split()[0]) 
     
    3333     
    3434def getDomain(self): 
    35     #returns domain as a dictionary of ordinates {name: [values], ...} 
     35    ''' get domain of the feature 
     36    @return:   domain as a dictionary of ordinates {name: [values], ...}''' 
    3637    self.domain={} 
    3738    self.gridnames={} 
     
    5657 
    5758def getNativeCRS(self): 
    58     #returns the crs of the feature 
     59    ''' get the the coordinate reference system of the domain of the feature 
     60    return:   a string, the srsName''' 
    5961    return self.value.gridSeriesDomain.srsName 
    6062 
    6163def getUom(self): 
     64    ''' get the uom of the phenomenon. 
     65    @return: string - uom attribute''' 
    6266    uom=None 
    63     #returns the uom of the phenomenon. 
    6467    try:  
    6568        uom=self.value.rangeSet.valueArray.valueComponent.quantityList.insertedExtract.uom.CONTENT 
     
    6972     
    7073def getDomainUnits(self): 
     74    ''' get the units used in the domain  
     75    @return:     list of units'''     
    7176    srsname=self.value.gridSeriesDomain.srsName 
    7277    cat=csml.csmllibs.csmlcrs.CRSCatalogue() 
     
    9297     
    9398def getLongitudeAxis(self): 
     99    ''' get the index of the longitude axis''' 
    94100    return self.__getAxis('lon') 
    95101 
    96102def getLatitudeAxis(self): 
     103    ''' get the index of the latitude axis''' 
    97104    return self.__getAxis('lat') 
    98105 
    99106def getTimeAxis(self): 
     107    ''' get the index of the time axis''' 
    100108    return self.__getAxis('time') 
    101109 
    102110def getAxisLabels(self): 
     111    '''get the names of the axes''' 
    103112    labels=[] 
    104113    for label in self.value.gridSeriesDomain.axisLabels.split(): 
     
    107116 
    108117def _subsetGrid(self, **kwargs): 
    109     '''this takes a selection from a gridseries object (be it a profile, a grid, whatever, it is still just a selection''' 
     118    '''this takes a selection from a gridseries object (be it a profile, a grid, whatever, it is still just a selection).  It is called internally  by the subsetToGridSeries method. 
     119    @return: a load of things which can then be used to rebuild a new csml feature: pathToSubsetNetCDF, crs, frame, timeName, times, strTimes, caltype, axisorder,units, fulldata, fillvalue, kwargs ''' 
    110120            
    111121    #set self.domain: 
     
    143153     
    144154def subsetToGridSeries(self, outputdir=None, ncname='gridseries.nc',**kwargs): 
    145     #perform the subset (note this included nearest neighbour searching, so may return a different set of kwargs 
     155    '''Subset a GridSeriesFeature to another smaller  GridSeriesFeature. Performs the subset (note this includes nearest neighbour searching, so may return a different set of kwargs 
     156    @param outputdir:    name of directory to write data files to 
     157    @param ncname:     name of netcdf file to write out 
     158    @param kwargs:      subset selection by axis name. 
     159    @return:     subsettedFeature (GridSeriesFeature instance)  pathToSubsetNetCDF (filepath), descriptor (array descriptor instance) 
     160     
     161    ''' 
    146162    if outputdir is not None: 
    147163        self.outputdir=outputdir 
     
    213229 
    214230def subsetToProfileSeries(self, outputdir=None, ncname='profileseries.nc',**kwargs): 
     231    '''Subset a GridSeriesFeature to a ProfileSeriesFeature. Performs the subset (note this includes nearest neighbour searching, so may return a different set of kwargs 
     232    @param outputdir:    name of directory to write data files to 
     233    @param ncname:     name of netcdf file to write out 
     234    @param kwargs:      subset selection by axis name. 
     235    @return:     subsettedFeature (ProfileSeriesFeature instance)  pathToSubsetNetCDF (filepath), descriptor (array descriptor instance)''' 
     236     
     237     
    215238    #TODO   !!!!!!!!! Need to perform some sort of testing on the kwargs to check it is a profileseries request. 
    216239    if outputdir is not None: 
     
    317340 
    318341def subsetToProfile(self, outputdir = None, ncname='profile.nc',**kwargs): 
    319     #Two step process - subset GridSeries to ProfileSeries, then ProfileSeries to Profile 
     342    '''Subset a GridSeriesFeature to a ProfileFeature. Performs the subset (note this includes nearest neighbour searching, so may return a different set of kwargs. 
     343         
     344        Is a two step process - subsets GridSeries to ProfileSeries, then ProfileSeries to Profile 
     345    @param outputdir:    name of directory to write data files to 
     346    @param ncname:     name of netcdf file to write out 
     347    @param kwargs:      subset selection by axis name. 
     348    @return:     subsettedFeature (ProfileFeature instance)  pathToSubsetNetCDF (filepath), descriptor (array descriptor instance)''' 
     349 
    320350    odir=outputdir 
    321351    profileSeries, pSfile, descriptor=self.subsetToProfileSeries(odir, ncname, **kwargs)    
     
    326356 
    327357def subsetToPointSeries(self, outputdir =None, ncname='pointseries.nc',**kwargs): 
    328     #Two step process - subset GridSeries to ProfileSeries, then ProfileSeries to PointSeries 
     358    '''Subset a GridSeriesFeature to a PointSeriesFeature. Performs the subset (note this includes nearest neighbour searching, so may return a different set of kwargs. 
     359         
     360        Is a two step process - subsets GridSeries to ProfileSeries, then ProfileSeries to PointSeries 
     361    @param outputdir:    name of directory to write data files to 
     362    @param ncname:     name of netcdf file to write out 
     363    @param kwargs:      subset selection by axis name. 
     364    @return:     subsettedFeature (PointSeriesFeature instance)  pathToSubsetNetCDF (filepath), descriptor (array descriptor instance)''' 
     365     
    329366    profileSeries, pSfile, descriptor =self.subsetToProfileSeries(outputdir, ncname, **kwargs)    
    330367    del kwargs['latitude']    #TODO - need to remove excess kwargs based on the domain of the temporary profileSeries feature 
Note: See TracChangeset for help on using the changeset viewer.