Changes between Initial Version and Version 1 of nappy/NappyAPI

13/10/10 13:11:53 (10 years ago)



  • nappy/NappyAPI

    v1 v1  
     1= The NAPpy API = 
     3The [source:ndg/nappy/trunk/] file is used for most interactions with nappy. The doc_string from that module is reproduced here: 
     5== The API == 
     7Top-level API module that allows user to access most of the useful stuff in nappy. API examples: 
     9 1. Working with NASA Ames file objects 
     10 2. Converting between formats (NASA Ames, NetCDF and CSV) 
     11 3. Comparing NASA Ames files (and/or CSV files) 
     12 4. General NASA Ames utilities 
     14=== 1. Working with NASA Ames file objects === 
     16# Start python interactive shell 
     17$ python 
     19# Import the nappy package 
     20import nappy 
     22# Let's open a NASA Ames file and examine its contents 
     23f = nappy.openNAFile("data_files/") 
     25# Get number of header lines 
     26n_lines = f.getNumHeaderLines() 
     28# Get Organisation from header 
     29org = f.getOrg() 
     30# Get the Normal Comments (SCOM) lines. 
     31norm_comms = f.getNormalComments() 
     33# Get the Special Comments (SCOM) lines. 
     34spec_comms = f.getSpecialComments() 
     36# Get a list of metadata for all main (non-auxiliary or independent) variables 
     37var_list = getVariables() 
     39# Get Auxiliary variable metadata for auxiliary variable number 2 
     40(variable, units, miss, scale) = f.getAuxVariable(2) 
     42# Get scale factor for primary variable number 3 
     43scale_factor = f.getScaleFactor(3) 
     45# Get missing value for primary variable number 1 
     46missing = f.getMissingValue(1) 
     48# Let's get the contents dictionary of the whole file 
     49na_dict = f.getNADict() 
     51# Let's write the na_dict object to a new NASA Ames file 
     52fout = openNAFile("test_outputs/", mode="w", na_dict=na_dict) 
     56=== 2. Converting between formats (NASA Ames, NetCDF and CSV) === 
     58# Let's convert a NASA Ames file into a NetCDF file, and add some of our own global attributes 
     59glob_atts = [("Project", "Really important scientific project involving worms"), 
     60             ("Errata": "I meant worm holes!")] 
     61na_file = "data_files/" 
     62nc_file = "test_outputs/" 
     63nappy.convertNAToNC(na_file, nc_file, global_attributes=glob_atts) 
     65# Let's convert a NASA Ames file to a CSV and add an annotation column to explain the header 
     66nappy.convertNAToCSV(na_file, annotation=True) 
     68# Let's read a NetCDF and write one (or more) output NASA Ames files, 
     69# but only including and variables "temp" and "ozone". Also let's write 
     70# the output using tabs as the delimiters and a float format of "%6.3f". 
     71nappy.convertNCToNA("data_files/", "test_outputs/", 
     72              var_ids=("temp", "ozone"), delimiter="\t", float_format="%6.3f") 
     74# Let's convert a NetCDF file to one (or more) CSV files and don't write the header at all 
     75nappy.convertNCToCSV("data_files/", "test_outputs/test1nc_no_header.csv", 
     76                     no_header=True) 
     78# Let's take some in-memory CDMS objects and write them to one, or more, NASA Ames file(s). 
     79# We need to give it a list of cdms variables and a global attributes list of tuples/lists. 
     80# We also want to instruct nappy to overwrite the content of its 
     81# MNAME (Mission Name) header line with our specific mission name. 
     82# Also, tell nappy to write the output to NASA Ames file format index (FFI) 2310 
     83# because we know it is compatible. 
     84nappy.convertCDMSObjectsToNA([cdms_var_1, cdms_var_2], [("Institute", "British Atmospheric Data Centre")], 
     85              na_file="test_outputs/", 
     86              na_items_to_override={"MNAME": "Atlantic Divergence Mission 2009"}, 
     87              requested_ffi=2310) 
     89# Let's take a list of cdms variables and a global attributes list and write 
     90# them to a CSV file. 
     91nappy.convertCDMSObjectsToCSV(cdms_vars, global_atttributes, csv_file) 
     93# Let's take a NASA Ames dictionary object, and write it to a NetCDF file 
     94nappy.writeNADictToNC(na_dict, nc_file, mode="w") 
     96# Let's try and write a second na_dict object to the same NetCDF file using mode="a". 
     97nappy.writeNADictToNC(na_dict_2, nc_file, mode="a") 
     99# Now let's read in a NASA Ames file and convert the contents in-memory into 
     100# CDMS objects so that we can manipulate them with NetCDF-compatible tools 
     101(cdms_vars_primary, cdms_vars_aux, global_attributes) = nappy.readCDMSObjectsFromNA(na_file) 
     103# Actually, I only want to get a single variable from that file, so I'll try 
     104temp_var = getCDMSVariableFromNA(na_file, "temperature") 
     106=== 3. Comparing NASA Ames files (and/or CSV files) === 
     108# I'd like to compare a NASA Ames and CSV file to check they are the same. 
     109# It will allow for different formatting of numbers as long as the values 
     110# are the same. Compare both header and body by setting as True (default). 
     111result = nappy.compareNA(na_file, csv_file, header=True, body=True, 
     112            number_clever=True, delimiter_1="    ", delimiter_2=",") 
     114=== 4. General NASA Ames utilities === 
     116# Get the FFI from a NASA Ames file 
     117ffi = nappy.readFFI(na_file) 
     119# Given a NASA Ames dictionary (na_dict) get an appropriate FFI. 
     120ffi = nappy.chooseFFI(na_dict)