API Reference

from farseer import Farseer

# Basic initialization
m = Farseer()

# Custom initialization
m = Farseer(
    growth='logistic',
    yearly_seasonality=True,
    weekly_seasonality=False,
    changepoint_prior_scale=0.1,
    seasonality_mode='multiplicative',
    interval_width=0.95
)

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

# Create data
dates = [datetime(2020, 1, 1) + timedelta(days=i) for i in range(100)]
df = pl.DataFrame({
    'ds': dates,
    'y': list(range(100))
})

# Fit model
m = Farseer()
m.fit(df)

# With optional columns
df_with_extras = pl.DataFrame({
    'ds': dates,
    'y': values,
    'cap': 200.0,        # For logistic growth
    'floor': 10.0,       # Minimum value
    'weight': weights,   # Observation weights
    'temperature': temps # Regressor
})

m = Farseer(growth='logistic')
m.add_regressor('temperature')
m.fit(df_with_extras)

from farseer import Farseer

m = Farseer()
m.fit(train_df)

# Predict on future dates
future = m.make_future_dataframe(periods=30)
forecast = m.predict(future)

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

from farseer import Farseer

m = Farseer()
m.fit(df)

# 30 days ahead (daily frequency)
future_daily = m.make_future_dataframe(periods=30, freq='D')

# 12 weeks ahead (weekly frequency)
future_weekly = m.make_future_dataframe(periods=12, freq='W')

# 6 months ahead (monthly frequency, ~30 days)
future_monthly = m.make_future_dataframe(periods=6, freq='M')

# Future only (no history)
future_only = m.make_future_dataframe(periods=30, include_history=False)

from farseer import Farseer

m = Farseer()

# Add monthly seasonality
m.add_seasonality(name='monthly', period=30.5, fourier_order=5)

# Add quarterly seasonality with custom prior
m.add_seasonality(
    name='quarterly',
    period=91.25,
    fourier_order=8,
    prior_scale=15.0,
    mode='multiplicative'
)

# Add conditional seasonality (weekday pattern)
m.add_seasonality(
    name='weekly_on_weekday',
    period=7,
    fourier_order=3,
    condition_name='is_weekday'
)

# Add condition column to data
df = df.with_columns((pl.col('ds').dt.weekday() < 5).alias('is_weekday'))
m.fit(df)

from farseer import Farseer

m = Farseer()

# Binary regressor (auto mode won't standardize)
m.add_regressor('is_weekend', standardize='auto')

# Continuous regressor (auto mode will standardize)
m.add_regressor('temperature', standardize='auto', prior_scale=10.0)

# Force standardization
m.add_regressor('sales', standardize='true', prior_scale=5.0)

# No standardization
m.add_regressor('pre_scaled_feature', standardize='false')

# Must have regressor columns in dataframe
df = pl.DataFrame({
    'ds': dates,
    'y': values,
    'is_weekend': [0, 1, 0, ...],
    'temperature': [15.2, 18.4, ...],
    'sales': [100, 150, ...],
    'pre_scaled_feature': [0.5, 0.7, ...]
})

m.fit(df)

from farseer import Farseer
from datetime import datetime

m = Farseer()

# Major holiday with strong effect
m.add_holidays(
    'christmas',
    dates=[
        datetime(2020, 12, 25),
        datetime(2021, 12, 25),
        datetime(2022, 12, 25)
    ],
    prior_scale=20.0,
    lower_window=-1,  # Day before
    upper_window=1    # Day after
)

# Minor holiday with weak effect
m.add_holidays(
    'minor_event',
    dates=['2020-03-17', '2021-03-17'],
    prior_scale=5.0
)

# Using date strings
m.add_holidays(
    'new_year',
    dates=['2021-01-01', '2022-01-01', '2023-01-01'],
    prior_scale=10.0
)

m.fit(df)

from farseer import Farseer

m = Farseer()
m.fit(df)

# Save model
m.save('my_model.json')

from farseer import Farseer

# Load saved model
m = Farseer.load('my_model.json')

# Make predictions with loaded model
future = m.make_future_dataframe(periods=30)
forecast = m.predict(future)

# Note: Loaded models may require pandas DataFrames
# due to PyO3 serialization limitations
import pandas as pd
future_pd = future.to_pandas()
forecast = m.predict(future_pd)

from farseer import Farseer

m = Farseer()
m.fit(df)

# Get JSON string
json_str = m.to_json()
print(json_str[:100])  # First 100 characters

from farseer import Farseer

# Serialize
m = Farseer()
m.fit(df)
json_str = m.to_json()

# Deserialize
m_loaded = Farseer.from_json(json_str)
forecast = m_loaded.predict(future)

from farseer import Farseer, regressor_coefficients

m = Farseer()
m.add_regressor('temperature')
m.add_regressor('is_weekend')
m.fit(df)

# Get coefficients
coeffs = regressor_coefficients(m)
print(coeffs)

# Output:
# shape: (2, 4)
# ┌─────────────┬─────────────┬──────┬──────┐
# │ regressor   ┆ coefficient ┆ mu   ┆ std  │
# ├─────────────┼─────────────┼──────┼──────┤
# │ temperature ┆ 0.523       ┆ 15.2 ┆ 5.3  │
# │ is_weekend  ┆ -10.234     ┆ 0.0  ┆ 1.0  │
# └─────────────┴─────────────┴──────┴──────┘

from farseer import Farseer

m = Farseer()
m.fit(df)

# Get parameters
params = m.params()
print(f"Trend slope (k): {params['k']}")
print(f"Trend offset (m): {params['m']}")
print(f"Observation noise (sigma_obs): {params['sigma_obs']}")
print(f"Fitted: {params['fitted']}")
print(f"Logistic floor used: {params.get('logistic_floor', False)}")