NetCDF Interface to Python

This page attempts to document the netCDF interface to Python.  It is assumed that the reader knows something
about the Python language, or at least the Python definitions of the terms: list, tuple, and attribute.  If not, you are
encouraged to take the Python tutorial which may be found at www.python.org.

The following documentation presents examples in the form of code snippets for each of the known interface
functions to netCDF.  They have been tested in my environment, but be warned.  The Numeric Python
(NumPy) package which includes the netCDF interface is not included in the standard python package.  NumPy
must be downloaded and installed as a separate package before these examples will work.   Click here to get more
information about Numeric Python.

This document is written from a netCDF perspective and so is intended for those who have experience in netCDF. It is organized similarly to the netCDF User's Guide, so that most experienced netCDF users will be able to better comprehend it.  Since some of the functions are from the netCDF interface classes, others are from vanilla Numeric Python, and the rest are generic Python it will you to understand the basics of Python and Numeric Python before you use the Python netCDF interface. The collection comprises a nearly complete set of functions that nearly emulates the standard netCDF interface.  Again if you are not familiar with Python, you are encourage to take the Python tutorial  and/or the Numeric Python Tutorial.  You'll be glad you did!

First Things First

Before you begin, you must have Python and Numeric Python installed on your system.  The links above will
help you find information on how to download these packages.  Once you have installed these packages, you
will need to import the Python netCDF interface in your source with the line:

import Scientific.IO.NetCDF

from Numeric import *
from NetCDF import *

If you have any problems getting Python to recognize the NetCDF module such as:

Traceback (most recent call last):
  File "<stdin>", line 1, in ?
ImportError: No module named NetCDF

try this line instead...

from Scientific.IO import NetCDF

This should give you access to all of the netCDF interface functions.

Sample Program

So that you can see how to perform the various netCDF operations in a Python program, here is a sample program that contains examples of nearly all of the function documented here.  After you configure your environment for Python, you should get this program to run correctly first, before trying something on your own.
 

The netCDF Interface  -  NetCDFFile Operations

The following sections document how to accomplish the basic netCDF operations in Python.  Each section is color coded as follows:

  • Blue text describes the function.
  • Red text defines the function and its parameters.
  • Black text is a small snippet of code that shows you how the call looks in a Python program.


  • Create / Open a netCDF file

    To create a netCDF file from python, you simply call the NetCDFFile constructor.  This is also the method used to open an existing netCDF file.  The object returned is of type NetCDFFile and all future access must be done through this object.  There is no explicit need to put the file in "define mode".  If the file is open for write access ('w' or 'a'), you may write any type of new data including new dimensions, variables and attributes.

    NetCDFFile(filename, mode)
         filename - name of the netCDF file as a string
         mode - "r" - (read_only)
                       "w" - (read_write)
                       "a" - open existing file or create new one if it does not yet exist for write

    file = NetCDFFile(filename, 'w')


    Close a netCDF file

    Closing the netCDF file is accomplished via the close function defined for the NetCDFFile object.  When close() is called, all modified data is written out to the disk file.

    file.close()



    Create a netCDF dimension

    NetCDF defines the sizes of all variables in terms of dimensions, so before any variables can be created the dimensions they use must be created first.

    NetCDFFile.createDimension(dimName, size)
        dimName  -  Python string - e.g. 'nLevels'
        size -  integer value

    dimName = 'numLevels'
    size = 12
    file.createDimension(dimName, size)
     



    Get all of the dimension names for a netCDF file

    Getting all of the dimension names is accomplished by getting all of the entries in the dimensions Python dictionary. Note that this returns the names of all of the dimensions of the netCDF file in a Python list.  These names are the elements of the Python dimensions tuple used when creating a variable.

    NetCDFFile.dimensions.keys()

    allDimNames = file.dimensions.keys()
     



    Get the value of a netCDF dimension

    Getting the value of a netCDF dimension is done via the dimensions dictionary.  Note that for some reason getting the current value of the UNLIMITED dimension does not work with this method.  The value returned in this case is "None".  However, you can always get the current value of any variable dimension via the shape attribute.

    dimValue = NetCDFFile.dimensions['dimName']
        dimName - name of a netCDF dimension as a Python string

    dimValue = file.dimensions['myDim']
     



    Create a netCDF variable

    Virtually all data in a netCDF file is stored in a netCDF variable (except for global attributes).  Here's how a netCDF variable is created in Python.  Note that the NetCDFFile object must have been created with the 'w' or 'a' mode.  Also note that calling this function returns a netCDF variable object which can be used later to access variable data and attributes.

    NetCDFFile.createVariable(varName, datatype, dimensions)
        varName  - name of the variable
        datatype  -  type of the variable.  Most common types are:
                            'f'  - float
                            'd'  - double precision float
                            'i' or 'l' - int or long
                            'c' - character
                            'b' - byte

    tempDims = ('dim1', 'dim2', )       # Note that this is a Python tuple
    netCDFVar = file.createVariable('temp', 'f', tempDims)
     



    Get all variable names for a netCDF file

    Getting all of the variable names is done much the same way as getting all of the dimension names.  Note that this function returns the names of all of the netCDF variables of the NetCDFFile in a Python list.

    NetCDFFile.variables.keys()

    variableNames = file.variables.keys()
     



    Create a netCDF global attribute

    Creating a netCDF global attribute is a little different than creating dimensions or attributes.  A generic python function is called instead of a function specific to the netCDF interface.

    setattr(NetCDFFile, attributeName, attributeValue)
        NetCDFFile - NetCDFFile object returned from the function NetCDFFile()
        attribute name - a Python string  e.g., 'myGlobalAtt'
        attributeValue - the value of the attribute

    setattr(file, 'globalAtt', 'attValue')
     



    Get all global attributes for a netCDF file

    Retrieving the names of the every global attribute defined in a NetCDFFile is done with the "dir()" Python function. Note that this call returns a Python list containing all of the currently defined global attributes.  Also be aware that because of the way Python works, this list will also contain the function names available for the NetCDFFile object which includes following entries: 'close', 'createDimension', 'createVariable', 'flush', 'sync'.  WARNING:  If you define a global attribute whose name matches one of the aforementioned entries, an error will occur when trying to call the function of the same name.  So, never name your global attributes one of these entries.

    dir(NetCDFFile)
        NetCDFFile is the NetCDFFile object created with the NetCDFFile constructor.

    globalAttList = dir(file)



    Get the value of a global attribute

    To get the value of a global attribute, use the getattt() function.  This same function works for variable attributes too.

    globalAttValue = getattr(file, globalAttName)
        file - NetCDFFile object returned from the function NetCDFFile()
        globalAttName  - name of the global attribute

    globalAttValue = getattr(file, 'globalAttName')
     



    Inquire whether a global attribute exists

    To check to see whether a particular global attribute exists, use the Python hasattr() function. Note that this function returns a boolean and is generally used in an "if" statement.

    NetCDFFile.hasattr(globalAttName)
        globalAttName  - name of the global attribute

    attName = 'myGlobalAttName'
    if hasattr(file, attName):
        print attName, "exists in this netCDF file."
     



    Flush all data to disk

    Sometimes you will want to explicitly flush all netCDF file modifications to disk.  This is done with the sync() function.

    NetCDFFile.sync()

    file.sync()
     



    NetCDF Variable Operations

    This sections describes the operations that you can perform on NetCDFile variables including: writing data, reading data, getting the dimensions of a variable, as well as creating , defining and reading variable attributes.



    Get a netCDF variable object

    In order to access netCDF variable data and attributes, you must first get the Python netCDF variable object. This is accomplished by accessing the NetCDFFile variable dictionary.

    NetCDFFile.variables[varName']
        varName - name of the netCDF variable as a Python string

    var = file.variables['temp']   # Returns the variable named 'temp'
     



    Get the data type of a netCDF variable

    Sometimes the type of a netCDF variable is needed.  The typecode() function was made for this purpose. See the section on creating netCDF varaibles for the translation between typecodes and datatypes.

    typecode = NetCDFVariable.typecode()
        typecode = a character value that represents the type of the netCDF variable.

    typechar = var.typecode()
     



    Get the "shape" of a netCDF variable

    Numeric Python has a concept of a "shape" of a Numeric array.  This is a tuple of dimension values that define the size of the netCDF variable.  Probably the easiest way to get the size of a netCDF variable is to get its shape, which is returned as a Python tuple.  Note that "shape" is an attribute of the variable object and not a function call, so no parentheses are required.

    varShape = NetCDFVariable.shape

    varShape = var.shape
     



    Assigning values to a netCDF variable

    Assigning the value to a netCDF variable uses the Numeric Python interface, which is simple, but not always intuitive.  The assignment is generally done by setting the netCDFVariable object to another Numeric Python array of the same shape.  Note that if the array on the right side of the assignment does not have the same shape as the netCDF variable, no values will be assigned at all.  As it turns out there are at least two ways to assign values to netCDF variables.

    NetCDFVariable[:] = data
        data - a Numeric Python array of the same shape as the variable

    data = zeros(var.shape)   #  Make a Numeric array of zeros with the same shape as var
    var[:] = data                       #  Store the array of zeros in the netCDF variable

    There's another method to store values in a netCDF variable that uses the assignValue function. Again the value in the assignValue call must have the same shape as the netCDF variable.

    data = zeros(var.shape)   #  Make a Numeric array of zeros with the same shape as var
    var.assignValue(data)      #  Store the array of zeros in the netCDF variable
     



    Get values of a netCDF variable

    Getting the values of a netCDF variable is done with the getValue() function.  Note that the values are deposited in a Numeric Python array.  Just like assigning values, there are two ways to get the values of a netCDF variable.

    NumericArray = var.getValue()
        NumericArray - a Numeric Python array object

    data = var.getValue()   # the entire contents of var is now stored and accessible in the Numeric Python array object: data

    The other way to get values for a netCDF variable is to use Numeric Python syntax.  See the Numeric Python documentation for lots of information on Numeric Python array objects.

    data = NetCDFVariable[:]
        data - a Numeric Python array object just like the one above

    data = var[:]
     



    Get the dimension names of a netCDF variable

    Getting the dimension names for a netCDF variable works just like getting dimension name for a NetCDF file.  Since "dimensions" is an attribute, no parentheses are needed.

    dimNames = NetCDFVariable.dimensions

    dimNames = var.dimensions   #  Returns a Python typle of dimension names for this variable
     
     



    Create a netCDF variable attribute

    You can create netCDF variable attributes via the Python setattr() function. Note that the functions "getValue", "assignValue", and "typecode" are treated as attributes in Python, so NEVER make variable attribute names that conflict with any of these function names.

    setattr(NetCDFVariable, attName, attValue)
        NetCDFVariable = a netCDFVariable object
        attName - the name of the attribute
        attValue - the value of the attribute

    attName = "newAtt"
    attValue = "newAttValue"
    setattr(var, attName, attValue)    #  creates a new variable attribute with name = "newAtt" and value = "newAttValue"
     



    Get the value of a netCDF variable attribute

    To get the value of a netCDFVariable attribute use the getattr() function.

    attData = getattr(NetCDFVariable, attName)
        attData - value of the attribute
        NetCDFVariable = a netCDFVariable object
        attName - the name of the attribute

    attName = "newAtt"
    attData = getattr(var,  attName)
     



    Get a list of all netCDF variable attributes

    Getting the entire list of attributes for a netCDF variable is just like getting all of the global attributes for a NetCDFFile. The dir function returns a list of attribute names. WARNING:  This list will always include the entries: "assignValue", "getValue", "typecode".

    attList = dir(NetCDFVariable)

    attList = dir(var)  #  attList contains all of the attributes for "var" and the entries: "assignValue", "getValue", "typecode".