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

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:

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 (mlnjsh@gmail.com)

GitHub: github.com/mlnjsh/timesage