ESA.util.otool_ncfile_io		index
/home/lfeng/otool/ESA/util/otool_ncfile_io.py

module for file IO. It contains codes for reading and writing netcdf files;
 
    Authors: L. Feng, Edinburgh University
    History: v0.9, 2012.05.18
    History: v0.95, 2013.02.15
    
 
Classes:
=============================================================
1. ncfile_desc_cl: class for ncfile access
 
 
 
Functions:
==============================================================
1. ncf_read: read variables into arrays  from netcdf file.
2. ncf_write: create a netcdf file, and write variables into it.
3. ncf_write_byvar: create a netcdf file, and write variables given 
---as a list of class io_var_cl. 
4. ncf_dims_def_byvar: create a netcdf file, and define dimensions 
---using a list of io_var_cl.
5. ncf_dims_add_byvar: add dimensions using a list of io_var_cl 
---to a netcdf file. 
6. ncf_dims_def:  create a netcdf file, and define dimensions.
7. ncf_data_write: write data into a netcdf file.
8. ncf_save_var: save var into a netcdf file.
9. ncf_data_write: write data into a netcdf file. 
10. ncf_save_var: save var into a netcdf file.

 
Modules
       
ESA.util.message_m
numpy
ESA.util.otool_obj
ESA.util.otool_var_io
Scientific.IO.NetCDF

 
Classes
       
ncfile_desc_cl

 
class ncfile_desc_cl
    class for netcdf file access
 
Members:
-----------------------------------------------
1. mask_val:<float>: filling for bad or missing data
2. var_lst:<list, t:str>: list of var to be read 
3. varname_dict:<dict>: translation between  name in netcdf file and name in the code. 
4. varname_lst:<list>: list of var name
 
 
5. read_to_array:<T/F>: if ture, data will be read from file as array (full loaded), otherwise
--- data will be just stored as pointer
 
6. nread:<obj>: number of vars, or the file handle 
7. attr_dict:<dict>: attribute dictionarys
8. grd:<ctm_grd_cl>: grid 
10. ref:<int/str>: value to identify the object
11. flnm:<str>: filename format
12. path:<str>: path format
13. full_flnm:<str>: the actual file name 
 
 
Functions
--------------------------------------------
1.  __init__: initialization
2. read_var_from_file: read var into the class 
3. append_var: append var to the var list of the class
 
4. get_lon: get longitude if existing 
5. get_lat: get latitude if existing 
6. get_time: get time if existing 
7. get_data: get var data 
8. get_var: get var
 
9. set_file_path:  set path for data file
 
10. set_filename_format: set template for filename 
 
11. construct_filename: make file name 
12. get_attr: get attribute
13. set_attr: set attribute
14. close_file: close file 
15. set_grid: set grid 
 
 
 
Attributes (reserved words)
-----------------------------------------------------------
1. flnm: <str>: full file name 
2. filepath:  <str>: path of the file name 
3. flnmformat:  <str>: template for filename
 
  Methods defined here:
__getitem__(self, index)
overide []
Inputs:
-------------------------------
1. index:<str/int>: var name or the index in the var_lst 
 
Returns:
----------------------------
1. gvar:<io_var_lst>: variable for given name or index
__init__(self, flnm='', ref=0, path='', var_lst=[], varname_dict={}, mask_val=-999.0, read_to_array=True, fio_keywords={}, **keywords)
read txt table files into var and return a record table
 
Inputs:
-----------------------------------------
1. flnm:<str>: filename 
2. datapath:<str>: data path for the file 
 
3. var_lst:<list, t:io_var_cl_>:list of var to be read
4. varnames_dict:<dict>:translation between default var name and name 
in netcdf file
3. mask_val:<float>: filling for bad or missing data
5. read_to_array:<T/F>: if ture, the data will be fully read and 
--- converted into numpy array 
6. fio_keywords:<dict>: extra inputs for file I/O
 
7. keywords:<dict>: attributes
append_var(self, var)
append var to the var_lst of the class
 
Inputs:
----------------------------------------
1. var:<io_var_cl>: variable
close_file(self)
close file if necessary
construct_filename(self, **keywords)
construction file name use the keywords
get_attr(self, attr_name)
get one attribute
Inputs:
------------------------------------------------
    1. name:<str>: attribute name
Returns:
-----------------------------------------------
    1. val: <obj>: attribute value
get_data(self, varname)
get value
 
Inputs:
----------------------------------------
1. varname:<str>: name of variable
 
Returns:
-----------------------------
1. data:<array/obj>: data of the variable
get_grid(self)
get the grid 
Returns:
---------------------------------------------
1. self.grd:<ctm_grid_cl>: grid
get_lat(self, varname='lat')
get latitude
 
Inputs:
----------------------------------------
1. varname:<str>: name of variable latitude 
 
Returns:
-----------------------------
1. data:<array/obj>: latitude
get_lon(self, varname='lon')
get longitude 
Inputs:
----------------------------------------
1. varname:<str>: name of variable longitude 
 
Returns:
-----------------------------
1. data:<array/obj>: longitude
get_time(self, varname='time')
get time 
 
Inputs:
----------------------------------------
1. varname:<str>: name of variable time 
 
Returns:
-----------------------------
1. data:<array/obj>: time
get_var(self, varname)
check the var 
 
Inputs:
-------------------------------
1. varname:<str>: var name 
 
Returns:
----------------------------
1. gvar:<io_var_lst>: variable for given name or index
read_var_from_file(self, flnm='')
read txt table files into var and return a record table
 
Inputs:
-----------------------------------------
1. flnm:<str>: file name 
 
2. var_lst:<list, t:io_var_cl_>:list of var to be read
 
Returns:
-----------------------------------------
1. nread:<int>:number of variables been read. 
 
Notes:
1.
set_attr(self, attr_name, value)
assign one attribute to axis
 
Inputs:
-------------------------------------------------------
1. attr_name: <str>: attribute name
2. value: <obj>:attribute value
set_file_path(self, path)
set path for data file 
 
Inputs:
----------------------------------------
1. path:<str>: file path
set_filename(self, flnm)
set path for data file 
 
Inputs:
----------------------------------------
1. flnm:<str>: file name
set_filename_format(self, flnm_format)
set template for filename 
 
Inputs:
---------------------------
1. flnm_format:<str>: file name
set_grid(self, grd)
setup the grid for the var

 
Functions
       
ncf_data_write(filename, dimNames, varName, varType, varData, varattr=None)
Write variable into netcdf file
 
Inputs:
--------------------------------------
1. filename:<str>: netcdf file name
2. dimNames:<list, t:str>: name of the var dimension
3. varName:<str>: name of the var
4. varData:<array,>: data 
5. varType:<str>: type of the data 
6. varattr:<dict>: attributes
ncf_dims_add_byvar(filename, var_lst)
Add dimensions from list of var 
Inputs:
------------------------------------
1. filename:<str>: name of netCDF file 
2. var_list:<list, t:io_var_cl>: list of geos_var
ncf_dims_def(filename, dimNames, dimTypes, dimVars)
Define dimensions into a netcdf file 
 
 
Inputs:
--------------------------------------------------------------
1. ncflnm:<str>: file name 
2. dimNames:<list, t:str>: dimension name 
3. dimTypes:<list, t:str>:dimension type 
4. dimvars:<list, t:array>:dimension data
ncf_dims_def_byvar(filename, var_lst)
Create dimensions from list of var 
Inputs:
------------------------------------
1. filename:<str>: name of netCDF file 
2. var_list:<list, t:io_var_cl>: list of geos_var
ncf_get_attr(ncflnm, varname, attrname)
read variables into arrays from a netcdf file 
Inputs:
------------------------------------------------
1. ncflnm:<str>: file name.
2. varname:<str>: var name to be read.
3. attrname:<str>: attribute name 
 
Returns:
-----------------------------------------
1. attr_val:<obj>: attribute of variable 
 
Notes:
1. if varname=='', global attribute will be seek
ncf_read(ncflnm, varnames)
read variables into arrays from a netcdf file 
Inputs:
------------------------------------------------
1. ncflnm:<str>: file name.
2. varnames:<list, t:str>: var name to be read.
 
Returns:
-----------------------------------------------
1. outvars:<list, t:array>: list of the variables read from netcdf file.
ncf_read_glb_attr(ncflnm, attr_name)
Inputs:
------------------------------------------------
1. ncflnm:<str>: file name.
2. attr_name:<str>: global attribute name .
 
Returns:
-----------------------------------
1. attr_val:<obj>: global attributes
ncf_read_var(ncflnm, var_lst, to_array=True)
read variables into var list from a netcdf file 
 
Inputs:
------------------------------------------------
1. ncflnm:<str>: file name.
2. var_lst:<list, t:str>: var name to be read.
 
Returns:
-----------------------------------------------
1. nread:<obj>: 
---if to_array=True, nread will be the number of read
---if to_array=False, nread will be the filehandle
ncf_save_var(ncflnm, var_lst, dim_lst=None, create_new=False, glb_attr=None)
save var info a file 
Inputs:
-------------------------------------------------------
1. ncflnm:<str>: file name 
2. var_lst:<list, t:io_var_cl>: datas
3. dim_lst:<list, t:io_var_cl>: dimensions
4. create_new:<T/F>: True if a new file will be created
5. glb_attr:<dict>: global attributes
ncf_set_glb_attr(ncflnm, glb_attr)
Inputs:
------------------------------------------------
1. ncflnm:<str>: file name.
2. glb_attr:<dict>: global attributes.
ncf_write(ncflnm, dimNames, dimTypes, dimVars, varNames, varTypes, varDatas)
write data into a netcdf file 
Inputs:
--------------------------------------------------------------
1. ncflnm:<str>: file name 
2. dimNames:<list, t:str>: dimension name 
3. dimTypes:<list, t:str>:dimension type 
4. dimvars:<list, t:array>:dimension data
 
5. varNames:<list, t:str>: var name
6. varTypes:<list, t:str>:var type
7. varDatas:<list, t:array>: data
ncf_write_byvar(ncflnm, dimNames, dimTypes, dimVars, varinfos)
write data contained by io_var_cl into a netcdf file 
 
Inputs:
--------------------------------------------------------------
1. ncflnm:<str>: file name 
2. dimNames:<list, t:str>: dimension name 
3. dimTypes:<list, t:str>:dimension type 
4. dimvars:<list, t:array>:dimension data
 
5. varinfos:<list, t:geos_info>: list of vars