- Pandas and Polars Compatibility:
- Improvements: @@ -392,8 +392,8 @@
Changelog for Pytimetk
-pytimetk 0.4.0.9000 (Development Version)
+pytimetk 1.0.0
Pandas and Polars Compatibility:
Upgrading to:
diff --git a/docs/_site/sitemap.xml b/docs/_site/sitemap.xml index 6e927291..7b04c865 100644 --- a/docs/_site/sitemap.xml +++ b/docs/_site/sitemap.xml @@ -2,342 +2,342 @@![\"Github](\"https://github.com/business-science/pytimetk/actions/workflows/timetk-checks.yaml/badge.svg\"/){kind=icon}
\n",
+ " ![\"PyPI](\"https://img.shields.io/pypi/v/pytimetk.svg\"/)
\n",
+ " ![\"PRs](\"https://img.shields.io/badge/PRs-welcome-brightgreen.svg\"/){kind=icon}
\n",
+ " ![](\"logo-timetk.png\")
\n",
+ "\n",
+ "> Time series easier, faster, more fun. Pytimetk.\n",
+ "\n",
+ "**PyTimetk's Mission:** To make time series analysis easier, faster, and more enjoyable in Python.\n",
+ "\n",
+ "[**Please β 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",
+ "\n",
+ "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.\n",
+ "\n",
+ "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.\n",
+ "\n",
+ "\n",
+ "| Features/Properties | **pytimetk** | **pandas (+matplotlib)** |\n",
+ "|---------------------|-------------------------------|---------------------------------------|\n",
+ "| **Speed** | π 3X to 500X Faster | π’ Standard |\n",
+ "| **Code Simplicity** | π Concise, readable syntax | π Often verbose |\n",
+ "| `plot_timeseries()` | π¨ 2 lines, no customization | π¨ 16 lines, customization needed |\n",
+ "| `summarize_by_time()` | π 2 lines, 13.4X faster | π 6 lines, 2 for-loops |\n",
+ "| `pad_by_time()` | β³ 2 lines, fills gaps in timeseries | β No equivalent |\n",
+ "| `anomalize()` | π 2 lines, detects and corrects anomalies | β No equivalent |\n",
+ "| `augment_timeseries_signature()` | π
1 line, all calendar features | π 30 lines of `dt` extractors |\n",
+ "| `augment_rolling()` | ποΈ 10X to 3500X faster | π’ Slow Rolling Operations |\n",
+ "\n",
+ "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`!\n",
+ " \n",
+ "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.\n",
+ "\n",
+ "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.\n",
+ "\n",
+ "Join the revolution in time series analysis. Reduce your code complexity, increase your productivity, and harness the speed that **pytimetk** brings to your workflows.\n",
+ "\n",
+ "Explore more at our [pytimetk homepage](https://business-science.github.io/pytimetk/).\n",
+ "\n",
+ "# π Installation\n",
+ "\n",
+ "Install the Latest Stable Version:\n",
+ "\n",
+ "``` bash\n",
+ "pip install pytimetk\n",
+ "```\n",
+ "\n",
+ "Alternatively, install the Development GitHub Version:\n",
+ "\n",
+ "```bash\n",
+ "pip install git+https://github.com/business-science/pytimetk.git\n",
+ "```\n",
+ "\n",
+ "# π Quick Start: A Monthly Sales Analysis\n",
+ "\n",
+ "This is a simple exercise to showcase the power of [`summarize_by_time()`](/reference/summarize_by_time.html):\n",
+ "\n",
+ "### Import Libraries & Data\n",
+ "\n",
+ "First, `import pytimetk as tk`. This gets you access to the most important functions. Use `tk.load_dataset()` to load the \"bike_sales_sample\" dataset.\n",
+ "\n",
+ "::: {.callout-note collapse=\"false\"}\n",
+ "## About the Bike Sales Sample Dataset\n",
+ "\n",
+ "This dataset contains \"orderlines\" for orders recieved. The `order_date` column contains timestamps. We can use this column to peform sales aggregations (e.g. total revenue).\n",
+ ":::\n"
+ ],
+ "id": "965e83de"
+ },
+ {
+ "cell_type": "code",
+ "metadata": {},
+ "source": [
+ "import pytimetk as tk\n",
+ "import pandas as pd\n",
+ "\n",
+ "df = tk.load_dataset('bike_sales_sample')\n",
+ "df['order_date'] = pd.to_datetime(df['order_date'])\n",
+ "\n",
+ "df "
+ ],
+ "id": "00147f1b",
+ "execution_count": null,
+ "outputs": []
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "### Using `summarize_by_time()` for a Sales Analysis\n",
+ "\n",
+ "Your company might be interested in sales patterns for various categories of bicycles. We can obtain a grouped monthly sales aggregation by `category_1` in two lines of code:\n",
+ "\n",
+ "1. First use pandas's `groupby()` method to group the DataFrame on `category_1`\n",
+ "2. Next, use timetk's `summarize_by_time()` method to apply the sum function my month start (\"MS\") and use `wide_format = 'False'` to return the dataframe in a long format (Note long format is the default). \n",
+ "\n",
+ "The result is the total revenue for Mountain and Road bikes by month. \n"
+ ],
+ "id": "77d83578"
+ },
+ {
+ "cell_type": "code",
+ "metadata": {},
+ "source": [
+ "summary_category_1_df = df \\\n",
+ " .groupby(\"category_1\") \\\n",
+ " .summarize_by_time(\n",
+ " date_column = 'order_date', \n",
+ " value_column = 'total_price',\n",
+ " freq = \"MS\",\n",
+ " agg_func = 'sum',\n",
+ " engine = \"polars\"\n",
+ " )\n",
+ "\n",
+ "# First 5 rows shown\n",
+ "summary_category_1_df.head()"
+ ],
+ "id": "73f70cb8",
+ "execution_count": null,
+ "outputs": []
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "### Visualizing Sales Patterns\n",
+ "\n",
+ "::: {.callout-note collapse=\"false\"}\n",
+ "## Now available: `plot_timeseries()`.\n",
+ "\n",
+ "Plot time series is a quick and easy way to visualize time series and make professional time series plots. \n",
+ ":::\n",
+ "\n",
+ "With the data summarized by time, we can visualize with `plot_timeseries()`. `pytimetk` functions are `groupby()` aware meaning they understand if your data is grouped to do things by group. This is useful in time series where we often deal with 100s of time series groups. \n"
+ ],
+ "id": "deb71506"
+ },
+ {
+ "cell_type": "code",
+ "metadata": {},
+ "source": [
+ "summary_category_1_df \\\n",
+ " .groupby('category_1') \\\n",
+ " .plot_timeseries(\n",
+ " date_column = 'order_date',\n",
+ " value_column = 'total_price',\n",
+ " smooth_frac = 0.8,\n",
+ " engine = \"plotnine\"\n",
+ " )"
+ ],
+ "id": "9e1cdcbf",
+ "execution_count": null,
+ "outputs": []
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "# π Documentation\n",
+ "\n",
+ "Next step? Learn more with the [pytimetk documentation](https://business-science.github.io/pytimetk/)\n",
+ "\n",
+ "- [π Overview](https://business-science.github.io/pytimetk/)\n",
+ "- [π Getting Started](https://business-science.github.io/pytimetk/getting-started/02_quick_start.html)\n",
+ "- [πΊοΈ Beginner Guides](https://business-science.github.io/pytimetk/guides/01_visualization.html)\n",
+ "- [πApplied Data Science Tutorials with PyTimeTK](https://business-science.github.io/pytimetk/tutorials/01_sales_crm.html)\n",
+ "- [ποΈSpeed Comparisons](https://business-science.github.io/pytimetk/performance/01_speed_comparisons.html)\n",
+ "- [π API Reference](https://business-science.github.io/pytimetk/reference/)\n",
+ "\n",
+ "# π» Contributing\n",
+ "\n",
+ "Interested in helping us make this the best Python package for time series analysis? We'd love your help. \n",
+ "\n",
+ "[Follow these instructions to Contribute.](/contributing.html)\n",
+ "\n",
+ "# π More Coming Soon...\n",
+ "\n",
+ "We are in the early stages of development. But it's obvious the potential for `pytimetk` now in Python. π\n",
+ "\n",
+ "- Please [β 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"
+ ],
+ "id": "3516333e"
+ }
+ ],
+ "metadata": {
+ "kernelspec": {
+ "name": "python3",
+ "language": "python",
+ "display_name": "Python 3 (ipykernel)"
+ }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}
\ No newline at end of file
diff --git a/docs/index.qmd b/docs/index.qmd
index fe3b4848..d3dd7374 100644
--- a/docs/index.qmd
+++ b/docs/index.qmd
@@ -110,7 +110,8 @@ summary_category_1_df = df \
value_column = 'total_price',
freq = "MS",
agg_func = 'sum',
- wide_format = False
+ wide_format = False,
+ # engine = "polars"
)
# First 5 rows shown
@@ -135,7 +136,8 @@ summary_category_1_df \
.plot_timeseries(
date_column = 'order_date',
value_column = 'total_price',
- smooth_frac = 0.8
+ smooth_frac = 0.8,
+ engine = "plotnine"
)
```
diff --git a/docs/index_files/execute-results/html.json b/docs/index_files/execute-results/html.json
new file mode 100644
index 00000000..47dc0eee
--- /dev/null
+++ b/docs/index_files/execute-results/html.json
@@ -0,0 +1,15 @@
+{
+ "hash": "c09375b4a33109b8fbc47186325c91ce",
+ "result": {
+ "markdown": "---\ntoc: true\ntoc-depth: 3\nnumber-sections: true\nnumber-depth: 2\ntitle: PyTimeTK \n---\n\n\n\n\n\n\n\n> Time series easier, faster, more fun. Pytimetk.\n\n**PyTimetk's Mission:** To make time series analysis easier, faster, and more enjoyable in Python.\n\n[**Please β 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\n| Features/Properties | **pytimetk** | **pandas (+matplotlib)** |\n|---------------------|-------------------------------|---------------------------------------|\n| **Speed** | π 3X to 500X Faster | π’ Standard |\n| **Code Simplicity** | π Concise, readable syntax | π Often verbose |\n| `plot_timeseries()` | π¨ 2 lines, no customization | π¨ 16 lines, customization needed |\n| `summarize_by_time()` | π 2 lines, 13.4X faster | π 6 lines, 2 for-loops |\n| `pad_by_time()` | β³ 2 lines, fills gaps in timeseries | β No equivalent |\n| `anomalize()` | π 2 lines, detects and corrects anomalies | β No equivalent |\n| `augment_timeseries_signature()` | π
1 line, all calendar features | π 30 lines of `dt` extractors |\n| `augment_rolling()` | ποΈ 10X to 3500X faster | π’ Slow Rolling Operations |\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:\n\n``` bash\npip install pytimetk\n```\n\nAlternatively, install the Development GitHub Version:\n\n```bash\npip install git+https://github.com/business-science/pytimetk.git\n```\n\n# π Quick Start: A Monthly Sales Analysis\n\nThis is a simple exercise to showcase the power of [`summarize_by_time()`](/reference/summarize_by_time.html):\n\n### Import Libraries & Data\n\nFirst, `import pytimetk as tk`. This gets you access to the most important functions. Use `tk.load_dataset()` to load the \"bike_sales_sample\" dataset.\n\n::: {.callout-note collapse=\"false\"}\n## About the Bike Sales Sample Dataset\n\nThis dataset contains \"orderlines\" for orders recieved. The `order_date` column contains timestamps. We can use this column to peform sales aggregations (e.g. total revenue).\n:::\n\n\n::: {.cell execution_count=1}\n``` {.python .cell-code}\nimport pytimetk as tk\nimport pandas as pd\n\ndf = tk.load_dataset('bike_sales_sample')\ndf['order_date'] = pd.to_datetime(df['order_date'])\n\ndf \n```\n\n::: {.cell-output .cell-output-display execution_count=1}\n```{=html}\n\n\n\n \n
\n
\n```\n:::\n:::\n\n\n### Using `summarize_by_time()` for a Sales Analysis\n\nYour company might be interested in sales patterns for various categories of bicycles. We can obtain a grouped monthly sales aggregation by `category_1` in two lines of code:\n\n1. First use pandas's `groupby()` method to group the DataFrame on `category_1`\n2. Next, use timetk's `summarize_by_time()` method to apply the sum function my month start (\"MS\") and use `wide_format = 'False'` to return the dataframe in a long format (Note long format is the default). \n\nThe result is the total revenue for Mountain and Road bikes by month. \n\n::: {.cell execution_count=2}\n``` {.python .cell-code}\nsummary_category_1_df = df \\\n .groupby(\"category_1\") \\\n .summarize_by_time(\n date_column = 'order_date', \n value_column = 'total_price',\n freq = \"MS\",\n agg_func = 'sum',\n wide_format = False\n )\n\n# First 5 rows shown\nsummary_category_1_df.head()\n```\n\n::: {.cell-output .cell-output-display execution_count=2}\n```{=html}\n| \n | order_id | \norder_line | \norder_date | \nquantity | \nprice | \ntotal_price | \nmodel | \ncategory_1 | \ncategory_2 | \nframe_material | \nbikeshop_name | \ncity | \nstate | \n
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 0 | \n1 | \n1 | \n2011-01-07 | \n1 | \n6070 | \n6070 | \nJekyll Carbon 2 | \nMountain | \nOver Mountain | \nCarbon | \nIthaca Mountain Climbers | \nIthaca | \nNY | \n
| 1 | \n1 | \n2 | \n2011-01-07 | \n1 | \n5970 | \n5970 | \nTrigger Carbon 2 | \nMountain | \nOver Mountain | \nCarbon | \nIthaca Mountain Climbers | \nIthaca | \nNY | \n
| 2 | \n2 | \n1 | \n2011-01-10 | \n1 | \n2770 | \n2770 | \nBeast of the East 1 | \nMountain | \nTrail | \nAluminum | \nKansas City 29ers | \nKansas City | \nKS | \n
| 3 | \n2 | \n2 | \n2011-01-10 | \n1 | \n5970 | \n5970 | \nTrigger Carbon 2 | \nMountain | \nOver Mountain | \nCarbon | \nKansas City 29ers | \nKansas City | \nKS | \n
| 4 | \n3 | \n1 | \n2011-01-10 | \n1 | \n10660 | \n10660 | \nSupersix Evo Hi-Mod Team | \nRoad | \nElite Road | \nCarbon | \nLouisville Race Equipment | \nLouisville | \nKY | \n
| ... | \n... | \n... | \n... | \n... | \n... | \n... | \n... | \n... | \n... | \n... | \n... | \n... | \n... | \n
| 2461 | \n321 | \n3 | \n2011-12-22 | \n1 | \n1410 | \n1410 | \nCAAD8 105 | \nRoad | \nElite Road | \nAluminum | \nMiami Race Equipment | \nMiami | \nFL | \n
| 2462 | \n322 | \n1 | \n2011-12-28 | \n1 | \n1250 | \n1250 | \nSynapse Disc Tiagra | \nRoad | \nEndurance Road | \nAluminum | \nPhoenix Bi-peds | \nPhoenix | \nAZ | \n
| 2463 | \n322 | \n2 | \n2011-12-28 | \n1 | \n2660 | \n2660 | \nBad Habit 2 | \nMountain | \nTrail | \nAluminum | \nPhoenix Bi-peds | \nPhoenix | \nAZ | \n
| 2464 | \n322 | \n3 | \n2011-12-28 | \n1 | \n2340 | \n2340 | \nF-Si 1 | \nMountain | \nCross Country Race | \nAluminum | \nPhoenix Bi-peds | \nPhoenix | \nAZ | \n
| 2465 | \n322 | \n4 | \n2011-12-28 | \n1 | \n5860 | \n5860 | \nSynapse Hi-Mod Dura Ace | \nRoad | \nEndurance Road | \nCarbon | \nPhoenix Bi-peds | \nPhoenix | \nAZ | \n
2466 rows Γ 13 columns
\n\n\n\n \n
\n
\n```\n:::\n:::\n\n\n### Visualizing Sales Patterns\n\n::: {.callout-note collapse=\"false\"}\n## Now available: `plot_timeseries()`.\n\nPlot time series is a quick and easy way to visualize time series and make professional time series plots. \n:::\n\nWith the data summarized by time, we can visualize with `plot_timeseries()`. `pytimetk` functions are `groupby()` aware meaning they understand if your data is grouped to do things by group. This is useful in time series where we often deal with 100s of time series groups. \n\n::: {.cell execution_count=3}\n``` {.python .cell-code}\nsummary_category_1_df \\\n .groupby('category_1') \\\n .plot_timeseries(\n date_column = 'order_date',\n value_column = 'total_price',\n smooth_frac = 0.8\n )\n```\n\n::: {.cell-output .cell-output-display}\n```{=html}\n| \n | category_1 | \norder_date | \ntotal_price | \n
|---|---|---|---|
| 0 | \nMountain | \n2011-01-01 | \n221490 | \n
| 1 | \nMountain | \n2011-02-01 | \n660555 | \n
| 2 | \nMountain | \n2011-03-01 | \n358855 | \n
| 3 | \nMountain | \n2011-04-01 | \n1075975 | \n
| 4 | \nMountain | \n2011-05-01 | \n450440 | \n