pytimetk — the time-series toolkit for people who build stuff

Time series easier, faster, more fun.

Please ⭐ us on GitHub (it takes 2‑seconds and makes a huge difference).

Why pytimetk?

• Single API, multiple engines. Every helper works on pandas and Polars (many run on NVIDIA cudf/GPU as well).
• Productivity first. Visualization, aggregation, feature engineering, anomaly detection, and regime modeling in a couple of lines.
• Performance obsessed. Vectorized Polars support, GPU acceleration (beta), and feature-store style caching.

The toolkit at a glance

Installation

Install the latest stable version of pytimetk using pip:

pip install pytimetk

Alternatively you can install the development version:

pip install --upgrade --force-reinstall git+https://github.com/business-science/pytimetk.git

60‑second tour

import numpy as np
import pandas as pd
import pytimetk as tk
from pytimetk.utils.selection import contains

sales = tk.load_dataset("bike_sales_sample", parse_dates=["order_date"])

# 1. Summaries in one line (Polars engine for speed)
monthly = (
    sales.groupby("category_1")
    .summarize_by_time(
        date_column="order_date",
        value_column="total_price",
        freq="MS",
        agg_func=["sum", "mean"],
        engine="polars",
    )
)

# 2. Visualize straight from Polars/pandas
monthly.plot_timeseries(
    date_column="order_date",
    value_column=contains("sum"),
    color_column="category_1",
    title="Revenue by Category",
    plotly_dropdown=True,
)

# 3. Fill gaps + detect anomalies
hourly = (
    sales.groupby(["category_1", "order_date"], as_index=False)
    .agg(total_price=("total_price", "sum"))
    .groupby("category_1")
    .pad_by_time(date_column="order_date", freq="1H", fillna=0)
)

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

Fresh in the latest releases

• New data visualizations Discover new time series plots like Time Series Box Plots, Regression Plots, Seasonal and Decomposition plots in our upgraded Guide 01.
• Selectors + natural periods guide. Learn how to point at columns with contains()/starts_with() and specify periods like "2 weeks" or "45 minutes". → Guide 08
• Polars everywhere. Dedicated Polars guide plus .tk accessor coverage for plotting, feature engineering, and gap filling.
• GPU + Feature Store (beta). Run rolling stats using our RAPIDS cudf guide or cache/track expensive feature sets with metadata and MLflow hooks in our new Feature Store guide.

Guides & docs

Quickstart snippet

import pandas as pd
import pytimetk as tk

df = tk.load_dataset("bike_sales_sample", parse_dates=["order_date"])

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

Feature Store & Caching (Beta)

⚠️ Beta: The Feature Store APIs and on-disk format may change before general availability. We’d love feedback and bug reports.

Persist expensive feature engineering steps once and reuse them everywhere. Register a transform, build it on a dataset, and reload it in any notebook or job with automatic versioning, metadata, and cache hits.

import pandas as pd
import pytimetk as tk

df = tk.load_dataset("bike_sales_sample", parse_dates=["order_date"])

store = tk.FeatureStore()

store.register(
    "sales_signature",
    lambda data: tk.augment_timeseries_signature(
        data,
        date_column="order_date",
        engine="pandas",
    ),
    default_key_columns=("order_id",),
    description="Calendar signatures for sales orders.",
)

result = store.build("sales_signature", df)
print(result.from_cache)  # False first run, True on subsequent builds

• Supports local disk or any pyarrow filesystem (e.g., s3://, gs://) via the artifact_uri parameter, plus optional file-based locking for concurrent jobs.
• Optional MLflow helpers capture feature versions and artifacts with your experiments for reproducible pipelines.

🏆 More Coming Soon...

We are in the early stages of development. But it's obvious the potential for pytimetk now in Python. 🐍

• Please ⭐ us on GitHub (it takes 2-seconds and means a lot).
• To make requests, please see our Project Roadmap GH Issue #2. You can make requests there.
• Want to contribute? See our contributing guide here.

⭐️ Star History

Please ⭐ us on GitHub (it takes 2 seconds and means a lot).