<div align="center">
<img src="docs/logo-timetk.png" width="30%"/>
</div>
<div align="center">
<a href="https://github.com/business-science/pytimetk/actions">
<img alt="Github Actions" src="https://img.shields.io/github/actions/workflow/status/business-science/pytimetk/timetk-checks.yaml?style=for-the-badge"/>
</a>
<a href="https://pypi.python.org/pypi/pytimetk">
<img alt="PyPI Version" src="https://img.shields.io/pypi/v/pytimetk.svg?style=for-the-badge"/>
</a>
<a href="https://github.com/business-science/pytimetk"><img src="https://img.shields.io/pypi/pyversions/pytimetk.svg?style=for-the-badge" alt="versions"></a>
<a href="https://business-science.github.io/pytimetk/contributing.html">
<a href="https://github.com/business-science/pytimetk/blob/main/LICENSE"><img src="https://img.shields.io/github/license/business-science/pytimetk.svg?style=for-the-badge" alt="license"></a>
<img alt="PRs Welcome" src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=for-the-badge"/>
<img alt="GitHub Repo stars" src="https://img.shields.io/github/stars/business-science/pytimetk?style=for-the-badge">
</a>
</div>
# pytimetk
> Time series easier, faster, more fun. Pytimetk.
[**Please ⭐ us on GitHub (it takes 2-seconds and means a lot).**](https://github.com/business-science/pytimetk)
# Introducing pytimetk: Simplifying Time Series Analysis for Everyone
Time series analysis is fundamental in many fields, from business forecasting to scientific research. While the Python ecosystem offers tools like `pandas`, they sometimes can be verbose and not optimized for all operations, especially for complex time-based aggregations and visualizations.
Enter **pytimetk**. Crafted with a blend of ease-of-use and computational efficiency, `pytimetk` significantly simplifies the process of time series manipulation and visualization. By leveraging the `polars` backend, you can experience speed improvements ranging from 3X to a whopping 3500X. Let's dive into a comparative analysis.
| Features/Properties | **pytimetk** | **pandas (+matplotlib)** |
|---------------------|-------------------------------|---------------------------------------|
| **Speed** | 🚀 3X to 3500X Faster | 🐢 Standard |
| **Code Simplicity** | 🎉 Concise, readable syntax | 📜 Often verbose |
| `plot_timeseries()` | 🎨 2 lines, no customization | 🎨 16 lines, customization needed |
| `summarize_by_time()` | 🕐 2 lines, 13.4X faster | 🕐 6 lines, 2 for-loops |
| `pad_by_time()` | ⛳ 2 lines, fills gaps in timeseries | ❌ No equivalent |
| `anomalize()` | 📈 2 lines, detects and corrects anomalies | ❌ No equivalent |
| `augment_timeseries_signature()` | 📅 1 line, all calendar features | 🕐 29 lines of `dt` extractors |
| `augment_rolling()` | 🏎️ 10X to 3500X faster | 🐢 Slow Rolling Operations |
| polars `.tk` plotting | ✅ Plot directly on `pl.DataFrame` (`plot_timeseries`, `plot_anomalies`, `plot_correlation_funnel`, …) | ❌ pandas-only accessor |
| polars `.tk` accessor | ✅ Core, feature, and plotting helpers available via `.tk` on pandas/polars | ❌ N/A |
| Feature store & caching | 🗃️ Persist, version, and reuse feature sets (with optional MLflow logging) | ❌ Manual recompute, no metadata lineage |
As evident from the table, **pytimetk** is not just about speed; it also simplifies your codebase. For example, `summarize_by_time()`, converts a 6-line, double for-loop routine in `pandas` into a concise 2-line operation. And with the `polars` engine, get results 13.4X faster than `pandas`!
Similarly, `plot_timeseries()` dramatically streamlines the plotting process, encapsulating what would typically require 16 lines of `matplotlib` code into a mere 2-line command in **pytimetk**, without sacrificing customization or quality. And with `plotly` and `plotnine` engines, you can create interactive plots and beautiful static visualizations with just a few lines of code.
For calendar features, **pytimetk** offers `augment_timeseries_signature()` which cuts down on over 30 lines of `pandas` dt extractions. For rolling features, **pytimetk** offers `augment_rolling()`, which is 10X to 3500X faster than `pandas`. It also offers `pad_by_time()` to fill gaps in your time series data, and `anomalize()` to detect and correct anomalies in your time series data.
Join the revolution in time series analysis. Reduce your code complexity, increase your productivity, and harness the speed that **pytimetk** brings to your workflows.
Explore more at our [pytimetk homepage](https://business-science.github.io/pytimetk/).
# Installation
Install the latest stable version of `pytimetk` using `pip`:
```bash
pip install pytimetk
```
Alternatively you can install the development version:
```bash
pip install --upgrade --force-reinstall git+https://github.com/business-science/pytimetk.git
```
# Quickstart:
This is a simple code to test the function `summarize_by_time`:
```python
import pytimetk as tk
import pandas as pd
df = tk.datasets.load_dataset('bike_sales_sample')
df['order_date'] = pd.to_datetime(df['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"
)
```
## What's New in pytimetk 2.0.0
- Added polars `.tk` accessor support for plotting helpers (`plot_timeseries`, `plot_anomalies`, `plot_anomalies_decomp`, `plot_anomalies_cleaned`, `plot_correlation_funnel`).
- Polars users can now call these functions directly on `pl.DataFrame` objects via the `.tk` accessor; results mirror the pandas interface (Plotly `Figure` or plotnine `ggplot`).
- See the [change log](https://business-science.github.io/pytimetk/changelog.html) for more details.
## 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](https://github.com/business-science/pytimetk/issues).
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.
```python
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.
# Documentation
Get started with the [pytimetk documentation](https://business-science.github.io/pytimetk/)
- [📈 Overview](https://business-science.github.io/pytimetk/)
- [🏁 Getting Started](https://business-science.github.io/pytimetk/getting-started/02_quick_start.html)
- [🗺️ Beginner Guides](https://business-science.github.io/pytimetk/guides/01_visualization.html)
- [📘Applied Data Science Tutorials](https://business-science.github.io/pytimetk/tutorials/01_sales_crm.html)
- [📄 API Reference](https://business-science.github.io/pytimetk/reference/)
# 🏆 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](https://github.com/business-science/pytimetk) (it takes 2-seconds and means a lot).
- To make requests, please see our [Project Roadmap GH Issue #2](https://github.com/business-science/pytimetk/issues/2). You can make requests there.
- Want to contribute? [See our contributing guide here.](/contributing.html)
# ⭐️ Star History
[](https://star-history.com/#business-science/pytimetk&Date)
[**Please ⭐ us on GitHub (it takes 2 seconds and means a lot).**](https://github.com/business-science/pytimetk)
Raw data
{
"_id": null,
"home_page": "https://business-science.github.io/pytimetk/",
"name": "pytimetk",
"maintainer": "Matt Dancho",
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": "mdancho@business-science.io",
"keywords": "time series, forecasting, machine learning, data science",
"author": "Business Science",
"author_email": "info@business-science.io",
"download_url": "https://files.pythonhosted.org/packages/fc/d9/bc2a0e6294e14cff963924e37be8236fad22bfa609f010e507110a46791c/pytimetk-2.0.1.tar.gz",
"platform": null,
"description": "<div align=\"center\">\n<img src=\"docs/logo-timetk.png\" width=\"30%\"/>\n</div>\n\n<div align=\"center\">\n <a href=\"https://github.com/business-science/pytimetk/actions\">\n <img alt=\"Github Actions\" src=\"https://img.shields.io/github/actions/workflow/status/business-science/pytimetk/timetk-checks.yaml?style=for-the-badge\"/>\n </a>\n <a href=\"https://pypi.python.org/pypi/pytimetk\">\n <img alt=\"PyPI Version\" src=\"https://img.shields.io/pypi/v/pytimetk.svg?style=for-the-badge\"/>\n </a>\n <a href=\"https://github.com/business-science/pytimetk\"><img src=\"https://img.shields.io/pypi/pyversions/pytimetk.svg?style=for-the-badge\" alt=\"versions\"></a>\n <a href=\"https://business-science.github.io/pytimetk/contributing.html\">\n <a href=\"https://github.com/business-science/pytimetk/blob/main/LICENSE\"><img src=\"https://img.shields.io/github/license/business-science/pytimetk.svg?style=for-the-badge\" alt=\"license\"></a>\n <img alt=\"PRs Welcome\" src=\"https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=for-the-badge\"/>\n <img alt=\"GitHub Repo stars\" src=\"https://img.shields.io/github/stars/business-science/pytimetk?style=for-the-badge\">\n </a>\n</div>\n\n# pytimetk\n\n> Time series easier, faster, more fun. Pytimetk.\n\n[**Please \u2b50 us on GitHub (it takes 2-seconds and means a lot).**](https://github.com/business-science/pytimetk)\n\n# Introducing pytimetk: Simplifying Time Series Analysis for Everyone\n\nTime series analysis is fundamental in many fields, from business forecasting to scientific research. While the Python ecosystem offers tools like `pandas`, they sometimes can be verbose and not optimized for all operations, especially for complex time-based aggregations and visualizations.\n\nEnter **pytimetk**. Crafted with a blend of ease-of-use and computational efficiency, `pytimetk` significantly simplifies the process of time series manipulation and visualization. By leveraging the `polars` backend, you can experience speed improvements ranging from 3X to a whopping 3500X. Let's dive into a comparative analysis.\n\n| Features/Properties | **pytimetk** | **pandas (+matplotlib)** |\n|---------------------|-------------------------------|---------------------------------------|\n| **Speed** | \ud83d\ude80 3X to 3500X Faster | \ud83d\udc22 Standard |\n| **Code Simplicity** | \ud83c\udf89 Concise, readable syntax | \ud83d\udcdc Often verbose |\n| `plot_timeseries()` | \ud83c\udfa8 2 lines, no customization | \ud83c\udfa8 16 lines, customization needed |\n| `summarize_by_time()` | \ud83d\udd50 2 lines, 13.4X faster | \ud83d\udd50 6 lines, 2 for-loops |\n| `pad_by_time()` | \u26f3 2 lines, fills gaps in timeseries | \u274c No equivalent |\n| `anomalize()` | \ud83d\udcc8 2 lines, detects and corrects anomalies | \u274c No equivalent |\n| `augment_timeseries_signature()` | \ud83d\udcc5 1 line, all calendar features | \ud83d\udd50 29 lines of `dt` extractors |\n| `augment_rolling()` | \ud83c\udfce\ufe0f 10X to 3500X faster | \ud83d\udc22 Slow Rolling Operations |\n| polars `.tk` plotting | \u2705 Plot directly on `pl.DataFrame` (`plot_timeseries`, `plot_anomalies`, `plot_correlation_funnel`, \u2026) | \u274c pandas-only accessor |\n| polars `.tk` accessor | \u2705 Core, feature, and plotting helpers available via `.tk` on pandas/polars | \u274c N/A |\n| Feature store & caching | \ud83d\uddc3\ufe0f Persist, version, and reuse feature sets (with optional MLflow logging) | \u274c Manual recompute, no metadata lineage |\n\nAs evident from the table, **pytimetk** is not just about speed; it also simplifies your codebase. For example, `summarize_by_time()`, converts a 6-line, double for-loop routine in `pandas` into a concise 2-line operation. And with the `polars` engine, get results 13.4X faster than `pandas`!\n \nSimilarly, `plot_timeseries()` dramatically streamlines the plotting process, encapsulating what would typically require 16 lines of `matplotlib` code into a mere 2-line command in **pytimetk**, without sacrificing customization or quality. And with `plotly` and `plotnine` engines, you can create interactive plots and beautiful static visualizations with just a few lines of code.\n\nFor calendar features, **pytimetk** offers `augment_timeseries_signature()` which cuts down on over 30 lines of `pandas` dt extractions. For rolling features, **pytimetk** offers `augment_rolling()`, which is 10X to 3500X faster than `pandas`. It also offers `pad_by_time()` to fill gaps in your time series data, and `anomalize()` to detect and correct anomalies in your time series data.\n\nJoin the revolution in time series analysis. Reduce your code complexity, increase your productivity, and harness the speed that **pytimetk** brings to your workflows.\n\nExplore more at our [pytimetk homepage](https://business-science.github.io/pytimetk/).\n\n# Installation\n\nInstall the latest stable version of `pytimetk` using `pip`:\n\n```bash\npip install pytimetk\n```\n\nAlternatively you can install the development version:\n\n```bash\npip install --upgrade --force-reinstall git+https://github.com/business-science/pytimetk.git\n```\n\n# Quickstart:\n\nThis is a simple code to test the function `summarize_by_time`:\n\n```python\nimport pytimetk as tk\nimport pandas as pd\n\ndf = tk.datasets.load_dataset('bike_sales_sample')\ndf['order_date'] = pd.to_datetime(df['order_date'])\n\ndf \\\n .groupby(\"category_2\") \\\n .summarize_by_time(\n date_column='order_date', \n value_column= 'total_price',\n freq = \"MS\",\n agg_func = ['mean', 'sum'],\n engine = \"polars\"\n )\n```\n\n\n## What's New in pytimetk 2.0.0\n\n- Added polars `.tk` accessor support for plotting helpers (`plot_timeseries`, `plot_anomalies`, `plot_anomalies_decomp`, `plot_anomalies_cleaned`, `plot_correlation_funnel`).\n- Polars users can now call these functions directly on `pl.DataFrame` objects via the `.tk` accessor; results mirror the pandas interface (Plotly `Figure` or plotnine `ggplot`).\n- See the [change log](https://business-science.github.io/pytimetk/changelog.html) for more details.\n\n## Feature Store & Caching (Beta)\n\n> \u26a0\ufe0f **Beta:** The Feature Store APIs and on-disk format may change before general availability. We\u2019d love [feedback and bug reports](https://github.com/business-science/pytimetk/issues).\n\nPersist 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.\n\n```python\nimport pandas as pd\nimport pytimetk as tk\n\ndf = tk.load_dataset(\"bike_sales_sample\", parse_dates=[\"order_date\"])\n\nstore = tk.FeatureStore()\n\nstore.register(\n \"sales_signature\",\n lambda data: tk.augment_timeseries_signature(\n data,\n date_column=\"order_date\",\n engine=\"pandas\",\n ),\n default_key_columns=(\"order_id\",),\n description=\"Calendar signatures for sales orders.\",\n)\n\nresult = store.build(\"sales_signature\", df)\nprint(result.from_cache) # False first run, True on subsequent builds\n```\n\n- Supports local disk or any `pyarrow` filesystem (e.g., `s3://`, `gs://`) via the `artifact_uri` parameter, plus optional file-based locking for concurrent jobs.\n- Optional MLflow helpers capture feature versions and artifacts with your experiments for reproducible pipelines.\n\n# Documentation\n\nGet started with the [pytimetk documentation](https://business-science.github.io/pytimetk/)\n\n- [\ud83d\udcc8 Overview](https://business-science.github.io/pytimetk/)\n- [\ud83c\udfc1 Getting Started](https://business-science.github.io/pytimetk/getting-started/02_quick_start.html)\n- [\ud83d\uddfa\ufe0f Beginner Guides](https://business-science.github.io/pytimetk/guides/01_visualization.html)\n- [\ud83d\udcd8Applied Data Science Tutorials](https://business-science.github.io/pytimetk/tutorials/01_sales_crm.html)\n- [\ud83d\udcc4 API Reference](https://business-science.github.io/pytimetk/reference/)\n\n# \ud83c\udfc6 More Coming Soon...\n\nWe are in the early stages of development. But it's obvious the potential for `pytimetk` now in Python. \ud83d\udc0d\n\n- Please [\u2b50 us on GitHub](https://github.com/business-science/pytimetk) (it takes 2-seconds and means a lot). \n- To make requests, please see our [Project Roadmap GH Issue #2](https://github.com/business-science/pytimetk/issues/2). You can make requests there. \n- Want to contribute? [See our contributing guide here.](/contributing.html)\n\n# \u2b50\ufe0f Star History\n\n[](https://star-history.com/#business-science/pytimetk&Date)\n\n[**Please \u2b50 us on GitHub (it takes 2 seconds and means a lot).**](https://github.com/business-science/pytimetk)\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "The time series toolkit for Python.",
"version": "2.0.1",
"project_urls": {
"Documentation": "https://business-science.github.io/pytimetk/reference/",
"Homepage": "https://business-science.github.io/pytimetk/",
"Repository": "https://github.com/business-science/pytimetk"
},
"split_keywords": [
"time series",
" forecasting",
" machine learning",
" data science"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "9a177bb4ce7afb5cd088a50c8d37398f42143881e80b86a34520550143c7acc0",
"md5": "81576fb4a1f9d59509198f561a401836",
"sha256": "30246d28843848a73f2007824c818a87ff02d06ce19c821f2be8551b874be436"
},
"downloads": -1,
"filename": "pytimetk-2.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "81576fb4a1f9d59509198f561a401836",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 4345455,
"upload_time": "2025-10-13T19:36:33",
"upload_time_iso_8601": "2025-10-13T19:36:33.363999Z",
"url": "https://files.pythonhosted.org/packages/9a/17/7bb4ce7afb5cd088a50c8d37398f42143881e80b86a34520550143c7acc0/pytimetk-2.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "fcd9bc2a0e6294e14cff963924e37be8236fad22bfa609f010e507110a46791c",
"md5": "f968058e68a30c4e361d79af5acc7fb9",
"sha256": "7202f04ef4e2f07ba89a231e45a80b70c5e08b59056b6f59762af8594a2c6d83"
},
"downloads": -1,
"filename": "pytimetk-2.0.1.tar.gz",
"has_sig": false,
"md5_digest": "f968058e68a30c4e361d79af5acc7fb9",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 4157510,
"upload_time": "2025-10-13T19:36:37",
"upload_time_iso_8601": "2025-10-13T19:36:37.808044Z",
"url": "https://files.pythonhosted.org/packages/fc/d9/bc2a0e6294e14cff963924e37be8236fad22bfa609f010e507110a46791c/pytimetk-2.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-13 19:36:37",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "business-science",
"github_project": "pytimetk",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pytimetk"
}
JSON
