Timple

0.1.8 verified Fri May 01 auth: no python

A Python library that extends Matplotlib's plotting capabilities for timedelta-like values, providing custom tick locators and formatters for intuitive axis formatting. Version 0.1.8 supports Python >=3.7 and is actively maintained.

pip install timple

Common errors

error AttributeError: module 'timple' has no attribute 'TimedeltaConverter' ↓

cause Incorrect import or outdated version (TimedeltaConverter was added likely after 0.1.0).

fix

Ensure you have installed timple>=0.1.0 and use correct import: 'from timple import TimedeltaConverter'.

error TypeError: cannot convert timedelta to matplotlib format ↓

cause Data is not in a format that TimedeltaConverter expects (e.g., plain datetime.timedelta or list of strings).

fix

Convert data to Pandas Timedelta or numpy timedelta64 array before passing to converter: times = pd.to_timedelta(times_list).

error ValueError: The truth value of a Timedelta is ambiguous ↓

cause Passing a Pandas NaT alongside valid timedeltas on timple <0.1.2.

fix

Upgrade to timple>=0.1.2 or drop NaT values using .dropna() on a Pandas Series.

Warnings

gotcha Timple converters only work with ax.xaxis or ax.yaxis, not directly with plt.xticks(). Apply the converter to the desired axis instance. ↓

fix Use TimedeltaConverter(timedelta_data).apply(axis_object) where axis_object is an Axes.xaxis or Axes.yaxis.

gotcha Passing a list or tuple of Pandas Timedelta objects can cause crashes in versions prior to 0.1.6. Ensure you use NumPy array or Pandas Series. ↓

fix Upgrade to timple>=0.1.6 or convert to numpy array with np.array(your_list).

deprecated The argument 'concise' was deprecated in v0.1.1 in favor of separate locators/formatters. Avoid passing concise=True to the converter. ↓

fix Use ticker_concise or formatter_concise directly instead.

gotcha When using Pandas NaT values, converters may fail on older versions (before 0.1.2). Upgrade or drop NaT values before plotting. ↓

fix Upgrade to timple>=0.1.2 or drop NaT with times.dropna() if using Pandas Series.

gotcha Masked arrays introduced in Matplotlib 3.7.0 are only supported from timple 0.1.6 onwards. Plotting masked timedelta data with earlier versions will crash. ↓

fix Upgrade to timple>=0.1.6 or avoid using masked arrays.

Imports

TimedeltaConverter
```
from timple import TimedeltaConverter
```
Main converter class for timedelta axis formatting
ticker_concise
```
from timple import ticker_concise
```
Concise timedelta tick locator
ticker_short
```
from timple import ticker_short
```
Short timedelta tick locator
formatter_concise
```
from timple import formatter_concise
```
Concise timedelta formatter
formatter_short
```
from timple import formatter_short
```
Short timedelta formatter

Quickstart

Plot timedelta data with automatic axis formatting.

import matplotlib.pyplot as plt
import pandas as pd
from timple import TimedeltaConverter

# Create a simple timedelta series
times = pd.to_timedelta(['00:00:00', '00:01:30', '00:03:00', '00:04:30'])
values = [1, 2, 3, 4]

fig, ax = plt.subplots()
ax.plot(times, values)

# Apply Timple converter
TimedeltaConverter(times).apply(ax.xaxis)

ax.set_xlabel('Time')
ax.set_ylabel('Value')
plt.show()