climatepals / cfdm

A Python reference implementation of the CF data model

cfdm

A Python reference implementation of the CF data model.

References

Compliance with FAIR principles

Documentation

https://ncas-cms.github.io/cfdm

Tutorial

https://ncas-cms.github.io/cfdm/tutorial

Installation

https://ncas-cms.github.io/cfdm/installation

Functionality

The cfdm package implements the CF data model (https://doi.org/10.5194/gmd-10-4619-2017) for its internal data structures and so is able to process any CF-compliant dataset. It is not strict about CF-compliance, however, so that partially conformant datasets may be ingested from existing datasets and written to new datasets. This is so that datasets which are partially conformant may nonetheless be modified in memory.

The central elements defined by the CF data model are the field construct, which corresponds to CF-netCDF data variable with all of its metadata; and the domain contruct, which may be the domain of a field construct or corresponds to a CF-netCDF domain variable with all of its metadata.

A simple example of reading a field construct from a file and inspecting it:

>>> import cfdm
>>> f = cfdm.read('file.nc')
>>> f
[<Field: air_temperature(time(12), latitude(64), longitude(128)) K>]
>>> print(f[0])
Field: air_temperature (ncvar%tas)
----------------------------------
Data            : air_temperature(time(12), latitude(64), longitude(128)) K
Cell methods    : time(12): mean (interval: 1.0 month)
Dimension coords: time(12) = [0450-11-16 00:00:00, ..., 0451-10-16 12:00:00] noleap
                : latitude(64) = [-87.8638, ..., 87.8638] degrees_north
                : longitude(128) = [0.0, ..., 357.1875] degrees_east
                : height(1) = [2.0] m

The cfdm package can:

• read field and domain constructs from netCDF and CDL datasets,
• create new field and domain constructs in memory,
• write and append field and domain constructs to netCDF datasets on disk,
• read, write, and create coordinates defined by geometry cells,
• read and write netCDF4 string data-type variables,
• read, write, and create netCDF and CDL datasets containing hierarchical groups,
• inspect field and domain constructs,
• test whether two constructs are the same,
• modify field and domain construct metadata and data,
• create subspaces of field and domain constructs, from indices or metadata values,
• incorporate, and create, metadata stored in external files, and
• read, write, and create data that have been compressed by convention (i.e. ragged or gathered arrays, or coordinate arrays compressed by subsampling), whilst presenting a view of the data in its uncompressed form.

Command line utility

During installation the cfdump command line tool is also installed, which generates text descriptions of the field constructs contained in a netCDF dataset:

$ cfdump file.nc
Field: air_temperature (ncvar%tas)
----------------------------------
Data            : air_temperature(time(12), latitude(64), longitude(128)) K
Cell methods    : time(12): mean (interval: 1.0 month)
Dimension coords: time(12) = [0450-11-16 00:00:00, ..., 0451-10-16 12:00:00] noleap
                : latitude(64) = [-87.8638, ..., 87.8638] degrees_north
                : longitude(128) = [0.0, ..., 357.1875] degrees_east
                : height(1) = [2.0] m

Tests

Tests are run from within the cfdm/test directory:

$ python run_tests.py

Citation

If you use cfdm, either as a stand-alone application or to provide a CF data model implementation to another software library, please consider including the reference:

Hassell et al., (2020). cfdm: A Python reference implementation of the CF data model. Journal of Open Source Software, 5(54), 2717, https://doi.org/10.21105/joss.02717

@article{Hassell2020,
  doi = {10.21105/joss.02717},
  url = {https://doi.org/10.21105/joss.02717},
  year = {2020},
  publisher = {The Open Journal},
  volume = {5},
  number = {54},
  pages = {2717},
  author = {David Hassell and Sadie L. Bartholomew},
  title = {cfdm: A Python reference implementation of the CF data model},
  journal = {Journal of Open Source Software}
}