CreateARIMAModel — Analysis Tool Box

Introduction

Forecasting a time series well starts with understanding its own structure — how strongly it depends on its recent past, whether it needs differencing to become stationary, and how much noise is left once you account for both. CreateARIMAModel builds that understanding into one workflow: it runs an Augmented Dickey-Fuller stationarity test, optionally plots ACF/PACF to guide your (p, d, q) choices, fits an ARIMA model via statsmodels' SARIMAX implementation, and compares training vs. test RMSE so you know whether the fitted model actually generalizes before you trust its forecasts.

Teaching Note

Building ARIMA models is essential for:

Forecasting financial indicators like stock prices or currency exchange rates
Predicting supply chain requirements and inventory demand cycles
Analyzing intelligence trends such as frequency of security incidents over time
Monitoring economic throughput and identifying seasonal fluctuations
Projecting infrastructure load and server capacity requirements
Detecting anomalies and structural shifts in high-frequency sensor data
Evaluating the impact of historical interventions on future outcomes

Parameters

Parameter	Default	Description
`dataframe`required	—	The input pandas DataFrame containing the time series data to be modeled.
`outcome_column_name`required	—	The name of the target variable column in the dataframe.
`time_column_name`	`None`	The name of the column representing the time axis (e.g., date, month). Required if plot_time_series is True. Defaults to None.
`lookback_periods`	`1`	The number of lags to include in ACF and PACF plots. Defaults to 1.
`differencing_periods`	`0`	The 'd' parameter in ARIMA(p, d, q) — the number of times the raw observations are differenced. Defaults to 0.
`lag_periods`	`1`	The 'p' parameter in ARIMA(p, d, q) — the number of lag observations included in the model (AR order). Defaults to 1.
`moving_average_periods`	`1`	The 'q' parameter in ARIMA(p, d, q) — the size of the moving average window (MA order). Defaults to 1.
`test_size`	`0.2`	Proportion of observations held out as a temporal test set (the last test_size fraction of rows). The model is fit on the remaining earlier observations. Defaults to 0.2.
`plot_time_series`	`False`	Whether to generate a line plot of the outcome variable over time. Defaults to False.
`time_series_figure_size`	`(8, 5)`	Dimensions (width, height) of the time series plot. Defaults to (8, 5).
`line_color`	`'#3269a8'`	Hex color code for the time series line. Defaults to '#3269a8'.
`line_alpha`	`0.8`	Transparency level for the plot line (0.0 to 1.0). Defaults to 0.8.
`number_of_x_axis_ticks`	`None`	Desired number of ticks on the x-axis. Defaults to None.
`x_axis_tick_rotation`	`None`	Degree of rotation for x-axis labels. Defaults to None.
`title_for_plot`	`'Time Series'`	Main title for the generated visualization. Defaults to 'Time Series'.
`subtitle_for_plot`	`'Shows the time series for the outcome variable.'`	Brief description shown below the main title.
`caption_for_plot`	`None`	Explanatory text displayed in the bottom margin. Defaults to None.
`data_source_for_plot`	`None`	Source citation displayed in the caption area. Defaults to None.
`x_indent`	`-0.127`	Horizontal offset for the title, subtitle, and caption text on the time series plot. Defaults to -0.127.
`title_y_indent`	`1.125`	Vertical offset for the plot title on the time series plot. Defaults to 1.125.
`subtitle_y_indent`	`1.05`	Vertical offset for the plot subtitle on the time series plot. Defaults to 1.05.
`caption_y_indent`	`-0.3`	Vertical offset for the plot caption on the time series plot. Defaults to -0.3.
`test_for_stationarity`	`True`	If True, performs an Augmented Dickey-Fuller test and prints a warning if the data appears non-stationary. Defaults to True.
`show_acf_pacf_plots`	`False`	Whether to display Autocorrelation and Partial Autocorrelation plots. Defaults to False.
`show_model_results`	`False`	If True, prints a comprehensive summary of the fitted SARIMAX model. Defaults to False.
`plot_residuals`	`True`	Whether to show a kernel density estimate (KDE) plot of the model residuals (training set only). Defaults to True.
`print_model_training_performance`	`False`	If True, prints training RMSE and test RMSE after fitting. Defaults to False.
`plot_training_and_test_performance`	`True`	Whether to render a bar chart comparing training RMSE and test RMSE. Defaults to True.
`training_bar_color`	`'#3a86ff'`	Bar color for the training RMSE bar in the performance comparison chart. Defaults to '#3a86ff'.
`test_bar_color`	`'#b0170c'`	Bar color for the test RMSE bar in the performance comparison chart. Defaults to '#b0170c'.
`figure_size_for_performance_comparison_plot`	`(7, 5)`	Dimensions (width, height) for the training/test RMSE comparison chart. Defaults to (7, 5).
`title_for_performance_comparison_plot`	`None`	Title text for the training/test RMSE comparison chart. Defaults to a sensible built-in title when None.
`subtitle_for_performance_comparison_plot`	`None`	Subtitle text for the training/test RMSE comparison chart. Defaults to a sensible built-in subtitle when None.
`caption_for_performance_comparison_plot`	`None`	Caption text for the training/test RMSE comparison chart. Defaults to None.
`title_y_indent_for_performance_comparison_plot`	`1.1`	Vertical offset for the title on the performance comparison chart. Defaults to 1.1.
`subtitle_y_indent_for_performance_comparison_plot`	`1.05`	Vertical offset for the subtitle on the performance comparison chart. Defaults to 1.05.
`caption_y_indent_for_performance_comparison_plot`	`-0.15`	Vertical offset for the caption on the performance comparison chart. Defaults to -0.15.
`x_indent_for_performance_comparison_plot`	`-0.115`	Horizontal offset for text elements on the performance comparison chart. Defaults to -0.115.

Returns

The fitted statsmodels.tsa.statespace.sarimax.SARIMAXResultsWrapper model object, containing coefficients, statistics, and prediction methods (e.g. .forecast(steps=n)).

Example

python

from analysistoolbox.predictive_analytics import CreateARIMAModel

model = CreateARIMAModel(
    dataframe=monthly_df,
    outcome_column_name='revenue',
    time_column_name='month',
    lag_periods=2,              # AR(2)
    differencing_periods=1,     # one difference for stationarity
    moving_average_periods=1,   # MA(1)
    test_for_stationarity=True,
    plot_time_series=True,
)

# Forecast next 6 months
forecast = model.forecast(steps=6)