Metadata-Version: 2.1
Name: functime
Version: 0.8.5
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Scientific/Engineering
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Requires-Dist: dask
Requires-Dist: bottleneck
Requires-Dist: flaml >=2.0.2, <3
Requires-Dist: holidays
Requires-Dist: numpy
Requires-Dist: polars >=0.19.11
Requires-Dist: scikit-learn >=1.2.2, <2
Requires-Dist: scipy
Requires-Dist: tqdm
Requires-Dist: typing-extensions
Requires-Dist: zarr
Requires-Dist: pylance ; extra == 'ann'
Requires-Dist: pyarrow ; extra == 'ann'
Requires-Dist: catboost ; extra == 'cat'
Requires-Dist: xgboost ; extra == 'xgb'
Requires-Dist: pyarrow ; extra == 'xgb'
Requires-Dist: lightgbm ; extra == 'lgb'
Requires-Dist: openai ; extra == 'llm'
Requires-Dist: tabulate ; extra == 'llm'
Requires-Dist: tenacity ; extra == 'llm'
Requires-Dist: tiktoken ; extra == 'llm'
Requires-Dist: pandas ; extra == 'plot'
Requires-Dist: plotly ; extra == 'plot'
Requires-Dist: kaleido ==0.2.1 ; extra == 'plot'
Requires-Dist: pre-commit ; extra == 'dev'
Requires-Dist: aeon ; extra == 'test'
Requires-Dist: coverage[toml] ; extra == 'test'
Requires-Dist: fastapi ; extra == 'test'
Requires-Dist: joblib ; extra == 'test'
Requires-Dist: mlforecast ==0.8.1 ; extra == 'test'
Requires-Dist: pandas ; extra == 'test'
Requires-Dist: pytest-benchmark ; extra == 'test'
Requires-Dist: pytest-memray ; extra == 'test'
Requires-Dist: pytest-timeout ; extra == 'test'
Requires-Dist: pytest ; extra == 'test'
Requires-Dist: scikit-learn-intelex ; extra == 'test'
Requires-Dist: statsmodels ; extra == 'test'
Requires-Dist: tsfresh ; extra == 'test'
Requires-Dist: mkdocs ; extra == 'doc'
Requires-Dist: mkdocs-material ; extra == 'doc'
Requires-Dist: mkdocstrings-python ; extra == 'doc'
Requires-Dist: mkdocs-jupyter ; extra == 'doc'
Provides-Extra: ann
Provides-Extra: cat
Provides-Extra: xgb
Provides-Extra: lgb
Provides-Extra: llm
Provides-Extra: plot
Provides-Extra: dev
Provides-Extra: test
Provides-Extra: doc
License-File: LICENSE
Summary: Time-series machine learning at scale.
Author-email: functime Team <team@functime.ai>, Chris Lo <chris@functime.ai>, Daryl Lim <daryl@functime.ai>
Requires-Python: >=3.8
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Homepage, https://github.com/neocortexdb/functime

<div align="center">
    <h1>Time-series machine learning at scale</h1>
<br />

![functime](https://github.com/neocortexdb/functime/raw/main/docs/img/banner_dark_bg.png)
[![Python](https://img.shields.io/pypi/pyversions/functime)](https://pypi.org/project/functime/)
[![PyPi](https://img.shields.io/pypi/v/functime?color=blue)](https://pypi.org/project/functime/)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
[![GitHub Publish to PyPI](https://github.com/neocortexdb/functime/actions/workflows/publish.yml/badge.svg)](https://github.com/neocortexdb/functime/actions/workflows/publish.yml)
[![GitHub Run Quickstart](https://github.com/neocortexdb/functime/actions/workflows/quickstart.yml/badge.svg)](https://github.com/neocortexdb/functime/actions/workflows/quickstart.yml)
[![Discord](https://img.shields.io/discord/1145819725276917782)](https://discord.gg/JKMrZKjEwN)

</div>

---
**functime** is a powerful [Python library](https://pypi.org/project/functime/) for production-ready **global forecasting** and **time-series feature extraction** on **large panel datasets**.

**functime** also comes with time-series [preprocessing](https://docs.functime.ai/ref/preprocessing/) (box-cox, differencing etc), cross-validation [splitters](https://docs.functime.ai/ref/cross-validation/) (expanding and sliding window), and forecast [metrics](https://docs.functime.ai/ref/metrics/) (MASE, SMAPE etc). All optimized as [lazy Polars](https://pola-rs.github.io/polars-book/user-guide/lazy/using/) transforms.

Join us on [Discord](https://discord.gg/JKMrZKjEwN)!

## Highlights
- **Fast:** Forecast and extract features (e.g. tsfresh, Catch22) across 100,000 time series in seconds *on your laptop*
- **Efficient:** Embarrassingly parallel [feature engineering](https://docs.functime.ai/ref/preprocessing/) for time-series using [`Polars`](https://www.pola.rs/)
- **Battle-tested:** Machine learning algorithms that deliver real business impact and win competitions
- **Exogenous features:** supported by every forecaster
- **Backtesting** with expanding window and sliding window splitters
- **Automated lags and hyperparameter tuning** using [`FLAML`](https://github.com/microsoft/FLAML)

## Additional Highlights
`functime` comes with a specialized LLM agent to analyze, describe, and compare your forecasts. Check out the walkthrough [here](https://docs.functime.ai/notebooks/llm/).

## Getting Started
Install `functime` via the [pip](https://pypi.org/project/functime) package manager.
```bash
pip install functime
```

`functime` comes with extra options. For example, to install `functime` with large-language model (LLM) and lightgbm features:

```bash
pip install "functime[llm,lgb]"
```

- `cat`: To use `catboost` forecaster
- `xgb`: To use `xgboost` forecaster
- `lgb`: To use `lightgbm` forecaster
- `llm`: To use the LLM-powered forecast analyst

### Forecasting

```python
import polars as pl
from functime.cross_validation import train_test_split
from functime.feature_extraction import add_fourier_terms
from functime.forecasting import linear_model
from functime.preprocessing import scale
from functime.metrics import mase

# Load commodities price data
y = pl.read_parquet("https://github.com/neocortexdb/functime/raw/main/data/commodities.parquet")
entity_col, time_col = y.columns[:2]

# Time series split
y_train, y_test = y.pipe(train_test_split(test_size=3))

# Fit-predict
forecaster = linear_model(freq="1mo", lags=24)
forecaster.fit(y=y_train)
y_pred = forecaster.predict(fh=3)

# functime ❤️ functional design
# fit-predict in a single line
y_pred = linear_model(freq="1mo", lags=24)(y=y_train, fh=3)

# Score forecasts in parallel
scores = mase(y_true=y_test, y_pred=y_pred, y_train=y_train)

# Forecast with target transforms and feature transforms
forecaster = linear_model(
    freq="1mo",
    lags=24,
    target_transform=scale(),
    feature_transform=add_fourier_terms(sp=12, K=6)
)

# Forecast with exogenous regressors!
# Just pass them into X
X = (
    y.select([entity_col, time_col])
    .pipe(add_fourier_terms(sp=12, K=6)).collect()
)
X_train, X_future = y.pipe(train_test_split(test_size=3))
forecaster = linear_model(freq="1mo", lags=24)
forecaster.fit(y=y_train, X=X_train)
y_pred = forecaster.predict(fh=3, X=X_future)
```

View the full walkthrough on forecasting [here](https://docs.functime.ai/forecasting/).

## LLM Copilot

Requires an OpenAI API key set as an environment variable `OPENAI_API_KEY`.

```python
import polars as pl
import functime.llm

y = pl.read_parquet("../../data/commodities.parquet")
context = "This dataset comprises of historical commodity prices between 1980 to 2022."

# Analyze trend and seasonality for two commodities
analysis = y_pred.llm.analyze(
    context=dataset_context,
    basket=["Aluminum", "Banana, Europe"]
)
print("📊 Analysis:\n", analysis)

# Compare two baskets of commodities!
basket_a = ["Aluminum", "Banana, Europe"]
basket_b = ["Chicken", "Cocoa"]
comparison = y_pred.llm.compare(
    basket=basket_a,
    other_basket=basket_b
)
print("📊 Comparison:\n", comparison)
```

View the full walkthrough on the LLM copilot [here](https://docs.functime.ai/notebooks/llm/).

## License
`functime` is distributed under [Apache-2.0](LICENSE).

