Quick Start

Installation

pip install durbyn

For all optional dependencies (pandas + matplotlib):

pip install durbyn[all]

Setup

durbyn uses juliacall to run Julia code. Julia is initialised lazily on the first .fit() call — there is a one-time startup cost (~10-30 seconds) while Julia compiles Durbyn.jl.

Local Development

To use a local copy of Durbyn.jl instead of the registered package, set the environment variable:

export DURBYN_JL_PATH=/path/to/Durbyn.jl

---

Example 1: Simple Exponential Smoothing

import numpy as np
from durbyn import SES

# Sample data
y = [112, 118, 132, 129, 121, 135, 148, 148, 136, 119, 104, 118,
     115, 126, 141, 135, 125, 149, 170, 170, 158, 133, 114, 140]

# Fit and forecast
model = SES().fit(y, m=12)
fc = model.forecast(h=12, level=[80, 95])

print(fc)
# ForecastResult(h=12, method='SES', level=[80, 95])

print(fc.mean)
# array([...])  — 12-step-ahead point forecasts

---

Example 2: Automatic ARIMA

from durbyn import AutoARIMA

y = [112, 118, 132, 129, 121, 135, 148, 148, 136, 119, 104, 118,
     115, 126, 141, 135, 125, 149, 170, 170, 158, 133, 114, 140,
     145, 150, 178, 163, 172, 178, 199, 199, 184, 162, 146, 166]

model = AutoARIMA(stepwise=True).fit(y, m=12)
fc = model.forecast(h=12, level=[80, 95])

# Convert to pandas DataFrame
print(fc.to_dataframe())
#     step        mean     lower_80     upper_80     lower_95     upper_95
# 0      1  168.123456  155.234567  181.012345  148.345678  187.901234
# 1      2  170.456789  154.567890  186.345678  146.678901  194.234567
# ...

---

Example 3: Holt-Winters with Plotting

from durbyn import HoltWinters

y = [112, 118, 132, 129, 121, 135, 148, 148, 136, 119, 104, 118,
     115, 126, 141, 135, 125, 149, 170, 170, 158, 133, 114, 140,
     145, 150, 178, 163, 172, 178, 199, 199, 184, 162, 146, 166]

model = HoltWinters(seasonal="multiplicative").fit(y, m=12)
fc = model.forecast(h=12, level=[80, 95])

# Plot with matplotlib
fc.plot(show_history=True)

---

Example 4: ETS with Automatic Model Selection

from durbyn import ETS

y = [112, 118, 132, 129, 121, 135, 148, 148, 136, 119, 104, 118,
     115, 126, 141, 135, 125, 149, 170, 170, 158, 133, 114, 140]

# "ZZZ" = auto-select error, trend, and seasonal components
model = ETS(model="ZZZ").fit(y, m=12)
fc = model.forecast(h=12)

print(model.summary)   # Detailed model summary
print(model.residuals)  # In-sample residuals

---

Example 5: Model Comparison

from durbyn import SES, Holt, HoltWinters, ETS, AutoARIMA, compare

y = [112, 118, 132, 129, 121, 135, 148, 148, 136, 119, 104, 118,
     115, 126, 141, 135, 125, 149, 170, 170, 158, 133, 114, 140,
     145, 150, 178, 163, 172, 178, 199, 199, 184, 162, 146, 166]

# Split into train/test
y_train, y_test = y[:24], y[24:]

# Compare models
result = compare(
    models={
        "SES": SES(),
        "Holt": Holt(damped=True),
        "HW": HoltWinters(seasonal="multiplicative"),
        "ETS": ETS(model="ZZZ"),
        "AutoARIMA": AutoARIMA(),
    },
    y_train=y_train,
    y_test=y_test,
    m=12,
)

# Results as DataFrame
print(result.to_dataframe())
#             ME       RMSE       MAE       MPE      MAPE      ACF1      MASE
# SES       ...        ...       ...       ...       ...       ...       ...
# Holt      ...        ...       ...       ...       ...       ...       ...
# HW        ...        ...       ...       ...       ...       ...       ...
# ...

# Overlay all forecasts
result.plot()

---

Example 6: Panel Data (Grouped Forecasting)

import pandas as pd
from durbyn import AutoARIMA, PanelForecaster

# Example panel data
data = pd.DataFrame({
    "group": ["A"] * 36 + ["B"] * 36,
    "date": list(range(36)) * 2,
    "y": list(range(36)) + [x * 1.5 for x in range(36)],
})

# Fit one model template per group
pf = PanelForecaster(model=AutoARIMA(), groupby="group")
pf.fit(data, y_col="y", m=12, date_col="date")

# Forecast all groups
result = pf.forecast(h=12, level=[80, 95])

# Long-format DataFrame
print(result.to_dataframe())

---

Common Workflow

All models in durbyn follow the same pattern:

from durbyn import SomeModel

# 1. Create the model with configuration
model = SomeModel(param1=value1, param2=value2)

# 2. Fit to data
model.fit(y, m=seasonal_period)

# 3. Forecast
fc = model.forecast(h=steps_ahead, level=[80, 95])

# 4. Access results
fc.mean              # np.ndarray — point forecasts
fc.lower             # dict — {80: np.ndarray, 95: np.ndarray}
fc.upper             # dict — {80: np.ndarray, 95: np.ndarray}
fc.fitted_values     # np.ndarray — in-sample fitted values
fc.residuals         # np.ndarray — in-sample residuals
fc.method            # str — model description

# 5. Output
fc.to_dataframe()    # pandas DataFrame
fc.plot()            # matplotlib figure

# 6. Model inspection
model.fitted_values  # np.ndarray
model.residuals      # np.ndarray
model.summary        # str — detailed model summary
model.get_params()   # dict — model configuration

---

Next Steps

• User Guide — Detailed documentation for each model family
• API Reference — Complete parameter documentation
• Metrics — Forecast accuracy metrics