Installation

Version 3.16.2 for version 1.11 of the CF conventions.

Operating systems

The cf package works only for Linux and Mac operating systems.

If you have a Windows operating system then you can use the Microsoft Windows Subsystem for Linux (WSL).

Python versions

The cf package is only for Python 3.8 or newer.

pip

cf is in the Python package index: https://pypi.org/project/cf-python

To install cf and its required dependencies (apart from Udunits, and there are also some optional dependencies which are not automatically installed via pip) run, for example:

Install as root, with any missing dependencies.
$ pip install cf-python
Install as a user, with any missing dependencies.
$ pip install cf-python --user

To install cf without any of its dependencies then run, for example:

Install as root without installing any of the dependencies.
$ pip install cf-python --no-deps

See the documentation for pip install for further options.

Udunits

Udunits (a C library that provides support for units of physical quantities) is a required dependency that is not installed by pip, but it can be installed in a conda environment:

$ conda install -c conda-forge udunits2

Alternatively, Udunits is often available from operating system software download managers, or may be installed from source.

Note that some environment variables might also need setting in order for the Udunits library to work properly, although the defaults are usually sufficient.

See the required dependencies section for more details.

conda

To install cf with all of its required and optional dependencies, and the cf-plot visualisation package, run:

Install with conda.
$ conda install -c conda-forge cf-python cf-plot udunits2
$ conda install -c conda-forge "esmpy>=8.0.0"

The second of the two conda commands is required for regridding to work.

Note that some environment variables might also need setting in order for the Udunits library to work properly, although the defaults are usually sufficient.

Source

To install from source (without any dependencies):

  1. Download the cf package from https://pypi.org/project/cf-python

  2. Unpack the library (replacing <version> with the version that you want to install, e.g. 3.16.2):

    $ tar zxvf cf-python-<version>.tar.gz
$ cd cf-python-<version>

  3. Install the package:

  • To install the cf-python package to a central location:

    $ python setup.py install

  • To install the cf-python package locally to the user in the default location:

    $ python setup.py install --user

  • To install the cf-python package in the <directory> of your choice:

    $ python setup.py install --home=<directory>

Note that some environment variables might also need setting in order for the Udunits library to work properly, although the defaults are usually sufficient.

cfa utility

During installation the cfa command line utility is also installed, which:

Dependencies

Required

  • Python, 3.8.0 or newer.

  • numpy, 1.22.0 or newer.

  • dask, 2022.12.1 or newer.

  • netCDF4, 1.6.5 or newer.

  • cftime, version 1.6.2 or newer (note that this package may be installed with netCDF4).

  • scipy, version 1.10.0 or newer.

  • cfdm, version 1.11.1.0 or up to, but not including, 1.11.2.0.

  • cfunits, version 3.3.7 or newer.

  • psutil, version 0.6.0 or newer.

  • packaging, version 20.0 or newer.

  • UNIDATA Udunits-2 library, version 2.2.25 or newer. UDUNITS-2 is a C library that provides support for units of physical quantities.

    If the Udunits-2 shared library file (libudunits2.so.0 on GNU/Linux or libudunits2.0.dylibfile on MacOS) is in a non-standard location then its directory path should be added to the LD_LIBRARY_PATH environment variable.

    It may also be necessary to specify the location (directory path and file name) of the udunits2.xml file in the UDUNITS2_XML_PATH environment variable, although the default location is usually correct. For example, export UDUNITS2_XML_PATH=/home/user/anaconda3/share/udunits/udunits2.xml. If you get a run-time error that looks like assert(0 == _ut_unmap_symbol_to_unit(_ut_system, _c_char_p(b'Sv'), _UT_ASCII)) then setting the UDUNITS2_XML_PATH environment variable is the likely solution.

Optional

Some further dependencies that enable further functionality are optional. This to facilitate cf-python being installed in restricted environments for which these features are not required.

Regridding

  • esmpy, previously named ESMF with the old module name also being accepted for import, version 8.0.0 or newer. This is easily installed via conda with

    $ conda install -c conda-forge "esmpy>=8.0.0"

    or may be installed from source.

Subspacing based on N-dimensional construct cells (N > 1) containing a given value

Tests

Tests are run from within the cf/test directory:

$ python run_tests.py

Code repository

The complete source code and issue tracker is available at https://github.com/NCAS-CMS/cf-python