Document Actions

CHAPTER 2

by Renata McCoy — last modified 2006-03-21 16:34


	Contents	Previous	Next

CHAPTER 2 CDMS Python Application Programming Interface

2.1 Overview

This chapter describes the CDMS Python application programming interface (API). Python is a popular public-domain, object-oriented language. Its features include support for object-oriented development, a rich set of programming constructs, and an extensible architecture. CDMS itself is implemented in a mixture of C and Python. In this chapter the assumption is made that the reader is familiar with the basic features of the Python language.

Python supports the notion of a module, which groups together associated classes and methods. The import command makes the module accessible to an application. This chapter documents the cdms, cdtime, and regrid modules.

The chapter sections correspond to the CDMS classes. Each section contains tables base. If no parent, the datapath is absolute.describing the class internal (non-persistent) attributes, constructors (functions for creating an object), and class methods (functions). A method can return an instance of a CDMS class, or one of the Python types:

Table 2.1 Python types used in CDMS

Type	Description
Array	Numeric or masked multidimensional data array. All elements of the array are of the same type. Defined in the Numeric and MA modules.
Comptime	Absolute time value, a time with representation (year, month, day, hour, minute, second). Defined in the cdtime module. cf. reltime
Dictionary	An unordered 2,3collection of objects, indexed by key. All dictionaries in CDMS are indexed by strings, e.g.:
	axes['time']
Float	Floating-point value.
Integer	Integer value.
List	An ordered sequence of objects, which need not be of the same type. New members can be inserted or appended. Lists are denoted with square brackets, e.g.,
	[1, 2.0, 'x', 'y']
None	No value returned.
Reltime	Relative time value, a time with representation (value, units since basetime). Defined in the cdtime module. cf. comptime
Tuple	An ordered sequence of objects, which need not be of the same type. Unlike lists, tuples elements cannot be inserted or appended. Tuples are denoted with parentheses, e.g.,
	(1, 2.0, 'x', 'y')

2.2 A first example

The following Python script reads January and July monthly temperature data from an input dataset, averages over time, and writes the results to an output file. The input temperature data is ordered (time, latitude, longitude).

1 #!/usr/bin/env python
2 import cdms
3 from cdms import MV
4 jones = cdms.open('/pcmdi/cdms/obs/jones_mo.nc')
5 tasvar = jones['tas']
6 jans = tasvar[0::12]
7 julys = tasvar[6::12]
8 janavg = MV.average(jans)
9 janavg.id = "tas_jan"
10 janavg.long_name = "mean January surface temperature"
11 julyavg = MV.average(julys)
12 julyavg.id = "tas_jul"
13 julyavg.long_name = "mean July surface temperature"
14 out = cdms.open('janjuly.nc','w')
15 out.write(janavg)
16 out.write(julyavg)
17 out.comment = "Average January/July from Jones dataset"
18 jones.close()
19 out.close()

Line	Notes
2,3	Makes the CDMS and MV modules available. MV defines arithmetic functions.
4	Opens a netCDF file read-only. The result jones is a dataset object.
5	Gets the surface air temperature variable. 'tas' is the name of the variable in the input dataset. This does not actually read the data.
6	Read all January monthly mean data into a variable jans. Variables can be sliced like arrays. The slice operator [0::12] means take every 12th slice from dimension 0, starting at index 0 and ending at the last index. If the stride 12 were omitted, it would default to 1. Note that the variable is actually 3-dimensional. Since no slice is specified for the second or third dimensions, all values of those2,3 dimensions are retrieved. The slice operation could also have been written [0::12, : , :]. Also note that the same script works for multi-file datasets. CDMS opens the needed data files, extracts the appropriate slices, and concatenates them into the result array.
7	Reads all July data into a masked array julys.
8	Calculate the average January value for each grid zone. Any missing data is handled automatically.
9,10	Set the variable id and long_name attributes. The id is used as the name of the variable when plotted or written to a file.
14	Create a new netCDF output file named 'janjuly.nc' to hold the results.
15	Write the January average values to the output file. The variable will have id "tas_jan" in the file. write is a utility function which creates the variable in the file, then writes data to the variable. A more general method of data output is first to create a variable, then set a slice of the variable. Note that janavg and julavg have the same latitude and longitude information as tasvar. It is carried along with the computations.
17	Set the global attribute 'comment'.
18	Close the output file.

2.3 cdms module

The cdms module is the Python interface to CDMS. The objects and methods in this chapter are made accessible with the command:

import cdms

The functions described in this section are not associated with a class. Rather, they are called as module functions, e.g.,

file = cdms.open('sample.nc')

Table 2.2 cdms module functions

Type	Definition
Variable	asVariable(s)
	Transform s into a transient variable.
	s is a masked array, Numeric array, or Variable. If s is already a transient variable, s is returned.
	See also: isVariable.
Axis	createAxis(data, bounds=None)
	Create a one-dimensional coordinate Axis, which is not associated with a file or dataset. This is useful for creating a grid which is not contained in a file or dataset.
	data is a one-dimensional, monotonic Numeric array.
	bounds is an array of shape (len(data),2), such that for all i, data[i] is in the range [bounds[i,0],bounds[i,1] ]. If bounds is not specified, the default boundaries are generated at the midpoints between the consecutive data values, provided that the autobounds mode is 'on' (the default). See setAutoBounds.
	Also see: CdmsFile.createAxis

Axis	createEqualAreaAxis(nlat) Create an equal-area latitude axis. The latitude values range from north to south, and for all axis values x[i], sin(x[i])sin(x[i+1]) is constant. nlat is the axis length. The axis is not associated with a file or dataset.
Axis	createGaussianAxis(nlat) Create a Gaussian latitude axis. Axis values range from north to south. nlat is the axis length. The axis is not associated with a file or dataset.
RectGrid	createGaussianGrid(nlats, xorigin=0.0, order="yx") Create a Gaussian grid, with shape (nlats, 2nlats). nlats* is the number of latitudes. xorigin is the origin of the longitude axis. order is either “yx” (lat-lon, default) or “xy” (lon-lat)
RectGrid	createGenericGrid(latArray, lonArray, latBounds=None, lonBounds=None, order="yx", mask=None) Create a generic grid, that is, a grid which is not typed as Gaussian, uniform, or equal-area. The grid is not associated with a file or dataset. latArray is a NumPy array of latitude values. lonArray is a NumPy array of longitude values latBounds is a NumPy array having shape (len(latArray),2), of latitude boundaries. lonBounds is a NumPy array having shape (len(lonArray),2), of longitude boundaries. order is a string specifying the order of the axes, either "yx" for (latitude, longitude), or "xy" for the reverse. mask (optional) is an integer-valued NumPy mask array, hav- ing the same shape and ordering as the grid.
RectGrid	createGlobalMeanGrid(grid) Generate a grid for calculating the global mean via a regridding operation. The return grid is a single zone covering the range of the input grid. grid is a RectGrid.
RectGrid	createRectGrid(lat, lon, order, type="generic", mask=None) Create a rectilinear grid, not associated with a file or dataset. This might be used as the target grid for a regridding opera- tion. lat is a latitude axis, created by cdms.createAxis. lon is a longitude axis, created by cdms.createAxis. order is a string with value "yx" (the first grid dimension is latitude) or "xy" (the first grid dimension is longitude). type is one of 'gaussian','uniform','equalarea',or 'generic'. If specified, mask is a two-dimensional, logical Numeric array (all values are zero or one) with the same shape as the grid.
RectGrid	createUniformGrid(startLat, nlat, deltaLat, start-Lon, nlon, deltaLon, order="yx", mask=None) Create a uniform rectilinear grid. The grid is not associated with a file or dataset. The grid boundaries are at the midpoints of the axis values. startLat is the starting latitude value. nlat is the number of latitudes. If nlat is 1, the grid latitude boundaries will be startLat +/- deltaLat/2. deltaLat is the increment between latitudes. startLon is the starting longitude value. nlon is the number of longitudes. If nlon is 1, the grid longitude boundaries will be startLon +/-deltaLon/2. deltaLon is the increment between longitudes. order is a string with value "y"x (the first grid dimension is latitude) or "xy" (the first grid dimension is longitude). . If specified, mask is a two-dimensional, logical Numeric array (all values are zero or one) with the same shape as the grid.

Axis	createUniformLatitudeAxis(startLat, nlat, deltaLat)
	Create a uniform latitude axis. The axis boundaries are at the midpoints of the axis values. The axis is designated as a circular latitude axis.
	startLat is the starting latitude value.
	nlat is the number of latitudes.
	deltaLat is the increment between latitudes.
RectGrid	createZonalGrid(grid)
	Create a zonal grid. The output grid has the same latitude as the input grid, and a single longitude. This may be used to calculate zonal averages via a regridding operation.
	grid is a RectGrid.
Axis	createUniformLongitudeAxis(startLon, nlon, delta-Lon)
	Create a uniform longitude axis. The axis boundaries are at the midpoints of the axis values. The axis is designated as a circular longitude axis.
	startLon is the starting longitude value.
	nlon is the number of longitudes.
	deltaLon is the increment between longitudes.
Variable	createVariable(array, typecode=None, copy=0, savespace=0, mask=None, fill_value=None, grid=None, axes=None, attributes=None, id=None)
	This function is documented in Table 2.34 on page 90.
Integer	getAutoBounds()
	Get the current autobounds mode. Returns 0, 1, or 2. See setAutoBounds.

Integer	isVariable(s)
	Return 1 if s is a variable, 0 otherwise. See also: asVariable.
Dataset or CdmsFile	open(url,mode='r') Open or create a Dataset or CdmsFile. url is a Uniform Resource Locator, referring to a cdunif or XML file. If the URL has the extension '.xml' or '.cdml', a Dataset is returned, otherwise a CdmsFile is returned. If the URL protocol is 'http', the file must be a '.xml' or '.cdml' file, and the mode must be 'r'. If the protocal is 'file' or is omitted, a local file or dataset is open
	mode is the open mode. See Table 2.24 on page 70.
	Example: Open an existing dataset:
	f = cdms.open("sampleset.xml")
	Example: Create a netCDF file:
	f = cdms.open("newfile.nc",'w')
List	order2index (axes, orderstring)
	Find the index permutation of axes to match order. Return a list of indices
	axes is a list of axis objects.
	orderstring is defined as in orderparse.
List	orderparse(orderstring) Parse an order string. Returns a list of axes specifiers. orderstring consists of: etters t, x, y, z meaning time, longitude, latitude, level Numbers 0-9 representing position in axes Dash (-) meaning insert the next available axis here. The ellipsis ... meaning fill these positions with any remaining axes. (name) meaning an axis whose id is name
None	setAutoBounds(mode) Set autobounds mode. In some circumstances CDMS can generate boundaries for 1-D axes and rectilinear grids, when the bounds are not explicitly defined. The autoBounds mode determines how this is done: If mode is 'grid' or 2 (the default), the getBounds method will automatically generate boundary information for an axis or grid if the axis is designated as a latitude or longitude axis, and the boundaries are not explicitly defined. If mode is 'on' or 1, the getBounds method will automatically generate boundary information for an axis or grid, if the boundaries are not explicitly defined. If mode is 'off' or 0, and no boundary data is explicitly defined, the bounds will NOT be generated; the getBounds method will return None for the boundaries. Note: In versions of CDMS prior to V4.0, the default mode was 'on'.
None	setClassifyGrids(mode) Set the grid classification mode. This affects how grid type is determined, for the purpose of generating grid boundaries. If mode is 'on' (the default), grid type is determined by a grid classification method, regardless of the value of grid.get-Type(). If mode is 'off', the value of grid.getType() determines the grid type
None	writeScripGrid(path, grid, gridTitle=None) Write a grid to a SCRIP grid file. path is a string, the path of the SCRIP file to be created. grid is a CDMS grid object. It may be rectangular. gridTitle is a string ID for the grid.

Table 2.3 Class Tags

Tag Class

'axis'	Axis
'database'	Database
'dataset'	Dataset, CdmsFile
'grid'	RectGrid
'variable'	Variable
'xlink'	Xlink

2.4 CdmsObj

A CdmsObj is the base class for all CDMS database objects. At the application level, CdmsObj objects are never created and used directly. Rather the subclasses of CdmsObj (Dataset, Variable, Axis, etc.) are the basis of user application programming.

All objects derived from CdmsObj have a special attribute .attributes. This is a Python dictionary, which contains all the external (persistent) attributes associated with the object. This is in contrast to the internal, non-persistent attributes of an object, which are built-in and predefined. When a CDMS object is written to a file, the external attributes are written, but not the internal attributes.

Example: get a list of all external attributes of obj.

extatts = obj.attributes.keys()

Table 2.4 Attributes common to all CDMS objects

Type Name Definition

Dictionary

attributes

External attribute dictionary for this object.'

Table 2.5 Getting and setting attributes

Type Definition

various value = obj.attname

Get an internal or external attribute value. If the attribute is external, it is read from the database. If the attribute is not already in the database, it is created as an external attribute. Internal attributes cannot be created, only referenced.

obj.attname = value

Set an internal or external attribute value. If the attribute is external, it is written to the database.

2.5 CoordinateAxis

A CoordinateAxis is a variable that represents coordinate information. It may be contained in a file or dataset, or may be transient (memoryresident). Setting a slice of a file CoordinateAxis writes to the file, and referencing a file CoordinateAxis slice reads data from the file. Axis objects are also used to define the domain of a Variable.

CDMS defines several different types of CoordinateAxis objects. Table 2.9 on page 45 documents methods that are common to all CoordinateAxis types. Table 2.10 on page 48 specifies methods that are unique to 1D Axis objects.

Table 2.6 CoordinateAxis types

Type	Definition
CoordinateAxis	A variable that represents coordinate information. Has subtypes Axis2D and AuxAxis1D.
Axis	A one-dimensional coordinate axis whose values are strictly monotonic. Has subtypes DatasetAxis, FileAxis, and TransientAxis. May be an index axis, mapping a range of integers to the equivalent floating point value. If a latitude or longitude axis, may be associated with a RectGrid.
Axis2D	A two-dimensional coordinate axis, typically a latitude or longitude axis related to a CurvilinearGrid. Has subtypes DatasetAxis2D, FileAxis2D, and TransientAxis2D.
AuxAxis1D	A one-dimensional coordinate axis whose values need not be monotonic. Typically a latitude or longitude axis associated with a GenericGrid. Has subtypes DatasetAuxAxis1D, FileAuxAxis1D, and TransientAuxAxis1D.

An axis in a CdmsFile may be designated the unlimited axis, meaning that it can be extended in length after the initial definition. There can be at most one unlimited axis associated with a CdmsFile.

Table 2.7 CoordinateAxis Internal Attributes

Type	Name	Definition
Dictionary	attributes	External attribute dictionary.
String	id	CoordinateAxis identifer.
Dataset	parent	The dataset which contains the variable.
Tuple	shape	The length of each axis.

Table 2.8 Axis Constructors

cdms.createAxis(data, bounds=None)
Create an axis which is not associated with a dataset or file. See Table 2.2 on page 33.

Dataset.createAxis(name,ar)
Create an Axis in a Dataset. (This function is not yet implemented. )

CdmsFile.createAxis(name,ar,unlimited=0)
Create an Axis in a CdmsFile.
name is the string name of the Axis.
ar is a 1-D data array which defines the Axis values. It may have the value
None if an unlimited axis is being defined.

At most one Axis in a CdmsFile may be designated as being unlimited, meaning that it may be extended in length. To define an axis as unlimited, either:

set ar to None, and leave unlimited undefined, or
set ar to the initial 1-D array, and set unlimited to cdms.Unlimited

cdms.createEqualAreaAxis(nlat)
See Table 2.2 on page 33.

cdms.createGaussianAxis(nlat)
See Table 2.2 on page 18.

cdms.createUniformLatitudeAxis(startlat, nlat, deltalat)
See Table 2.2 on page 18.

cdms.createUniformLongitudeAxis(startlon, nlon, deltalon)
See Table 2.2 on page 18.

Table 2.9 CoordinateAxis Methods

Type	Method Definition
Array	array = axis[ i:j]
	Read a slice of data from the external file or dataset. Data is returned in the physical ordering defined in the dataset. See Table 2.11 on page 51 for a description of slice operators.
None	axis[ i:j] = array
	Write a slice of data to the external file. Dataset axes are read-only.
None	assignValue(array) Set the entire value of the axis.
	array is a Numeric array, of the same dimensionality as the axis.
Axis	clone(copyData=1) Return a copy of the axis, as a transient axis. If copyData is 1 (the default) the data itself is copied.
None	designateLatitude(persistent=0): Designate the axis to be a latitude axis. If persistent is true, the external file or dataset (if any) is modified. By default, the designation is temporary.
None	designateLevel(persistent=0) Designate the axis to be a vertical level axis. If persistent is true, the external file or dataset (if any) is modified. By default, the designation is temporary.
None	designateLongitude(persistent=0, modulo=360.0) Designate the axis to be a longitude axis. modulo is the modulus value. Any given axis value x is treated as equivalent to x+modulus If persistent is true, the external file or dataset (if any) is modified. By default, the designation is temporary.
None	designateTime(persistent=0, calendar = cdtime.MixedCalendar) Designate the axis to be a time axis. If persistent is true, the external file or dataset (if any) is modified. By default, the designation is temporary. calendar is defined as in getCalendar().
Array	getBounds() Get the associated boundary array. The shape of the return array depends on the type of axis: Axis: (n,2) Axis2D: (i,j,4) AuxAxis1D: (ncell, nvert) where nvert is

PCMDI Software Portal

Sections

Personal tools

Document Actions

CHAPTER 2