{"id":7444,"library":"nc-time-axis","title":"Matplotlib cftime Axis Support","description":"nc-time-axis (current version 1.4.1) provides seamless integration for plotting `cftime.datetime` objects on `matplotlib` axes. It handles various calendar types and automatically formats tick labels. The library is actively maintained with releases focusing on compatibility with `matplotlib` and `cftime` updates, as well as bug fixes and minor enhancements.","status":"active","version":"1.4.1","language":"en","source_language":"en","source_url":"https://github.com/SciTools/nc-time-axis","tags":["matplotlib","cftime","netcdf","plotting","time-series","scientific-computing","axis-customization"],"install":[{"cmd":"pip install nc-time-axis","lang":"bash","label":"Pip"},{"cmd":"conda install -c conda-forge nc-time-axis","lang":"bash","label":"Conda (conda-forge)"}],"dependencies":[{"reason":"Required Python version.","package":"python","optional":false},{"reason":"Core plotting library integration.","package":"matplotlib","optional":false},{"reason":"Provides the datetime objects for axis handling.","package":"cftime","optional":false},{"reason":"Numerical operations, often used with cftime data.","package":"numpy","optional":false}],"imports":[{"note":"Importing the package registers the necessary Matplotlib converters for cftime.datetime objects.","symbol":"nc_time_axis","correct":"import nc_time_axis"},{"note":"Used for explicit control over tick label formatting on cftime axes.","symbol":"CFTimeFormatter","correct":"from nc_time_axis import CFTimeFormatter"},{"note":"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.","wrong":"from nc_time_axis.CalendarDateTime import CalendarDateTime","symbol":"CalendarDateTime","correct":"from nc_time_axis import CalendarDateTime"}],"quickstart":{"code":"import cftime\nimport matplotlib.pyplot as plt\nimport nc_time_axis # This import registers the converters\nimport numpy as np\n\n# Create some sample cftime data\nx_values = np.linspace(0, 6 * np.pi, 100)\ny_values = 0.5 * x_values + np.sin(x_values)\ntimes = cftime.num2date(x_values, units=\"days since 2000-01-01\", calendar=\"noleap\")\n\n# Plotting with cftime.datetime objects on the x-axis\nfig, ax = plt.subplots(1, 1)\nax.plot(times, y_values)\n\nax.set_xlabel(\"Time\")\nax.set_ylabel(\"Value\")\nax.set_title(\"Plot with cftime.datetime Axis\")\n\n# For explicit tick formatting, use CFTimeFormatter\n# formatter = nc_time_axis.CFTimeFormatter(\"%Y-%m-%d\", \"noleap\")\n# ax.xaxis.set_major_formatter(formatter)\n\nplt.tight_layout()\nplt.show()","lang":"python","description":"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."},"warnings":[{"fix":"Switch to plotting instances or subclasses of `cftime.datetime` directly instead of wrapping them in `CalendarDateTime`.","message":"The `nc_time_axis.CalendarDateTime` class is deprecated and will be removed in version 1.5.0.","severity":"deprecated","affected_versions":">=1.4.0"},{"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.","message":"When using Matplotlib versions 3.5 or newer, `nc-time-axis` might internally trigger a `MatplotlibDeprecationWarning` regarding `units.ConversionInterface.is_numlike()`.","severity":"gotcha","affected_versions":">=1.4.0, <1.4.1"},{"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`.","message":"Before `v1.4.0`, setting `xticks` or `yticks` with lists of `cftime.datetime` objects could lead to `ValueError` or confusing automatic tick labels.","severity":"gotcha","affected_versions":"<1.4.0"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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).","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.","error":"ValueError: The values must be numbers or instances of \"nc_time_axis.CalendarDateTime\"."},{"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.","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.","error":"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."},{"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`.","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.","error":"Plot shows numerical x-axis (e.g., 0 to 4) instead of dates when plotting cftime.datetime objects with Xarray."}]}