{{{
#!python
#!/usr/bin/env python 
#		use "env" command to make sure you use the right python interpreter
# -*- coding: utf-8 -*-
#		allows usage of non-ASCII characters in scripts


# Add general information below

'''
FILENAME:
    ncreader.py

DESCRIPTION:
    Introduction to various python objects
    Python Seminar 13.09.2012

Sample ncfile "../Nio/sresa1b_ncar_ccsm3_0_run1_200001.nc

'''

# for python objects naming conventions and style see PEP8:
#  http://www.python.org/dev/peps/pep-0008/

# If you use this file as a importable module for other programs than
# the information below is useful to describe 
__author__ = "A. U. Thor"
__version__ = "0.0"
__date__ = "0000/00/00"


import sys
import os
from optparse import OptionParser
import Nio
import numpy as np
import matplotlib.pyplot as plt
import pdb
import cPickle as cP



# below is a simple class that provides some convenience functions
class NcReader:
	
	''' As an example, this particular Class is basically 
		a set of convenience functions that are meant 
		to speed up some of your routine work with NetCDF files '''
	
	def __init__(self, file_path):
		''' Initialize object '''
		self.fpath  = file_path
		self.ncfile = Nio.open_file(self.fpath)
		self.variables = self.ncfile.variables
	
	def printVars(self):
		''' prints variables dictionary ''' 
		for i in self.variables: 
			print i
	
	def plotVar(self, var_name):
		''' plots single 1d variable '''
		variable = self.ncfile.variables[var_name][:]
		plt.plot(variable)
		plt.show()
		
	def plot2dVar(self, *args, **kwargs):
		'''plots multiple 2d variables '''
		
		# args is a tuple
		# kwargs is a keyworded dictionary
		
		for i in args:
			try:
				var = self.variables[i]
				print var[:].shape
				plt.imshow(self.variables[i][0,:])
			except:
				raise #KeyError("variable %s not found" %i)
			
			if kwargs['colorbar'] == True:
				plt.colorbar()	
			plt.show()
			

# "parse_options" is meant to parse command line arguments and options
# there can be unknown number of arguments, but options are predefined
# mandatory arguments are actually options

def parse_options():
    
    ''' Parse command line options and arguments '''

    usage = "usage: %prog [options] <input_files>";
    version = "%prog 0.1"
    parser = OptionParser(usage)
    
    parser.add_option("-d", "--pdb_switch", dest = 'pdb_switch',
                       action = "store_true", default = "False")
    parser.add_option("-i", "--input_file", dest = 'input_file')
						
    (options, args) = parser.parse_args()
    
    return (options, args)


# It is a good practice to separate code execution and objects like classes
# and functions
# Main function is used for executing python code as a standalone program
#  
def main():

    options, arguments = parse_options()

    input_file = options.input_file
    
    variables = arguments[:]
    
    a = NcReader(input_file)
    a.printVars()
    
    # keyworded arguments - normally used as options for fuctions
    # non keyworded arguments - just arguments
    a.plotVar('plev')
    a.plot2dVar(*variables, colorbar = True)
    
    # debugger?
    pdb_switch = options.pdb_switch


# The following structure is useful if 
# the code to be run as a standalone program AND a module which 
# can be imported in other python scripts
if __name__ == "__main__":
    main()
}}}