Introduction
A Monte Carlo simulation produces a distribution of possible outcomes, but the decision-relevant question is usually narrower: what fraction of those outcomes cross a threshold you actually care about — ICU capacity, a budget ceiling, a defect rate limit? PlotRiskTolerance takes simulated values and a risk tolerance threshold, highlights the portion of the distribution that breaches it, calculates the probability of that breach, and can overlay an observed real-world value for direct comparison against the simulated risk.
Teaching Note
Risk tolerance plots are essential for:
- Epidemiology: Estimating the probability of hospitalizations exceeding ICU capacity.
- Healthcare: Assessing the risk of clinical wait times exceeding an operational threshold.
- Intelligence Analysis: Visualizing the probability of enemy troop concentrations within target sectors.
- Data Science: Evaluating the risk of model latency exceeding a service-level agreement (SLA).
- Public Health: Estimating the probability of daily pollutant levels exceeding safety limits.
- Finance: Assessing the Value at Risk (VaR) for an investment portfolio.
- Project Management: Estimating the probability of a project exceeding its budget or timeline.
- Quality Control: Assessing the risk of manufacturing defect rates exceeding quality standards.
Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
simulated_valuesrequired | array_like (numpy.ndarray or pd.Series) | — | The collection of simulated data points to be visualized. |
risk_tolerancerequired | int or float | — | The threshold value representing the maximum acceptable risk level. |
lower_is_worse | bool | True | Whether values smaller than risk_tolerance are considered negative outcomes. Defaults to True. |
variable_name | str | 'Outcome' | The label for the simulated metric (e.g., 'Profit', 'Cases'). Defaults to 'Outcome'. |
observed_value | int or float | None | A specific actual or historical value to plot as a reference line. Defaults to None. |
risk_tolerance_label | str | 'Tolerance' | The text label used to identify the risk tolerance line. Defaults to 'Tolerance'. |
fill_color | str | '#999999' | The hex color code for the non-critical portion of the histogram. Defaults to '#999999'. |
fill_transparency | float | 0.6 | The transparency level (alpha) of the histogram bars. Defaults to 0.6. |
title_for_plot | str | 'Risk Tolerance' | The primary title text at the top of the chart. Defaults to 'Risk Tolerance'. |
subtitle_for_plot | str | 'Shows the simulated outcomes that are worse than the risk tolerance.' | Descriptive subtitle text below the main title. |
caption_for_plot | str | None | Explanatory text or notes at the bottom of the plot. Defaults to None. |
data_source_for_plot | str | None | Text identifying the data source, appended to the caption. Defaults to None. |
show_y_axis | bool | False | Whether to display the vertical frequency axis. Defaults to False. |
title_y_indent | float | 1.1 | Vertical offset for the title position. Defaults to 1.1. |
subtitle_y_indent | float | 1.05 | Vertical offset for the subtitle position. Defaults to 1.05. |
caption_y_indent | float | -0.15 | Vertical offset for the caption position. Defaults to -0.15. |
figure_size | tuple | (8, 6) | Dimensions of the output figure as a (width, height) tuple in inches. Defaults to (8, 6). |
filepath_to_save_plot | str | None | The local path (ending in .png or .jpg) where the plot should be exported. If None, the file is not saved. Defaults to None. |
Returns
None — the function displays the risk tolerance plot using matplotlib and optionally saves it to disk.
Example
python
from analysistoolbox.visualizations import PlotRiskTolerance
import numpy as np
# Epidemiology: risk of exceeding hospital bed capacity
sim_cases = np.random.normal(450, 50, 1000)
PlotRiskTolerance(
sim_cases, risk_tolerance=550, lower_is_worse=False,
variable_name="ICU Beds Required",
title_for_plot="Hospital Capacity Risk Analysis",
subtitle_for_plot="Simulated ICU demand vs. total available beds"
)