Python object representing a CDF file.
Open or create a CDF file by creating an object of this class.
Parameters: | pathname : string
masterpath : string
|
---|---|
Raises: | CDFError :
|
Warns: | CDFWarning :
|
Examples
>>> cdffile = pycdf.CDF('cdf_filename.cdf')
Be sure to close() or save() when done.
Note
Existing CDF files are opened read-only by default, see readonly() to change.
CDF supports the with keyword, like other file objects, so:
>>> with pycdf.CDF('cdf_filename.cdf') as cdffile:
... #do brilliant things with the CDF
will open the CDF, execute the indented statements, and close the CDF when finished or when an error occurs. The python docs include more detail on this ‘context manager’ ability.
CDF objects behave like a python dictionary, where the keys are names of variables in the CDF, and the values, Var objects. As a dictionary, they are also iterable and it is easy to loop over all of the variables in a file. Some examples:
- List the names of all variables in the open CDF cdffile:
>>> cdffile.keys()- Or:
>>> for k in cdffile: ... print(k)Get a Var object corresponding to the variable named Epoch:
>>> epoch = cdffile['Epoch']
- Determine if a CDF contains a variable named B_GSE:
>>> if 'B_GSE' in cdffile: ... print('B_GSE is in the file') ... else: ... print('B_GSE is not in the file')
- Find how many variables are in the file:
>>> print(len(cdffile))
- Delete the variable Epoch from the open CDF file cdffile:
>>> del cdffile['Epoch']
- Display a summary of variables and types in open CDF file cdffile:
>>> print(cdffile)Open the CDF named cdf_filename.cdf, read all the data from all variables into dictionary data, and close it when done or if an error occurs:
>>> with pycdf.CDF('cdf_filename.cdf') as cdffile: ... data = cdffile.copy()
This last example can be very inefficient as it reads the entire CDF. Normally it’s better to treat the CDF as a dictionary and access only the data needed, which will be pulled transparently from disc. See Var for more subtle examples.
The CDF user’s guide section 2.2 has more background information on CDF files.
The attrs Python attribute acts as a dictionary referencing CDF attributes (do not confuse the two); all the dictionary methods above also work on the attribute dictionary. See gAttrList for more on the dictionary of global attributes.
Creating a new CDF from a master (skeleton) CDF has similar syntax to opening one:
>>> cdffile = pycdf.CDF('cdf_filename.cdf', 'master_cdf_filename.cdf')
This creates and opens cdf_filename.cdf as a copy of master_cdf_filename.cdf.
Using a skeleton CDF is recommended over making a CDF entirely from scratch, but this is possible by specifying a blank master:
>>> cdffile = pycdf.CDF('cdf_filename.cdf', '')
When CDFs are created in this way, they are opened read-write, see readonly() to change.
By default, new CDFs (without a master) are created in version 2 (backward-compatible) format. To create a version 3 CDF, use Library.set_backward():
>>> pycdf.lib.set_backward(False)
>>> cdffile = pycdf.CDF('cdf_filename.cdf', '')
Add variables by direct assignment, which will automatically set type and dimension based on the data provided:
>>> cdffile['new_variable_name'] = [1, 2, 3, 4]
or, if more control is needed over the type and dimensions, use new().
attrs | Global attributes for this CDF in a dict-like format. |
CDF.backward | |
checksum([new_val]) | Set or check the checksum status of this CDF. |
clone(zVar[, name, data]) | Clone a zVariable (from another CDF or this) into this CDF |
close() | Closes the CDF file |
col_major([new_col]) | Finds the majority of this CDF file |
compress([comptype, param]) | Set or check the compression of this CDF |
copy() | Make a copy of all data and attributes in this CDF |
from_data(filename, sd) | Create a new CDF file from a SpaceData object or similar |
new(name[, data, type, recVary, dimVarys, ...]) | Create a new zVariable in this CDF |
raw_var(name) | Get a “raw” Var object. |
readonly([ro]) | Sets or check the readonly status of this CDF |
save() | Saves the CDF file but leaves it open. |
version() | Get version of library that created this CDF |
True if this CDF was created in backward-compatible mode (for opening with CDF library before 3.x)
Set or check the checksum status of this CDF. If checksums are enabled, the checksum will be verified every time the file is opened.
Returns: | out : boolean
|
---|---|
Other Parameters: | |
new_val : boolean
|
Clone a zVariable (from another CDF or this) into this CDF
Parameters: | zVar : Var
|
---|---|
Other Parameters: | |
name : str
data : boolean (optional)
|
Closes the CDF file
Although called on object destruction (__del__()), to ensure all data are saved, the user should explicitly call close() or save().
Raises: | CDFError : if CDF library reports an error |
---|---|
Warns: | CDFWarning : if CDF library reports a warning |
Finds the majority of this CDF file
Returns: | out : boolean
|
---|---|
Other Parameters: | |
new_col : boolean
|
Set or check the compression of this CDF
Sets compression on entire file, not per-variable.
See section 2.6 of the CDF user’s guide for more information on compression.
Returns: | out : tuple
|
---|---|
Other Parameters: | |
comptype : ctypes.c_long
param : ctypes.c_long
|
See also
Examples
>>> cdffile.compress(pycdf.const.GZIP_COMPRESSION, 9)
Make a copy of all data and attributes in this CDF
Returns: | out : CDFCopy
|
---|
Create a new CDF file from a SpaceData object or similar
The CDF named filename is created, opened, filled with the contents of sd (including attributes), and closed.
sd should be a dictionary-like object; each key will be made into a variable name. An attribute called attrs, if it exists, will be made into global attributes for the CDF.
Each value of sd should be array-like and will be used as the contents of the variable; an attribute called attrs, if it exists, will be made into attributes for that variable.
Parameters: | filename : string
sd : spacepy.datamodel.SpaceData
|
---|
Create a new zVariable in this CDF
Note
Either data or type must be specified. If type is not specified, it is guessed from data.
Parameters: | name : str
|
---|---|
Returns: | out : Var
|
Other Parameters: | |
data :
type : ctypes.c_long
recVary : boolean
dimVarys : list of boolean
dims : list of int
n_elements : int
compress : ctypes.c_long
compress_param : ctypes.c_long
|
|
Raises: | ValueError : if neither data nor sufficient typing information
|
Notes
Any given data may be representable by a range of CDF types; if the type is not specified, pycdf will guess which the CDF types which can represent this data. This breaks down to:
- If input data is a numpy array, match the type of that array
- Proper kind (numerical, string, time)
- Proper range (stores highest and lowest number provided)
- Sufficient resolution (EPOCH16 required if datetime has microseconds or below.)
If more than one value satisfies the requirements, types are returned in preferred order:
- Type that matches precision of data first, then
- integer type before float type, then
- Smallest type first, then
- signed type first, then
- specifically-named (CDF_BYTE) vs. generically named (CDF_INT1)
So for example, EPOCH_16 is preferred over EPOCH if data specifies below the millisecond level (rule 1), but otherwise EPOCH is preferred (rule 2).
This will switch to an eight-byte double in some cases where four bytes would be sufficient for IEEE 754 encoding, but where DEC formats would require eight.
Get a “raw” Var object.
Normally a Var will perform translation of values for certain types (to/from Unicode for CHAR variables on Py3k, and to/from datetime for all time types). A “raw” object does not perform this translation, on read or write.
This does not affect the data on disk, and in fact it is possible to maintain multiple Python objects with access to the same zVariable.
Parameters: | name : str
|
---|
Sets or check the readonly status of this CDF
If the CDF has been changed since opening, setting readonly mode will have no effect.
Returns: | out : Boolean
|
---|---|
Other Parameters: | |
ro : Boolean
|
|
Raises: | CDFError : if bad mode is set |
Saves the CDF file but leaves it open.
If closing the CDF, close() is sufficient; there is no need to call save() before close().
Note
Relies on an undocumented call of the CDF C library, which is also used in the Java interface.
Raises: | CDFError : if CDF library reports an error |
---|---|
Warns: | CDFWarning : if CDF library reports a warning |