mcidasv/mcidasv — pull request #86 by mhiley (2014-01-15 16:19:47+00:00)
Title: initial commit of loadFile [1589]

Basic loadFile usage example:
====================

```python
# create the request in a similar way as getADDEImage
parms = dict(
filename = '/Users/mhiley/eastarw.t12z.awp4km09.tm00.grib2',
time = 0, # time index
level = 50000.0, # level in Pa
field = 'Relative_humidity_isobaric',
)

# get a “mega-object” containing the relative humidity grid and some metadata.
relative_humidity = loadFile(**parms)

# print all the keys in the dictionary to see what metadata is available
print relative_humidity.keys()

# can access metadata as with data objects returned by getADDEImage
print relative_humidity[‘description’]

# run createLayer
layer = activeDisplay().createLayer('Color-Shaded Plan View', relative_humidity)
```

Here is the file used in the example (please try throwing your own data at it though):
====================

ftp://ftp.ssec.wisc.edu/pub/ssec/eastarw.t12z.awp4km09.tm00.grib2

However, the current code doesn’t deal with much beyond the simple case. Here is an initial to-do list:
====================

- Multiple time step/loop functionality still needs much development…

- createLayer needs some work because much of the code there is specific to getADDEImage. As a result, %timestamp% macro isn't working, and it probably won’t handle time sequence yet.

- Time step can only be specified by index…user can’t specify by actual date/time

- Handling of vertical level needs a lot of testing…implementation seems very fragile…also should be able to handle different units (e.g. user should be able to specify in both Pa or hPa as desired)

- Still need to implement ‘binary’ method in GeoGridFlatField and _MappedGeoGridFlatField so you get a mega-object back after doing arithmetic on a data object

- My testing so far is specific to the basic case of a file containing 3D model grids. Haven’t put any thought into e.g. ensemble model grids yet, or other special cases we might need to deal with.

- error handling and code documentation

- Implement convenience functions: list time steps, list grid names, list levels…

- implement ‘subset’ keyword

- “field” param must be specified as the “Short name” - e.g. “Temperature_isobaric” instead of “Temperature @ Isobaric surface” (which is what actually shows up in Field Selector. Note, you can mouse over the field name in the Field Selector to see the “short name”.

Implementation details…
====================

Mostly bypasses IDV DataChoice, etc. stuff (analogous to getADDEImage implementation). Use GeoGridAdapter class to get a GeoGridFlatField which can then be made into a _MappedGeoGridFlatField ‘mega-object’.

GeoGridAdapter constructor does require a valid DataSource. I was worried about creating a new data source for every call to loadFile, but it appears IDV magically avoids creating multiple identical data sources… so this is apparently a non-issue.