spacepy.pycdf.istp

Support for ISTP-compliant CDFs

The ISTP metadata standard specifies the interpretation of the attributes in a CDF to describe relationships between the variables and their physical interpretation.

This module supports that subset of CDFs.

Authors: Jon Niehof

Additional Contributors: Lorna Ellis, Asher Merrill

Institution: University of New Hampshire

Contact: Jonathan.Niehof@unh.edu

Functions

fillval(v[, ret])	Set ISTP-compliant FILLVAL on a variable
format(v[, use_scaleminmax, dryrun])	Set ISTP-compliant FORMAT on a variable
nanfill(v)	Set fill values to NaN

Classes

FileChecks()	ISTP compliance checks for a CDF file.
VarBundle(source[, name])	Collective handling of ISTP-compliant variable and its dependencies.
VariableChecks()	ISTP compliance checks for a single variable.

spacepy.pycdf.istp.fillval(v, ret=False)

Set ISTP-compliant FILLVAL on a variable

Sets or returns a CDF variable’s FILLVAL attribute to the value required by ISTP (based on variable type).

Parameters:

vVar

CDF variable to update

Returns:

various

If ret is True, returns the correct value for variable type (which may be of various Python types). Otherwise sets the value and returns None.

Other Parameters:

retboolean

If True, return the value instead of setting it (Default False, set).

Examples

>>> import spacepy.pycdf
>>> import spacepy.pycdf.istp
>>> f = spacepy.pycdf.CDF('foo.cdf', create=True)
>>> v = f.new('Var', data=[1, 2, 3])
>>> spacepy.pycdf.istp.fillval(v)
>>> v.attrs['FILLVAL']
-128

spacepy.pycdf.istp.format(v, use_scaleminmax=False, dryrun=False)

Set ISTP-compliant FORMAT on a variable

Sets a CDF variable’s FORMAT attribute, which provides a Fortran-like format string that should be useable for printing any valid value in the variable. Sets according to the VALIDMIN/VALIDMAX attributes (or, optionally, SCALEMIN/SCALEMAX) if present, otherwise uses the full range of the type.

Parameters:

vVar

Variable to update

use_scaleminmaxbool, optional

Use SCALEMIN/MAX instead of VALIDMIN/MAX (default False). Note: istpchecks may complain about result.

dryrunbool, optional

Print the decided format to stdout instead of modifying the CDF (for use in command-line debugging) (default False).

Examples

>>> import spacepy.pycdf
>>> import spacepy.pycdf.istp
>>> f = spacepy.pycdf.CDF('foo.cdf', create=True)
>>> v = f.new('Var', data=[1, 2, 3])
>>> spacepy.pycdf.istp.format(v)
>>> v.attrs['FORMAT']
'I4'

spacepy.pycdf.istp.nanfill(v)

Set fill values to NaN

Finds all values which are equal to FILLVAL, greater than VALIDMAX, or less than VALIDMIN, and replace with NaN (not-a-number). This is an update-in-place operation; does not return a copy.

Assumes a single value for VALIDMIN, VALIDMAX, FILLVAL (although if the attribute is not present, will simply assume no restriction.)

Only applicable to floating-point types. Best applied to a VarCopy or dmarray rather than Var. Updating a variable in a CDF requires one write per changed value, and also will result in a CDF that is no longer ISTP compliant.

Because of floating-point comparison, the matching to FILLVAL may fail.

Parameters:

vVar or dmarray

CDF variable, data, or copy to update

Examples

>>> import spacepy.pycdf
>>> import spacepy.pycdf.istp
>>> f = spacepy.pycdf.CDF('foo.cdf', create=True)
>>> v = f.new('Var', data=[1, 2, 3, -1e31])
>>> spacepy.pycdf.istp.fillval(v)
>>> data = v.copy()
>>> data
VarCopy([1., 2., 3., -1.e31], dtype=float32)
>>> spacepy.pycdf.istp.nanfill(data)
>>> data
VarCopy([1., 2., 3., nan], dtype=float32)