wiki:nappy/NappyAPI

Version 1 (modified by astephen, 10 years ago) (diff)

--

The NAPpy API

The ndg/nappy/trunk/nappy_api.py file is used for most interactions with nappy. The doc_string from that module is reproduced here:

The API

Top-level API module that allows user to access most of the useful stuff in nappy. API examples:

  1. Working with NASA Ames file objects
  2. Converting between formats (NASA Ames, NetCDF and CSV)
  3. Comparing NASA Ames files (and/or CSV files)
  4. General NASA Ames utilities

1. Working with NASA Ames file objects

# Start python interactive shell $ python

# Import the nappy package import nappy

# Let's open a NASA Ames file and examine its contents f = nappy.openNAFile("data_files/2010.na")

# Get number of header lines n_lines = f.getNumHeaderLines()

# Get Organisation from header org = f.getOrg() # Get the Normal Comments (SCOM) lines. norm_comms = f.getNormalComments()

# Get the Special Comments (SCOM) lines. spec_comms = f.getSpecialComments()

# Get a list of metadata for all main (non-auxiliary or independent) variables var_list = getVariables()

# Get Auxiliary variable metadata for auxiliary variable number 2 (variable, units, miss, scale) = f.getAuxVariable(2)

# Get scale factor for primary variable number 3 scale_factor = f.getScaleFactor(3)

# Get missing value for primary variable number 1 missing = f.getMissingValue(1)

# Let's get the contents dictionary of the whole file na_dict = f.getNADict()

# Let's write the na_dict object to a new NASA Ames file fout = openNAFile("test_outputs/mytest.na", mode="w", na_dict=na_dict) fout.write() fout.close()

2. Converting between formats (NASA Ames, NetCDF and CSV)

# Let's convert a NASA Ames file into a NetCDF file, and add some of our own global attributes glob_atts = [("Project", "Really important scientific project involving worms"),

("Errata": "I meant worm holes!")]

na_file = "data_files/1020.na" nc_file = "test_outputs/try_1020.nc" nappy.convertNAToNC(na_file, nc_file, global_attributes=glob_atts)

# Let's convert a NASA Ames file to a CSV and add an annotation column to explain the header nappy.convertNAToCSV(na_file, annotation=True)

# Let's read a NetCDF and write one (or more) output NASA Ames files, # but only including and variables "temp" and "ozone". Also let's write # the output using tabs as the delimiters and a float format of "%6.3f". nappy.convertNCToNA("data_files/test1.nc", "test_outputs/test1nc.na",

var_ids=("temp", "ozone"), delimiter="\t", float_format="%6.3f")

# Let's convert a NetCDF file to one (or more) CSV files and don't write the header at all nappy.convertNCToCSV("data_files/test1.nc", "test_outputs/test1nc_no_header.csv",

no_header=True)

# Let's take some in-memory CDMS objects and write them to one, or more, NASA Ames file(s). # We need to give it a list of cdms variables and a global attributes list of tuples/lists. # We also want to instruct nappy to overwrite the content of its # MNAME (Mission Name) header line with our specific mission name. # Also, tell nappy to write the output to NASA Ames file format index (FFI) 2310 # because we know it is compatible. nappy.convertCDMSObjectsToNA([cdms_var_1, cdms_var_2], [("Institute", "British Atmospheric Data Centre")],

na_file="test_outputs/cdms_to_na.na", na_items_to_override={"MNAME": "Atlantic Divergence Mission 2009"}, requested_ffi=2310)

# Let's take a list of cdms variables and a global attributes list and write # them to a CSV file. nappy.convertCDMSObjectsToCSV(cdms_vars, global_atttributes, csv_file)

# Let's take a NASA Ames dictionary object, and write it to a NetCDF file nappy.writeNADictToNC(na_dict, nc_file, mode="w")

# Let's try and write a second na_dict object to the same NetCDF file using mode="a". nappy.writeNADictToNC(na_dict_2, nc_file, mode="a")

# Now let's read in a NASA Ames file and convert the contents in-memory into # CDMS objects so that we can manipulate them with NetCDF-compatible tools (cdms_vars_primary, cdms_vars_aux, global_attributes) = nappy.readCDMSObjectsFromNA(na_file)

# Actually, I only want to get a single variable from that file, so I'll try temp_var = getCDMSVariableFromNA(na_file, "temperature")

3. Comparing NASA Ames files (and/or CSV files)

# I'd like to compare a NASA Ames and CSV file to check they are the same. # It will allow for different formatting of numbers as long as the values # are the same. Compare both header and body by setting as True (default). result = nappy.compareNA(na_file, csv_file, header=True, body=True,

number_clever=True, delimiter_1=" ", delimiter_2=",")

4. General NASA Ames utilities

# Get the FFI from a NASA Ames file ffi = nappy.readFFI(na_file)

# Given a NASA Ames dictionary (na_dict) get an appropriate FFI. ffi = nappy.chooseFFI(na_dict)