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.
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')
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()
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)
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()
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']
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)
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()
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')
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)
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')
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."
Sometimes you will want to explicitly flush all netCDF file modifications to disk. This is done with the sync() function.
NetCDFFile.sync()
file.sync()
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.
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'
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()
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 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
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[:]
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
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"
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)
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".