Introduction
A logistic regression's predicted probability for a specific applicant or case comes with a confidence interval — but most workflows discard that interval and pass only the point estimate downstream. CreateSLURPDistributionFromLogisticRegression keeps the uncertainty: it extracts the confidence interval for a predicted probability from a fitted statsmodels logit or probit model at a given set of predictor values, fits a flexible Metalog distribution bounded to [0, 1] over that interval, and returns stochastic probability samples ready for a larger Monte Carlo risk model.
Teaching Note
SLURP distributions from logistic regression are essential for:
- Healthcare: Simulating the probability of disease presence based on clinical diagnostic markers.
- Finance: Estimating the likelihood of loan default based on credit history and income levels.
- Intelligence Analysis: Modeling the probability of a specific threat or event based on signal data.
- Marketing: Simulating customer churn probability for a cohort based on engagement metrics.
- Epidemiology: Estimating the individual probability of infection based on exposure risk factors.
- Cybersecurity: Modeling the likelihood of a system breach based on detected vulnerabilities.
- Legal Analysis: Estimating the probability of a favorable verdict based on case characteristics.
- Environmental Science: Assessing the likelihood of extreme weather events or wildfires.
Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
logistic_regression_modelrequired | statsmodels.discrete.discrete_model.BinaryResultsWrapper | — | A fitted logit or probit model from the statsmodels library. |
list_of_prediction_valuesrequired | list | — | A list of values for each predictor in the model. 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 probability uncertainty. Defaults to 10000. |
prediction_interval | float | 0.95 | The confidence level for the predicted probability interval (between 0 and 1). Defaults to 0.95. |
lower_bound | float | 0 | A logical lower limit for the probability (clamped to 0). Defaults to 0. |
upper_bound | float | 1 | A logical upper limit for the probability (clamped to 1). Defaults to 1. |
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. 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 probability 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 probability as a vertical dashed line. Defaults to True. |
show_median | bool | True | Whether to display the median probability as a vertical dotted line. 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 probability samples representing the uncertainty of the model's prediction — a pandas DataFrame or a NumPy array, depending on return_format.
Example
python
from analysistoolbox.simulations import CreateSLURPDistributionFromLogisticRegression
import statsmodels.api as sm
# Finance: simulating the probability of loan default for an applicant
logit_model = sm.Logit(y, X).fit()
default_prob_sim = CreateSLURPDistributionFromLogisticRegression(
logistic_regression_model=logit_model,
list_of_prediction_values=[720, 50000], # Credit score and Income
title_for_plot="Uncertainty in Default Probability"
)