pytimetk puts one time series API over pandas and Polars

One API, more than one engine

The project answers the question why pytimetk exists with three reasons. The first is a single API with multiple engines, where every helper works on pandas and Polars, and many of them also run on NVIDIA cudf on the GPU. The second is productivity first, with visualisation, aggregation, feature engineering, anomaly detection and regime modelling in a couple of lines. The third is what they call performance obsession, which in practice means vectorised Polars support, GPU acceleration in beta, and feature store style caching. The multi-engine promise is the one that changes how you write code, because the alternative is a library that assumes one dataframe library and a second library for the other. The GPU path is the extension of that idea, and the same call can move up the stack as the data grows.

The workflow map tells you what is in the box

The at-a-glance table in the README is organised by workflow, which is a better way to understand the library than a function list. Visualization and diagnostics covers plot_timeseries, plot_stl_diagnostics, plot_time_series_boxplot and a theme_plotly_timetk helper, with interactive Plotly charts, STL faceting, distribution-aware plots and Plotly theming. Time-aware aggregations covers summarize_by_time, apply_by_time and pad_by_time, where the last one fills padded rows with a single scalar. Feature engineering covers augment_timeseries_signature, augment_rolling, augment_wavelet and feature_store, giving calendar signatures, GPU-ready rolling windows, wavelets and reusable feature sets. Anomaly workflows are a chain of anomalize, plot_anomalies, plot_anomalies_decomp and plot_anomalies_cleaned, so you detect, diagnose and visualise without leaving the library. Finance and regimes covers augment_regime_detection with an optional regime_backends extra, augment_macd and dozens of indicators, and Polars-native workflows give a .tk accessor on a Polars DataFrame and an engine="polars" option on the heavy helpers.

The accessor is the API

The sixty second tour shows how the library is meant to be used, and the shape is the point. You load a sample dataset with the date column parsed, then you call a time aware aggregation straight off a groupby object:

monthly = (
    sales.groupby("category_1")
    .summarize_by_time(
        date_column="order_date",
        value_column="total_price",
        freq="MS",
        agg_func=["sum", "mean"],
        engine="polars",
    )
)

The engine argument switches the whole call to the Polars implementation, which is how the single API covers two engines. The plotting call then works on the result, with a column selector in the value position:

monthly.plot_timeseries(
    date_column="order_date",
    value_column=contains("sum"),
    color_column="category_1",
    title="Revenue by Category",
    plotly_dropdown=True,
)

That is the design in miniature. A time aware aggregation is a method on the groupby result rather than a separate call, the column selection is a selector object rather than a string, and the plot is another method on the frame. The tour then fills gaps and detects anomalies, again by chaining:

anomalies = (
    hourly.groupby("category_1")
    .anomalize("order_date", "total_price")
    .plot_anomalies(date_column="order_date", plotly_dropdown=True)
)

The gap filling in the middle of that chain, pad_by_time with a frequency and a fill value, is the step that makes the anomaly detection meaningful, since a detector that treats a missing hour as a flat value will report the gap as an anomaly.

Selectors and natural language periods

Two ergonomics features run through the API. The first is column selectors, so that a pipeline does not break when a column is renamed, with contains and starts_with among the options and a contains helper imported from pytimetk.utils.selection. The second is natural language periods, so that a frequency can be written as two weeks or 45 minutes rather than as 14D or 2700s, and there is a whole guide on the two ideas together. This is the sort of thing that looks like sugar until you maintain a pipeline, where the hard coded string offsets and the positional column indices are the two things that break when somebody changes the data. The other side of the same coin is that a helper that takes a natural language period has to parse it, and the cost of that parsing is paid on every call.

The dependency surface is wide

The pyproject file is a Poetry project and its dependency list explains the reach of the library. The core is pandas with a version split, where Python 3.9 and 3.10 are held at pandas 2.0 and 3.11 and later are allowed pandas 2.0 and up, and alongside it sit pandas-flavor, which provides the accessor machinery the groupby methods hook into, matplotlib, plotnine, plotly, holidays for calendar features, tsfeatures, statsmodels, tqdm and polars with pyarrow. Then the scientific stack: scikit-learn, patsy, xarray, timebasedcv, adjusttext, ray for the distributed feature work, and hmmlearn for the hidden Markov model regime detection. Two dependencies are optional. Pomegranate is an optional alternative backend for regime detection, and cudf-cu12 is the GPU path, marked optional with markers that require Python 3.10 or newer on Linux on either x86_64 or aarch64. The xarray pin carries an inline comment explaining that an upper bound was dropped because of a pandas_flavor issue, which is a small but useful signal about how the pins are maintained. Python 3.9 and newer is supported.

Guides, extras and the current release

The documentation is organised as guides, with a quick start that claims you can load data, plot, summarise and build forecast-ready features in about five minutes, a visualisation guide, a Polars guide, and a selectors and human durations guide. The recent releases have added new time series visualisations such as time series box plots, regression plots, and seasonal and decomposition plots, along with the selectors and natural language periods guide, wider Polars coverage through the.tk accessor, and the beta GPU and feature store work with RAPIDS cudf and MLflow hooks. The repository is laid out as a Poetry project with a src/ directory, a tests/ directory, a docs/ directory, a roadmap/ directory, a dist/ directory and a poetry.lock, and the package metadata is maintained by a long list of people, with the project run by Business Science and Quant Science. The releases are frequent, with 2.5.3 published on 2026-10-16, 2.5.2 on 2026-09-25 and 2.5.1 on 2026-08-05, the last push was on 2026-10-16, and the licence is MIT.

Editorial conclusion

pytimetk fits an analyst who has to resample, engineer features and detect anomalies in the same script and does not want to switch dataframe libraries halfway through, since the same call works on pandas and Polars and the groupby accessor keeps the code in the pandas idiom. It does not fit a project that needs a small dependency tree, because the install pulls in statsmodels, scikit-learn, xarray, ray, hmmlearn and a plotting stack whether or not you use them, and it does not fit a team that cannot accept beta features in a stable release, since the GPU acceleration, the feature store and the MLflow integration are all marked as in beta. Before you upgrade, read the release notes for the version you are moving to, and if you plan to use the regime detection extra, install it explicitly, since it pulls an optional dependency.

Frequently asked questions

Official sources

1. business-science/pytimetk on GitHub
2. License: MIT
3. Project website
4. README
5. Releases