Changes between Version 3 and Version 4 of nappy/NappyAPI


Ignore:
Timestamp:
04/03/13 14:57:40 (6 years ago)
Author:
astephen
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • nappy/NappyAPI

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