Orbit: Bayesian Time Series Modeling

Orbit provides an initialize-fit-predict interface. The following example demonstrates a full Bayesian prediction using the DLT model with regressors and seasonality.

Key steps:

1. Load your dataset.
2. Split data into training and testing sets.
3. Initialize the DLT model specifying response_col, date_col, regressor_col, and seasonality.
4. Call .fit(df=train_df) to train the model.
5. Call .predict(df=test_df) to generate predictions.
6. Use plot_predicted_data to visualize the results.

from orbit.utils.dataset import load_iclaims
from orbit.models import DLT
from orbit.diagnostics.plot import plot_predicted_data

# log-transformed data
df = load_iclaims()
# train-test split
test_size = 52
train_df = df[:-test_size]
test_df = df[-test_size:]

dlt = DLT(
  response_col='claims', date_col='week',
  regressor_col=['trend.unemploy', 'trend.filling', 'trend.job'],
  seasonality=52,
)
dlt.fit(df=train_df)

# outcomes data frame
predicted_df = dlt.predict(df=test_df)

plot_predicted_data(
  training_actual_df=train_df, predicted_df=predicted_df,
  date_col=dlt.date_col, actual_col=dlt.response_col,
  test_actual_df=test_df
)

Orbit's architecture (as of v1.1.0) is composed of three primary interacting components:

1. Forecaster: The top-level interface for users to perform fit and predict tasks. It handles the execution flow and supports different methodologies:
   • MAP (Maximum a posterior): Yields point posterior estimates via get_point_posterior().
   • SVI (Stochastic Variational Inference): Allows posterior sample extraction via get_posteriors().
   • Full Bayesian: Allows posterior sample extraction via get_posteriors().
   • Note: You can approximate point estimates in SVI/Full Bayesian by passing point_method='median' to the .fit() method.
2. Model: An object inheriting from ModelTemplate. It defines the model structure, parameters, likelihoods, and inputs. It turns the logic of fit() and predict() concrete by supplying a fitter (either a file like CmdStanPy or a callable class like Pyro) and an internal predict() method.
3. Estimator: The component that implements specific APIs for sampling or optimization (e.g., PyroEstimator or StanEstimator). It acts as the bridge between the Forecaster and the underlying probabilistic programming library.

To use a Forecaster, you must provide it with a Model and an Estimator object.

Once you have defined a custom Model class, you use a Forecaster to perform the actual fitting and prediction. The choice of Forecaster depends on your model's backend (e.g., use SVIForecaster for Pyro-based models).

Workflow

1. Instantiate the Model: Pass configuration parameters like regressor_col.
2. Instantiate the Forecaster: Provide the model, response_col, date_col, and the appropriate estimator_type.
3. Fit: Call .fit(train_df).
4. Predict: Call .predict(df) to get forecasts.
5. Extract Posteriors: Use .get_posterior_samples() to access the sampled parameters.

Example

# 1. Initialize custom model
model = BayesLinearRegression(regressor_col=['x1','x2'])

# 2. Initialize Forecaster (using SVI for Pyro)
blr = SVIForecaster(
    model=model,
    response_col='y', 
    date_col='week',
    estimator_type=PyroEstimatorSVI,
    verbose=True,
    num_steps=501,
    seed=2021,
)

# 3. Fit the model
blr.fit(train_df)

# 4. Predict
predicted_df = blr.predict(df)

# 5. Access posterior samples
weights = blr.get_posterior_samples()['weight']

model = BayesLinearRegression(
    regressor_col=['x1','x2'], 
)

blr = SVIForecaster(
    model=model,
    response_col='y', 
    date_col='week',
    estimator_type=PyroEstimatorSVI,
    verbose=True,
    num_steps=501,
    seed=2021,
)

blr.fit(train_df)
predicted_df = blr.predict(df)
estimated_weights = blr.get_posterior_samples()['weight']