timesage-ts 0.2.1

The Wise Time Series Library - Beautiful EDA, All Models, Plain-English Interpretation

TimeSage

The Wise Time Series Library

Beautiful EDA · All Models · Plain-English Interpretation

---

TimeSage makes time series forecasting effortless. Go from raw data to a forecast with plain-English interpretation in just a few lines of Python.

Features

• 3-Line Forecasting -- Load data, call forecast(), done. TimeSage handles model selection, feature engineering, and evaluation automatically.
• Plain-English Interpretation -- Call result.interpret() and get a human-readable explanation of accuracy, error patterns, key drivers, and forecast direction.
• Beautiful Plots -- Publication-ready visualizations with a custom Sage theme. Decomposition plots, forecast overlays, diagnostics, and more.
• All Models, One API -- ARIMA, ETS, Theta, Random Forest, XGBoost, and LightGBM all share the same series.forecast(model="...") interface.
• Smart EDA -- Automated exploratory data analysis with series.eda(): stationarity tests, seasonality detection, decomposition, and descriptive statistics.
• Automatic Feature Engineering -- ML models get lag features, rolling statistics, and calendar features created automatically. No manual work required.

Installation

Basic (statistical models + Random Forest)

pip install timesage-ts

Full (adds XGBoost, LightGBM, Plotly)

pip install timesage-ts[full]

Optional extras

pip install timesage-ts[ml]           # XGBoost + LightGBM only
pip install timesage-ts[interactive]  # Plotly interactive charts

Requirements: Python 3.9+

Quick Start

import timesage as ts

# 1. Create a TimeSeries from your data
series = ts.TimeSeries(df, target="sales", time="date", freq="D")

# 2. Explore your data
series.eda()

# 3. Forecast the next 30 days (auto-selects the best model)
result = series.forecast(horizon=30)

# 4. Get a plain-English interpretation
result.interpret()

# 5. Plot the forecast
result.plot()

What interpret() prints

Forecast Interpretation
=======================
Overall accuracy : Excellent (MAPE = 3.2%)
Error consistency: Errors are uniform -- no major outlier spikes.
vs. Naive baseline: Model is 2.4x better than a naive repeat-last-value forecast.
Forecast trend  : Upward -- the series is predicted to increase over the horizon.

Available Models

Model	Key	Type	Install
ARIMA (Auto)	"arima"	Statistical	Core
ETS (Holt-Winters)	"ets"	Statistical	Core
Theta	"theta"	Statistical	Core
Random Forest	"rf"	Machine Learning	Core
XGBoost	"xgboost"	Machine Learning	pip install timesage-ts[ml]
LightGBM	"lightgbm"	Machine Learning	pip install timesage-ts[ml]
Auto (best of all)	"auto"	Automatic	Core

Use any model with the same interface:

result = series.forecast(horizon=30, model="arima")
result = series.forecast(horizon=30, model="xgboost")
result = series.forecast(horizon=30, model="auto")     # default

Comparing models

comparison = series.compare_models(test_size=0.2)

This runs every available model, evaluates each on a held-out test set, and returns a ranked DataFrame with MAE, RMSE, MAPE, and training time.

EDA in One Line

series.eda()

This runs:

• Descriptive statistics (mean, std, min, max, skew, kurtosis)
• Stationarity testing (Augmented Dickey-Fuller)
• Seasonality detection (autocorrelation analysis)
• Trend-seasonal decomposition
• Distribution and time plot visualizations

Documentation

Full documentation is available in the docs/ folder:

Document	Description
Getting Started	Installation, first forecast, core workflow
User Guide	Detailed tutorials and common workflows
Models	Deep dive into every forecasting model
Features	Feature engineering and data handling
Plotting	Visualization guide and theme customization
Interpretation	How plain-English interpretation works
API Reference	Complete class and method reference
Examples	Real-world use cases with full code
FAQ	Frequently asked questions

Color Palette

TimeSage uses a carefully chosen color palette for all visualizations:

Color	Hex	Usage
Ocean Blue	#2E86AB	Primary -- forecasts, main series
Berry	#A23B72	Secondary -- actuals, comparisons
Amber	#F18F01	Accent -- confidence intervals, highlights
Sage Green	#2BA84A	Success -- good metrics, positive trends
Coral Red	#E63946	Danger -- warnings, poor metrics

Switch themes with:

import timesage as ts
ts.set_theme("sage")     # Default sage theme
ts.set_theme("dark")     # Dark mode
ts.set_theme("minimal")  # Clean minimal

License

MIT License. See LICENSE for details.

Author

Milan Amrut Joshi ([e-mail])

GitHub: github.com/mlnjsh/timesage