or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

cdf-reading.mdcdf-writing.mdepochs.mdindex.mdxarray-integration.md
tile.json

tessl/pypi-cdflib

A Python CDF reader toolkit for reading and writing CDF files without requiring NASA CDF library installation

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/cdflib@1.3.x

To install, run

npx @tessl/cli install tessl/pypi-cdflib@1.3.0

index.mddocs/

cdflib

A Python CDF reader toolkit for reading and writing CDF (Common Data Format) files without requiring NASA CDF library installation. This package provides comprehensive functionality for accessing scientific data stored in CDF format commonly used in space physics and earth sciences, with support for reading CDF metadata, variables, and attributes through a simple Python API.

Package Information

  • Package Name: cdflib
  • Language: Python
  • Installation: pip install cdflib
  • Requirements: Python >= 3.9, numpy >= 1.21

Core Imports

import cdflib

Reading CDF files:

from cdflib import CDF

Time epoch handling:

from cdflib import cdfepoch

XArray integration (optional):

from cdflib.xarray import cdf_to_xarray, xarray_to_cdf

Basic Usage

Reading CDF Files

import cdflib

# Open a CDF file
cdf_file = cdflib.CDF('/path/to/file.cdf')

# Get file information
info = cdf_file.cdf_info()
print(f"Variables: {info['zVariables']}")

# Read variable data
data = cdf_file.varget('VariableName')
print(data)

# Read with record range
subset = cdf_file.varget('VariableName', startrec=0, endrec=100)

# Get variable attributes
attrs = cdf_file.varattsget('VariableName')
print(attrs)

# Get global attributes
global_attrs = cdf_file.globalattsget()

Writing CDF Files

import cdflib
import numpy as np

# Create a new CDF file
cdf = cdflib.cdfwrite.CDF('/path/to/output.cdf')

# Write global attributes
cdf.write_globalattrs({'Title': 'My Dataset', 'Version': '1.0'})

# Define and write a variable
var_spec = {
    'Variable': 'temperature',
    'Data_Type': cdf.CDF_REAL4,
    'Num_Elements': 1,
    'Dims': []
}
var_data = np.array([20.5, 21.0, 19.8, 22.1])
cdf.write_var(var_spec, var_data=var_data)

# Close the file
cdf.close()

Time Epoch Conversion

import cdflib

# Convert date components to CDF epoch
epoch = cdflib.cdfepoch.compute_epoch([2023, 1, 1, 12, 0, 0, 0])

# Convert CDF epoch to human-readable string
time_str = cdflib.cdfepoch.encode_epoch(epoch)
print(time_str)  # "01-Jan-2023 12:00:00.000"

# Convert to Unix timestamp
unix_time = cdflib.cdfepoch.unixtime(epoch)

# Convert Unix timestamp back to CDF epoch
new_epoch = cdflib.cdfepoch.timestamp_to_cdfepoch(unix_time)

Architecture

cdflib follows a modular design with clear separation of concerns:

  • CDF Reader: File parsing, metadata extraction, and data reading with support for local files, URLs, and S3 buckets
  • CDF Writer: File creation, metadata writing, and data serialization with compression support
  • Epoch System: Comprehensive time handling for three CDF epoch formats (CDF_EPOCH, CDF_EPOCH16, TT2000)
  • XArray Integration: Seamless conversion between CDF files and xarray Datasets with ISTP compliance
  • Data Classes: Structured containers for CDF metadata and file information

The library supports multiple data sources (local files, HTTP/HTTPS URLs, S3 buckets) and provides extensive time format conversion capabilities essential for scientific data analysis.

Capabilities

CDF File Reading

Complete API for reading CDF files including metadata extraction, variable data access, and attribute retrieval. Supports local files, URLs, and S3 buckets with optional validation and custom string encoding.

class CDF:
    def __init__(self, path, validate=False, string_encoding='ascii', s3_read_method=1): ...
    def cdf_info(self): ...
    def varget(self, variable, epoch=None, startrec=0, endrec=None): ...
    def varinq(self, variable): ...
    def attget(self, attribute, entry=None): ...
    def globalattsget(self): ...
    def varattsget(self, variable): ...

CDF Reading

CDF File Writing

Complete API for creating and writing CDF files with support for global attributes, variable definitions, data writing, and file-level compression.

class CDF:
    def __init__(self, path, cdf_spec=None): ...
    def write_globalattrs(self, globalAttrs): ...
    def write_variableattrs(self, variableAttrs): ...
    def write_var(self, var_spec, var_attrs=None, var_data=None): ...
    def close(self): ...

CDF Writing

Time Epoch Conversion

Comprehensive time handling system supporting all three CDF epoch formats with conversion between CDF epochs, Unix timestamps, numpy datetime64, and human-readable strings.

class CDFepoch:
    @staticmethod
    def compute_epoch(dates): ...
    @staticmethod
    def encode_epoch(epochs, iso_8601=True): ...
    @staticmethod
    def breakdown_epoch(epochs): ...
    @staticmethod
    def unixtime(cdf_time): ...
    @staticmethod
    def timestamp_to_cdfepoch(unixtime_data): ...

Epochs

XArray Integration

Seamless conversion between CDF files and xarray Datasets with ISTP (International Solar-Terrestrial Physics) compliance checking and automatic metadata handling.

def cdf_to_xarray(filename, to_datetime=True, to_unixtime=False, fillval_to_nan=False): ...
def xarray_to_cdf(dataset, file_name, ...): ...

XArray Integration

Core Types

# Data classes for CDF metadata
class CDFInfo:
    """General CDF file information"""
    
class VDRInfo:
    """Variable descriptor record information"""
    
class ADRInfo:
    """Attribute descriptor record information"""
    
class AttData:
    """Attribute data container"""

# CDF data type constants (for cdfwrite)
CDF_INT1 = 1
CDF_INT2 = 2  
CDF_INT4 = 4
CDF_INT8 = 8
CDF_UINT1 = 11
CDF_UINT2 = 12
CDF_UINT4 = 14
CDF_REAL4 = 21
CDF_REAL8 = 22
CDF_EPOCH = 31
CDF_EPOCH16 = 32
CDF_TIME_TT2000 = 33
CDF_BYTE = 41
CDF_FLOAT = 44
CDF_DOUBLE = 45
CDF_CHAR = 51
CDF_UCHAR = 52