Category	Click badge for further information...
Package
Documentation
Repository
Testing & CI
Quality
Community
Licence

cf-plot allows you to produce and customise publication-quality contour, vector, line and more plots with the power of Python, matplotlib, Cartopy and cf-python, in as few lines of code as possible.

It is designed to be a useful visualisation tool for environmental, earth and aligned sciences, for example to facilitate climate and meteorological research. cf-plot is developed and maintained by the NCAS-CMS group, part of NCAS.

In as little as four lines of Python including imports and file reading, using cf-plot you can for example produce a contour plot showing a 2D subspace of a netCDF dataset:

import cf
import cfplot as cfp
f = cf.read('<dataset name>.nc')[0]  # picks out a read-in field of the dataset
cfp.con(f.subspace(time=<chosen time value>))  # creates a contour plot of the field at that time value

A gallery of outputs made with cf-plot, showcasing a range of plotting possibilities with links to relevant documentation pages and to example code, can be found on this dedicated page within the documentation, as illustrated in the (static) image at the top of this document.

See the cf-plot homepage (https://ncas-cms.github.io/cf-plot) for the full online documentation.

To install cf-plot with its required dependencies, you can use pip:

pip install cf-plot

or you can use conda (or similar package managers such as mamba) as follows (or equivalent):

conda install -c conda-forge cf-python cf-plot udunits2

More detail about installation is provided on the installation page (https://ncas-cms.github.io/cf-plot/installation.html) of the documentation.

To run the full test suite, call from the repo root:

$ pytest tests

Note however this calls image comparison testing on plot outputs and exact image comparison depends on the environment (libraries and versions) used. So they may fail if your environment differs from that which was used to generate the reference images. Therefore, to allow like-for-like comparison, a specific testing conda environment is provided, cfplot-test-env.yml. With this environment enabled, the image comparison should pass. Note we recommend use of mamba for environment creation/solving, but conda will also work.

$ # Deactivate all other environments present first
$ mamba env create --file cfplot-test-env.yml --name cfplot-test-env
$ conda activate cfplot-test-env
$ pytest tests

However you can disable this aspect with the --skip-image-comparison or equivalently -I option to the cf-plot test suite run with pytest, so that only the functional tests run. This is advised when you use any environment other than the above, except where some library version differs for the purpose of regression testing on that versioning change.

$ pytest tests -I

Everyone is welcome to contribute to cf-plot in the form of bug reports, documentation, code, design proposals, and more.

Contributing guidelines are available in a dedicated document which is copied into the documentation here.

For any queries, see the guidance page (https://ncas-cms.github.io/cf-plot/support.html).