Matplotlib cftime Axis Support

Common errors

• ValueError: The values must be numbers or instances of "nc_time_axis.CalendarDateTime".

  cause Attempting to set x-ticks with a list of cftime.datetime objects directly before nc-time-axis v1.4.0, where the converter expected specific types or mishandled list inputs.
  fix Upgrade `nc-time-axis` to v1.4.0 or newer. Ensure that if you are setting ticks explicitly, the values are `cftime.datetime` objects. Alternatively, if you are still on an older version, consider wrapping your `cftime.datetime` objects in `CalendarDateTime` (though this class is deprecated).

• MatplotlibDeprecationWarning: Support for passing numbers through unit converters is deprecated since 3.5 and support will be removed two minor releases later; use Axis.convert_units instead.

  cause This warning occurs when using `matplotlib>=3.5` with `nc-time-axis` versions prior to 1.4.1, due to a change in Matplotlib's unit conversion interface.
  fix Update `nc-time-axis` to version 1.4.1 or later. This version includes a fix to handle this deprecation internally, maintaining compatibility with newer Matplotlib versions.

• Plot shows numerical x-axis (e.g., 0 to 4) instead of dates when plotting cftime.datetime objects with Xarray.

  cause Xarray relies on `nc-time-axis` for plotting `cftime.datetime` objects. If `nc-time-axis` is not installed or the Xarray version is too old to correctly integrate with it, the axis might not be interpreted as a time axis. Also, automatic tick formatting can sometimes be misleading.
  fix Ensure `nc-time-axis` is installed (`pip install nc-time-axis`). Verify Xarray is version 0.16.0 or later (which recommends `nc-time-axis v1.3.0` or later for `cftime` plotting). If the labels are just confusing, try explicitly setting the formatter using Matplotlib's API with `nc_time_axis.CFTimeFormatter`.

Warnings

• deprecated The `nc_time_axis.CalendarDateTime` class is deprecated and will be removed in version 1.5.0.
  Fix: Switch to plotting instances or subclasses of `cftime.datetime` directly instead of wrapping them in `CalendarDateTime`.
• gotcha When using Matplotlib versions 3.5 or newer, `nc-time-axis` might internally trigger a `MatplotlibDeprecationWarning` regarding `units.ConversionInterface.is_numlike()`.
  Fix: Upgrade `nc-time-axis` to version 1.4.1 or later. This version includes an internal fix that addresses the deprecation for backwards compatibility.
• gotcha Before `v1.4.0`, setting `xticks` or `yticks` with lists of `cftime.datetime` objects could lead to `ValueError` or confusing automatic tick labels.
  Fix: Upgrade `nc-time-axis` to version 1.4.0 or later, which improved handling of explicit tick setting and automatic formatting. For precise control, use `ax.set_xticks()` with `cftime.datetime` objects and `nc_time_axis.CFTimeFormatter`.

Install

• pip install nc-time-axis Pip
• conda install -c conda-forge nc-time-axis Conda (conda-forge)

Imports

• nc_time_axis

  import nc_time_axis

  Importing the package registers the necessary Matplotlib converters for cftime.datetime objects.
• CFTimeFormatter

  from nc_time_axis import CFTimeFormatter

  Used for explicit control over tick label formatting on cftime axes.
• CalendarDateTime
  wrong:

  from nc_time_axis.CalendarDateTime import CalendarDateTime

  correct:

  from nc_time_axis import CalendarDateTime

  The CalendarDateTime class is deprecated as of v1.4.0 and will be removed in v1.5.0. Users should directly plot cftime.datetime instances.

Quickstart

This example demonstrates how to plot `cftime.datetime` objects on a Matplotlib axis using `nc-time-axis`. Simply importing `nc_time_axis` registers the necessary converters. You can optionally use `CFTimeFormatter` for custom tick label formatting.

import cftime
import matplotlib.pyplot as plt
import nc_time_axis # This import registers the converters
import numpy as np

# Create some sample cftime data
x_values = np.linspace(0, 6 * np.pi, 100)
y_values = 0.5 * x_values + np.sin(x_values)
times = cftime.num2date(x_values, units="days since 2000-01-01", calendar="noleap")

# Plotting with cftime.datetime objects on the x-axis
fig, ax = plt.subplots(1, 1)
ax.plot(times, y_values)

ax.set_xlabel("Time")
ax.set_ylabel("Value")
ax.set_title("Plot with cftime.datetime Axis")

# For explicit tick formatting, use CFTimeFormatter
# formatter = nc_time_axis.CFTimeFormatter("%Y-%m-%d", "noleap")
# ax.xaxis.set_major_formatter(formatter)

plt.tight_layout()
plt.show()