wiki:nappy/NappyAPI

Version 2 (modified by astephen, 9 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)