Install & Compatibility
Where this runs
tested against v1.4.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.954s · 183.4MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 7.7s · import 0.905s · 177MB
186MB installed
● package 186MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
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
✓ from nc_time_axis import CalendarDateTime
✗ from nc_time_axis.CalendarDateTime 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.
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()
Errors
Common errors & fixes
ValueError: The values must be numbers or instances of "nc_time_axis.CalendarDateTime".
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.
fixUpgrade `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.
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.
fixUpdate `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.
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.
fixEnsure `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`.
Upgrade
Version history
1.4.1latest on PyPI · released Apr 20, 2022
Audit
Dependencies
pythonrequiredRequired Python version.
matplotlibrequiredCore plotting library integration.
cftimerequiredProvides the datetime objects for axis handling.
numpyrequiredNumerical operations, often used with cftime data.