CreateSLURPDistributionFromExponentialSmoothing

Introduction

A single-point forecast from an exponential smoothing model hides how much uncertainty actually surrounds it — and feeding a point estimate into a downstream Monte Carlo model throws that uncertainty away entirely. CreateSLURPDistributionFromExponentialSmoothing fixes that by taking a fitted statsmodels exponential smoothing model, computing prediction intervals from its residual standard error at your chosen forecast horizon, fitting a flexible Metalog distribution to those intervals, and returning stochastic samples that carry the forecast's real uncertainty forward into your simulation.

Teaching Note

SLURP distributions from exponential smoothing are essential for:

Supply Chain: Modeling future inventory requirements given seasonal demand patterns.
Healthcare: Projecting future patient admission volumes with uncertainty for capacity planning.
Finance: Simulating future revenue or cash flows based on historical trends and volatility.
Epidemiology: Forecasting future disease incidence rates and the associated range of uncertainty.
Intelligence Analysis: Projecting future regional stability indices or economic indicators.
Energy: Simulating future power demand forecasts for grid reliability assessments.
Public Health: Estimating future vaccine uptake rates to optimize distribution logistics.
Retail: Forecasting future store traffic for staffing and resource allocation.

Parameters

Parameter	Type	Default	Description
`exponential_smoothing_model`required	`statsmodels.tsa.exponential_smoothing.ets.ETSResults`	—	A fitted exponential smoothing (ETS or Holt-Winters) model from statsmodels.
`forecast_steps`	`int`	`1`	The number of steps into the future to forecast (e.g., 1 for next day, 7 for next week). Defaults to 1.
`number_of_trials`	`int`	`10000`	The number of stochastic samples to generate from the uncertainty distribution. Defaults to 10000.
`prediction_interval`	`float`	`0.95`	The confidence level for the prediction interval (between 0 and 1). Defaults to 0.95.
`lower_bound`	`float`	`None`	A logical lower limit for the simulated values (e.g., 0 for counts/prices). Defaults to None.
`upper_bound`	`float`	`None`	A logical upper limit for the simulated values. Defaults to None.
`learning_rate`	`float`	`0.01`	The step length for the Metalog fitting algorithm. Defaults to 0.01.
`term_maximum`	`int`	`3`	The maximum number of terms in the Metalog expansion (up to 9). Higher terms increase shape flexibility. Defaults to 3.
`term_minimum`	`int`	`2`	The minimum number of terms allowed. Defaults to 2.
`term_for_random_sample`	`int`	`None`	The specific number of terms used for generating samples. If None, the term_limit from the fit is used. Defaults to None.
`show_summary`	`bool`	`False`	Whether to print the summary of the Metalog distribution coefficients. Defaults to False.
`return_format`	`str`	`'dataframe'`	The format of the output: 'dataframe' (pd.DataFrame) or 'array' (np.ndarray). Defaults to 'dataframe'.
`show_distribution_plot`	`bool`	`True`	Whether to display a histogram of the generated samples. Defaults to True.
`figure_size`	`tuple`	`(8, 6)`	The size of the plot figure in inches (width, height). Defaults to (8, 6).
`fill_color`	`str`	`'#999999'`	The hex color code for the histogram bars. Defaults to '#999999'.
`fill_transparency`	`float`	`0.6`	The transparency level (0-1) for the histogram plot. Defaults to 0.6.
`show_mean`	`bool`	`True`	Whether to display the mean as a vertical dashed line on the plot. Defaults to True.
`show_median`	`bool`	`True`	Whether to display the median as a vertical dotted line on the plot. Defaults to True.
`show_y_axis`	`bool`	`False`	Whether to display the frequency/density scale on the y-axis. Defaults to False.
`title_for_plot`	`str`	`None`	The main title for the distribution plot. Defaults to None.
`subtitle_for_plot`	`str`	`None`	The descriptive subtitle for the plot. Defaults to None.
`caption_for_plot`	`str`	`None`	Optional caption text displayed at the bottom of the plot. Defaults to None.
`data_source_for_plot`	`str`	`None`	Optional data source identification text. Defaults to None.
`title_y_indent`	`float`	`1.1`	Vertical position for the title text. Defaults to 1.1.
`subtitle_y_indent`	`float`	`1.05`	Vertical position for the subtitle text. Defaults to 1.05.
`caption_y_indent`	`float`	`-0.15`	Vertical position for the caption text. Defaults to -0.15.

Returns

The generated samples representing the uncertainty of the future forecast — a pandas DataFrame or a NumPy array, depending on return_format.

Example

python

from analysistoolbox.simulations import CreateSLURPDistributionFromExponentialSmoothing
from statsmodels.tsa.holtwinters import ExponentialSmoothing

# Supply Chain: simulating future demand (7 days ahead) for inventory planning
model = ExponentialSmoothing(historical_demand, trend='add', seasonal='add').fit()
demand_sim = CreateSLURPDistributionFromExponentialSmoothing(
    exponential_smoothing_model=model,
    forecast_steps=7,
    lower_bound=0,
    title_for_plot="Weekly Demand Uncertainty Projection"
)