CreateSLURPDistributionFromLinearRegression

Introduction

A regression's point prediction for a specific set of inputs is only half the story — the other half is how much that prediction could plausibly vary, which a single number can't convey. CreateSLURPDistributionFromLinearRegression extracts the prediction interval from a fitted statsmodels linear regression for a given set of predictor values, accounting for both the model's structural uncertainty and individual observation variance, fits a flexible Metalog distribution to that interval, and returns stochastic samples ready to feed into a Monte Carlo simulation.

Teaching Note

SLURP distributions from linear regression are essential for:

Finance: Projecting asset returns or portfolio performance based on macroeconomic indicators.
Healthcare: Simulating patient health outcomes or recovery scores based on treatment dosage and age.
Intelligence Analysis: Modeling potential threat activity levels based on historical intelligence markers.
Supply Chain: Estimating delivery lead times or shipping costs based on distance and carrier data.
Epidemiology: Projecting disease transmission rates or case counts based on public health interventions.
Engineering: Predicting mechanical component lifespan based on operational stress and temperature.
Real Estate: Estimating property valuation ranges based on square footage, location, and market trends.
Marketing: Simulating customer lifetime value (CLV) based on initial acquisition costs and demographics.

Parameters

Parameter	Type	Default	Description
`linear_regression_model`required	`statsmodels.regression.linear_model.RegressionResultsWrapper`	—	A fitted linear regression model from the statsmodels library.
`list_of_prediction_values`required	`list`	—	A list of values for each predictor in the model (e.g., [10, 0.5, 20]). If the model includes a constant, it will be automatically handled.
`number_of_trials`	`int`	`10000`	The number of stochastic trials 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 prices or weights). 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 flexibility but may overfit limited data. 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 regression prediction — a pandas DataFrame or a NumPy array, depending on return_format.

Example

python

from analysistoolbox.simulations import CreateSLURPDistributionFromLinearRegression
import statsmodels.api as sm

# Real Estate: simulating property value for a 2,500 sq ft home
X = sm.add_constant(homes_df[['sqft', 'bedrooms']])
model = sm.OLS(homes_df['price'], X).fit()
price_sim = CreateSLURPDistributionFromLinearRegression(
    linear_regression_model=model,
    list_of_prediction_values=[2500, 4],
    lower_bound=0,
    title_for_plot="Simulated Home Valuation Range"
)