.. _geotable-py:

###########
geotable.py
###########

::

    >>> from simo.builder.modelbase.modelbase import ModelbaseDef
    >>> tdf = open('../../simulator/xml/schemas/Typedefs_SIMO.xsd')
    >>> typedef = tdf.read()
    >>> tdf.close()
    >>> sf = open('../../simulator/xml/schemas/geo_table.xsd')
    >>> schema = sf.read()
    >>> sf.close()
    >>> xml = u'''<geo_tables xmlns="http://www.simo-project.org/simo"
    ...     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    ...     <geo_table name="dem" desc="Digital elevation model">
    ...         <filename>test.latlonarray</filename>
    ...         <ulx>21.0</ulx>
    ...         <uly>61.0</uly>
    ...         <nrow>3</nrow>
    ...         <ncol>3</ncol>
    ...         <xdim>0.5</xdim>
    ...         <ydim>0.5</ydim>
    ...         <nvar>1</nvar>
    ...         <coordinate_variables>
    ...             <longitude>
    ...                 <variable>GEO_X</variable>
    ...                 <level>comp_unit</level>
    ...             </longitude>
    ...             <latitude>
    ...                 <variable>GEO_Y</variable>
    ...                 <level>comp_unit</level>
    ...             </latitude>
    ...         </coordinate_variables>
    ...         <targets>
    ...             <target>
    ...                 <variable>ALT</variable>
    ...                 <level>comp_unit</level>
    ...             </target>
    ...         </targets>
    ...     </geo_table>
    ... </geo_tables>
    ... '''
    
    >>> class Validator(object):
    ...     def add_error(msg):
    ...         print msg
    
    >>> class Lexicon(object):
    ...     def __init__(self):
    ...         self.models = {}
    ...     def get_variable_ind(self, level, variable, active=False):
    ...         if variable == 'GEO_X':
    ...             return (1,1)
    ...         elif variable == 'GEO_Y':
    ...             return (1,2)
    ...         elif variable == 'ALT':
    ...             return (1,3)
    ...         elif variable == 'TS':
    ...             return (1,4)
    ...     def get_level_ind(self, level):
    ...         return 1
    ...     def add_model(self, mtype, mname):
    ...         if mtype not in self.models:
    ...             self.models[mtype] = set()
    ...         self.models[mtype].add(mname)
    >>> mb = ModelbaseDef(typedef)
    >>> mb.schema = ('geo_table', schema)
    >>> mb.xml = ('testxml', xml, Lexicon(),
    ...           ['./builder/modelbase/test/data'], 'geo_table')
    >>> mb.xml['geo_table']['testxml'][:11]
    u'<geo_tables'


***********************
class GeoTable(object):
***********************

Values tied to a regular grid over the earth. Coordinates in decimal degrees.

Attributes:

- name
- filename: where the data for the table is
- ulx: upper left x-coordinate (longitude)
- uly: upper left y-coordinate (latitude)
- nrow: number of data rows (along y-coord)
- ncol: number of data colums (along x-coord)
- xdim: the grid step in x-direction
- ydim: the grid step in y-direction
- nvar: number of variables tied to each node in the grid
- longitude_var: data variable containing the longitude coordinate; dictionary with keys 'variable' and 'level' containing the variable and level indices for the data matrix
- latitude_var: data variable containing the latitude coordinate; dictionary with keys 'variable' and 'level' containing the variable and level indices for the data matrix
- targets: result variable definitions: a list of (levelindex, variale index) tuples
- arr: the actual data in a multidimensional array
- sim: the simulator instance using the table

def __init__(self, ns, root, validator):
========================================

Construct geo table from the parsed geo table xml::

    >>> gt = mb.obj['geo_table']['testxml']['dem']
    >>> gt.load_function(Validator())
    >>> gt.dirs
    ['./builder/modelbase/test/data']
    >>> gt.filename
    'test.latlonarray'
    >>> gt.type
    'geo_table'
    >>> gt.ulx
    21.0
    >>> gt.longitude_var
    (1, 1)
    >>> gt.latitude_var
    (1, 2)
    >>> # the array is 3*3, values from 100 to 108
    >>> gt.arr[0,2,0]
    108.0
    >>> gt.arr[2,0,0]
    100.0
    >>> gt.targets
    [(1, 3)]


def __get_coord_var(self, ns, celem):
=====================================

Coordinate variable definition to data matrix indices

def __read_geo_array(self):
===========================

Reads the geo array data from disk into a numpy array


****************************
class GeoTableParam(object):
****************************

Extracts geo table model parameters defined in the model chain

Attributes:

- get_all: boolean for returning all the variables found in the table
- result_variables: only a subset of table variables are returned: a list of:
   
   -  dictionary having keys 'variable' and 'level' having variable index and level index in the data matrix as values

def __init__(self, ns, elem, variable_ind, model):
==================================================

Constructs the geo table parameter definition object based on the XML element. If result variables are listed, validates the variables using passed the lexicon method instance.

Invalid result variables defined in model chain parameters::

    >>> execfile('builder/modelbase/test/mocktask.py')
    >>> from lxml import etree
    >>> from simo.builder.modelbase.geotable import GeoTableParam
    >>> pelem = etree.XML('''<geo_table>
    ...                           <only_vars>
    ...                              <var>
    ...                                 <name>TS</name>
    ...                                 <level>comp_unit</level>
    ...                              </var>
    ...                           </only_vars>
    ...                      </geo_table>''')
    >>> param = GeoTableParam('', pelem, task, gt)
    >>> task.validator.errors # doctest: +NORMALIZE_WHITESPACE
    set(["variable 'TS' at level 'comp_unit' is not a target variable for 
         geo table 'dem'"])