PyTables User's Guide: Hierarchical datasets in Python - Release 1.3.3
Prev | Chapter 7. NetCDF - a PyTables NetCDF3 emulation API | Next

# 7.3. tables.NetCDF module reference

## 7.3.1. Global constants

_fillvalue_dict

  Dictionary whose keys are `NetCDFVariable` single character typecodes and whose values are the netCDF _FillValue for that typecode.

ScientificIONetCDF_imported

  `True` if `Scientific.IO.NetCDF` is installed and can be imported.

## 7.3.2. The NetCDFFile class

NetCDFFile(filename, mode='r', history=None)

Opens an existing `tables.NetCDF` file (mode = `'r'` or `'a'`) or creates a new one (mode = `'w'`). The `history` keyword can be used to set the `NetCDFFile.history` global attribute (if mode = `'a'` or `'w'`).

A `NetCDFFile` object has two standard attributes: `dimensions` and `variables`. The values of both are dictionaries, mapping dimension names to their associated lengths and variable names to variables. All other attributes correspond to global attributes defined in a netCDF file. Global file attributes are created by assigning to an attribute of the `NetCDFFile` object.

### 7.3.2.1. NetCDFFile methods

close()

  Closes the file (after invoking the `sync` method).

sync()

  Synchronizes the size of variables along the unlimited dimension, by filling in data with default netCDF _FillValue. Returns the length of the unlimited dimension. Invoked automatically when the `NetCDFFile` object is closed.

ncattrs()

  Returns a list with the names of all currently defined netCDF global file attributes.

createDimension(name, length)

  Creates a netCDF dimension with a name given by the Python string `name` and a size given by the integer `size`. If `size = None`, the dimension is unlimited (i.e. it can grow dynamically). There can be only one unlimited dimension in a file.

createVariable(name, type, dimensions, least_significant_digit=None, expectedsize=10000, filters=None)

  Creates a new variable with the given `name, type, and dimensions`. The type is a one-letter Numeric typecode string which can be one of `f` (Float32), `d` (Float64), `i` (Int32), `l` (Int32), `s` (Int16), `c` (CharType - length 1), `F` (Complex32), `D` (Complex64) or `1` (Int8); the predefined type constants from Numeric can also be used. The `F` and `D` types are not supported in netCDF or Scientific.IO.NetCDF, if they are used in a `tables.NetCDF` file, that file cannot be converted to a true netCDF file nor can it be shared over the internet with OPeNDAP. Dimensions must be a tuple containing dimension names (strings) that have been defined previously by `createDimensions`. The `least_significant_digit` is the power of ten of the smallest decimal place in the variable's data that is a reliable value. If this keyword is specified, the variable's data truncated to this precision to improve compression. The `expectedsize` keyword can be used to set the expected number of entries along the unlimited dimension (default 10000). If you expect that your data with have an order of magnitude more or less than 10000 entries along the unlimited dimension, you may consider setting this keyword to improve efficiency (see section 5.1 for details). The `filters` keyword is a PyTables `Filters` instance that describes how to store the data on disk. The default corresponds to `complevel=6`, `complib='zlib'`, `shuffle=1` and `fletcher32=0`.

nctoh5(filename, unpackshort=True, filters=None)

  Imports the data in a netCDF version 3 file (`filename`) into a `NetCDFFile` object using `Scientific.IO.NetCDF` (`ScientificIONetCDF_imported` must be `True`). If `unpackshort=True`, data packed as short integers (type `s`) in the netCDF file will be unpacked to type `f` using the `scale_factor` and `add_offset` netCDF variable attributes. The `filters` keyword can be set to a PyTables `Filters` instance to change the default parameters used to compress the data in the `tables.NetCDF` file. The default corresponds to `complevel=6`, `complib='zlib'`, `shuffle=1` and `fletcher32=0`.

h5tonc(filename, packshort=False, scale_factor=None, add_offset=None)

  Exports the data in a `tables.NetCDF` file defined by the `NetCDFFile` instance into a netCDF version 3 file using `Scientific.IO.NetCDF` (`ScientificIONetCDF_imported` must be `True`). If `packshort=True>` the dictionaries `scale_factor` and `add_offset` are used to pack data of type `f` as short integers (of type `s`) in the netCDF file. Since netCDF version 3 does not provide automatic compression, packing as short integers is a commonly used way of saving disk space (see this page for more details). The keys of these dictionaries are the variable names to pack, the values are the scale_factors and offsets to use in the packing. The data are packed so that the original Float32 values can be reconstructed by multiplying the `scale_factor` and adding `add_offset`. The resulting netCDF file will have the `scale_factor` and `add_offset` variable attributes set appropriately.

## 7.3.3. The NetCDFVariable class

The `NetCDFVariable` constructor is not called explicitly, rather an `NetCDFVarible` instance is returned by an invocation of `NetCDFFile.createVariable`. `NetCDFVariable` objects behave like arrays, and have the standard attributes of arrays (such as `shape`). Data can be assigned or extracted from `NetCDFVariable` objects via slices.

### 7.3.3.1. NetCDFVariable methods

typecode()

  Returns a single character typecode describing the type of the variable, one of `f` (Float32), `d` (Float64), `i` (Int32), `l` (Int32), `s` (Int16), `c` (CharType - length 1), `F` (Complex32), `D` (Complex64) or `1` (Int8).

append(data)

  Append data to a variable along its unlimited dimension. The data you append must have either the same number of dimensions as the `NetCDFVariable`, or one less. The shape of the data you append must be the same as the `NetCDFVariable` for all of the dimensions except the unlimited dimension. The length of the data long the unlimited dimension controls how may entries along the unlimited dimension are appended. If the data you append has one fewer number of dimensions than the `NetCDFVariable`, it is assumed that you are appending one entry along the unlimited dimension. For variables without an unlimited dimension, data can simply be assigned to a slice without using the `append` method.

ncattrs()

  Returns a list with all the names of the currently defined netCDF variable attributes.

assignValue(data)

  Provided for compatiblity with `Scientific.IO.NetCDF`. Assigns data to the variable. If the variable has an unlimited dimension, it is equivalent to `append(data)`. If the variable has no unlimited dimension, it is equivalent to assigning data to the variable with the slice `[:]`.

getValue()

  Provided for compatiblity with `Scientific.IO.NetCDF`. Returns all the data in the variable. Equivalent to extracting the slice `[:]` from the variable.

Prev | Home | Next
Using the tables.NetCDF module | Up | Converting between true netCDF files and tables.NetCDF files