netCDF3.Dataset

Module netCDF3 :: Class Dataset |

# Class Dataset

    object --+
             |
            Dataset

Known Subclasses:
  - MFDataset

Dataset(self, filename, mode="r", clobber=True, format='NETCDF3_64BIT')

A netCDF Dataset is a collection of dimensions, variables and attributes. Together they describe the meaning of data and relations among data fields stored in a netCDF file.

Parameters:

`filename` - Name of netCDF file to hold dataset.

Keywords:

`mode` - access mode. `r` means read-only; no data can be modified. `w` means write; a new file is created, an existing file with the same name is deleted. `a` and `r+` mean append (in analogy with serial files); an existing file is opened for reading and writing. Appending `s` to modes `w`, `r+` or `a` will enable unbuffered shared access. Unbuffered acesss may be useful even if you don't need shared access, since it may be faster for programs that don't access data sequentially.

`clobber` - if `True` (default), opening a file with `mode='w'` will clobber an existing file with the same name. if `False`, an exception will be raised if a file with the same name already exists.

`format` - underlying file format (either `'NETCDF3_64BIT'` or `'NETCDF3_CLASSIC'`. Only relevant if `mode = 'w'` (if `mode = 'r','a'` or `'r+'` the file format is automatically detected). Default `'NETCDF3_64BIT'` (the 64-bit offset version of the netCDF 3 file format, which fully supports 2+ GB files)). `'NETCDF3_CLASSIC'` is the classic netCDF 3 file format that does not handle 2+ Gb files very well.

Returns:

a Dataset instance. All further operations on the netCDF Dataset are accomplised via Dataset instance methods.

A list of attribute names corresponding to global netCDF attributes defined for the Dataset can be obtained with the ncattrs() method. These attributes can be created by assigning to an attribute of the Dataset instance. A dictionary containing all the netCDF attribute name/value pairs is provided by the `__dict__` attribute of a Dataset instance.

The instance variables `dimensions, variables, file_format` and `path` are read-only (and should not be modified by the user).

Instance Methods
__delattr__(...) x.__delattr__('name') <==> del x.name |
__getattr__(...) |
__getattribute__(...) x.__getattribute__('name') <==> x.name |
__init__(self, filename, mode="r", clobber=True, format='NETCDF3_64BIT') x.__init__(...) initializes x; see x.__class__.__doc__ for signature |
a new object with type S, a subtype of T |
__new__(T, S, ...) |
__setattr__(...) x.__setattr__('name', value) <==> x.name = value |
close(self) Close the Dataset. |
createDimension(self, dimname, size=None) Creates a new dimension with the given `dimname` and `size`. |
createVariable(self, varname, datatype, dimensions=(), fill_value=None) Creates a new variable with the given `varname`, `datatype`, and `dimensions`. |
delncattr(self, name, value) delete a netCDF dataset or group attribute. |
getncattr(self, name) retrievel a netCDF dataset attribute. |
ncattrs(self) return netCDF global attribute names for this Dataset in a list. |
renameDimension(self, oldname, newname) rename a Dimension named `oldname` to `newname`. |
renameVariable(self, oldname, newname) rename a Variable named `oldname` to `newname` |
set_fill_off(self) Sets the fill mode for a Dataset open for writing to `off`. |
set_fill_on(self) Sets the fill mode for a Dataset open for writing to `on`. |
setncattr(self, name, value) set a netCDF dataset attribute using name,value pair. |
sync(self) Writes all buffered data in the Dataset to the disk file. |
Inherited from `object`: `__format__`, `__hash__`, `__reduce__`, `__reduce_ex__`, `__repr__`, `__sizeof__`, `__str__`, `__subclasshook__`

Instance Variables
| dimensions The `dimensions` dictionary maps the names of dimensions defined for the Dataset to instances of the Dimension class.
| file_format The `file_format` attribute describes the netCDF file format version, either `NETCDF3_CLASSIC` or or `NETCDF3_64BIT`.
| variables The `variables` dictionary maps the names of variables defined for this Dataset to instances of the Variable class.

Properties
| maskanscale
Inherited from `object`: `__class__`

Method Details

### __delattr__(...) |
x.__delattr__('name') <==> del x.name Overrides: object.__delattr__

### __getattribute__(...) |
x.__getattribute__('name') <==> x.name Overrides: object.__getattribute__

### __init__(self, filename, mode="r", clobber=True, format='NETCDF3_64BIT') (Constructor) |
x.__init__(...) initializes x; see x.__class__.__doc__ for signature Overrides: object.__init__

### __new__(T, S, ...) |
Returns: a new object with type S, a subtype of T Overrides: object.__new__

### __setattr__(...) |
x.__setattr__('name', value) <==> x.name = value Overrides: object.__setattr__

### createDimension(self, dimname, size=None) |
Creates a new dimension with the given `dimname` and `size`. `size` must be a positive integer or `None`, which stands for "unlimited" (default is `None`). Specifying a size of 0 also results in an unlimited dimension. The return value is the Dimension class instance describing the new dimension. To determine the current maximum size of the dimension, use the `len` function on the Dimension instance. To determine if a dimension is 'unlimited', use the `isunlimited()` method of the Dimension instance.

### createVariable(self, varname, datatype, dimensions=(), fill_value=None) |
Creates a new variable with the given `varname`, `datatype`, and `dimensions`. If dimensions are not given, the variable is assumed to be a scalar. The `datatype` can be a numpy datatype object, or a string that describes a numpy dtype object (like the `dtype.str` attribue of a numpy array). Supported specifiers include: `'S1' or 'c' (NC_CHAR), 'i1' or 'b' or 'B' (NC_BYTE), 'i2' or 'h' or 's' (NC_SHORT), 'u2' (NC_USHORT), 'i4' or 'i' or 'l' (NC_INT), 'f4' or 'f' (NC_FLOAT), 'f8' or 'd' (NC_DOUBLE)`. Data from netCDF variables is presented to python as numpy arrays with the corresponding data type. `dimensions` must be a tuple containing dimension names (strings) that have been defined previously using `createDimension`. The default value is an empty tuple, which means the variable is a scalar. The optional keyword `fill_value` can be used to override the default netCDF `_FillValue` (the value that the variable gets filled with before any data is written to it). The return value is the Variable class instance describing the new variable. A list of names corresponding to netCDF variable attributes can be obtained with the Variable method `ncattrs()`. A dictionary containing all the netCDF attribute name/value pairs is provided by the `__dict__` attribute of a Variable instance. Variable instances behave much like array objects. Data can be assigned to or retrieved from a variable with indexing and slicing operations on the Variable instance. A Variable instance has four standard attributes: `dimensions, dtype, shape, ndim`. Application programs should never modify these attributes. The `dimensions` attribute is a tuple containing the names of the dimensions associated with this variable. The `dtype` attribute is a string describing the variable's data type (`i4, f8, S1,` etc). The `shape` attribute is a tuple describing the current sizes of all the variable's dimensions. The `ndim` attribute is the number of variable dimensions.

### delncattr(self, name, value) |
delete a netCDF dataset or group attribute. Only use if you need to delete a netCDF attribute with the same name as one of the reserved python attributes.

### getncattr(self, name) |
retrievel a netCDF dataset attribute. Only use if you need to set a netCDF attribute with the same name as one of the reserved python attributes.

### set_fill_off(self) |
Sets the fill mode for a Dataset open for writing to `off`. This will prevent the data from being pre-filled with fill values, which may result in some performance improvements. However, you must then make sure the data is actually written before being read.

### set_fill_on(self) |
Sets the fill mode for a Dataset open for writing to `on`. This causes data to be pre-filled with fill values. The fill values can be controlled by the variable's `_Fill_Value` attribute, but is usually sufficient to the use the netCDF default `_Fill_Value` (defined separately for each variable type). The default behavior of the netCDF library correspongs to `set_fill_on`. Data which are equal to the `_Fill_Value` indicate that the variable was created, but never written to.

### setncattr(self, name, value) |
set a netCDF dataset attribute using name,value pair. Only use if you need to set a netCDF attribute with the same name as one of the reserved python attributes.