Farseer - Forecasting at Scale, Powered by Rust
Description: High-performance time series forecasting library built in Rust with Python bindings. Prophet-like forecasting with the speed and reliability of Rust.

## Why Farseer?

🚀

### Blazing Fast

Rust-powered performance with automatic multithreading. Get forecasts in seconds, 5-10x faster than Prophet.

🎯

### Accurate & Robust

Bayesian approach with uncertainty intervals. Handles missing data, outliers, and trend shifts automatically.

⚖️

### Weighted Observations

Native support for observation weights. Emphasize recent data or downweight outliers with ease.

📊

### Polars & Pandas

Works with both Polars (recommended, 5-10x faster) and Pandas DataFrames for backward compatibility.

🔧

### Fully Tunable

Multiple trend types, custom seasonality, holiday effects, and regressors. Add your domain knowledge.

🔄

### Prophet Compatible

Nearly identical API to Prophet. Migrate your existing code with minimal changes.

## Farseer vs Prophet

Feature | Farseer | Prophet
--- | --- | ---
Performance | Rust-powered, 5-10x faster | Python/Stan
Multithreading | Automatic parallel optimization | Single-threaded by default
Weighted Data | Native support | Not directly supported
DataFrames | Polars + Pandas | Pandas only
Deployment | Minimal dependencies | Requires Stan, PyStan
API | Scikit-learn-like, Prophet-compatible | Scikit-learn-like

## Quick Start

### Installation

    # From PyPI (when published)
    pip install farseer

    # Development install from source
    git clone https://github.com/ryanbieber/seer
    cd seer
    export PYO3_USE_ABI3_FORWARD_COMPATIBILITY=1  # For Python 3.13+
    maturin develop --release

### Basic Usage (Polars - Recommended)

    from farseer import Farseer
    import polars as pl
    from datetime import datetime

    # Create data
    df = pl.DataFrame({
        'ds': pl.date_range(
            datetime(2020, 1, 1),
            periods=100,
            interval='1d',
            eager=True
        ),
        'y': range(100)
    })

    # Fit and forecast
    m = Farseer()
    m.fit(df)
    future = m.make_future_dataframe(periods=30)
    forecast = m.predict(future)

    print(forecast.select(['ds', 'yhat', 'yhat_lower', 'yhat_upper']).tail())

### Prophet-Compatible (Pandas)

    from farseer import Farseer
    import pandas as pd

    # Create data
    df = pd.DataFrame({
        'ds': pd.date_range('2020-01-01', periods=100),
        'y': range(100)
    })

    # Fit and forecast - same API!
    m = Farseer()
    m.fit(df)
    future = m.make_future_dataframe(periods=30)
    forecast = m.predict(future)

    print(forecast[['ds', 'yhat', 'yhat_lower', 'yhat_upper']].tail())

## Examples

### 🎯 Weighted Observations

Give more importance to recent or reliable data

    import polars as pl
    import numpy as np
    from farseer import Farseer

    df = pl.DataFrame({
        'ds': pl.date_range(...),
        'y': np.random.randn(100).cumsum() + 50,
        'weight': [2.0 if i < 50 else 1.0 for i in range(100)]
    })

    # Weights automatically detected!
    m = Farseer()
    m.fit(df)

Learn more →

### 📈 Custom Regressors

Add additional variables to improve forecasts

    from farseer import Farseer

    m = Farseer()

    # Add custom regressors
    m.add_regressor('temperature', prior_scale=10.0)
    m.add_regressor('is_weekend', mode='additive')
    m.add_regressor('promo', prior_scale=5.0)

    m.fit(train_df)
    forecast = m.predict(test_df)

Learn more →

### 🔄 Manual Changepoints

Specify known trend changes in your data

    from farseer import Farseer

    # Specify exact changepoint dates
    changepoints = ['2021-01-01', '2022-01-01']

    m = Farseer(
        changepoints=changepoints,
        yearly_seasonality=True
    )

    m.fit(df)
    forecast = m.predict(future)

Learn more →

### 🎄 Holiday Effects

Model special events and holidays

    import polars as pl
    from farseer import Farseer

    holidays = pl.DataFrame({
        'ds': pl.date_range(...),
        'holiday': ['Christmas', 'New Year', ...],
        'lower_window': 0,
        'upper_window': 1
    })

    m = Farseer(holidays=holidays)
    m.fit(df)

Learn more →

## Documentation

📦

### Installation

Get started with Farseer on your system

⚡

### Quick Start Guide

Learn the basics in 5 minutes

📚

### API Reference

Complete API documentation

💡

### Examples & Tutorials

Learn from real-world examples

🔄

### Migrating from Prophet

Switch from Prophet to Farseer

🚀

### Performance Guide

Optimize your forecasting workflow

## Ready to get started?

Start forecasting with the speed and reliability of Rust

Get Started Now Star on GitHub