Introduction
A small per-trial risk can compound into an unacceptable cumulative one faster than intuition suggests — a 2% detection risk per phase becomes a 64% cumulative risk across 50 phases. ProbabilityOfAtLeastOne computes exactly that compounding via P(at least one) = 1 − (1 − p)^n, and plots how the cumulative probability grows with the number of trials, optionally marking a risk-tolerance threshold so you can see at a glance how many trials it takes to cross into unacceptable territory.
Teaching Note
Calculating the probability of at least one event is essential for:
- Epidemiology: Estimating the risk of a disease outbreak over multiple years.
- Healthcare: Assessing the cumulative risk of drug side effects over a long-term prescription.
- Intelligence Analysis: Determining the probability of an operation being detected across multiple phases.
- Cybersecurity: Evaluating the likelihood of a successful system breach over numerous hacking attempts.
- Engineering: Calculating the failure probability of a redundant system during its lifespan.
- Finance: Estimating the probability of a market "black swan" event occurring within a specific decade.
- Environmental Science: Assessing the risk of a 100-year flood occurring at least once in 30 years.
- Quality Control: Predicting the likelihood of finding at least one defect in a batch of products.
Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
probability_of_eventrequired | float | — | The probability of the event occurring in a single trial (value between 0 and 1). |
number_of_eventsrequired | int | — | The total number of trials or events to consider. |
format_as_percent | bool | False | Whether to return the result as a formatted percentage string (e.g., '75.00%') instead of a raw float. Defaults to False. |
show_plot | bool | True | Whether to generate a line plot showing the cumulative probability growth. Defaults to True. |
line_color | str | '#3269a8' | The hex color code for the probability curve in the plot. Defaults to '#3269a8'. |
line_alpha | float | 0.8 | The transparency level of the plotted line (0 to 1). Defaults to 0.8. |
risk_tolerance | float | None | A specific probability threshold (0 to 1) to highlight on the plot. If provided, the function marks the point where the cumulative risk exceeds this value. Defaults to None. |
risk_tolerance_color | str | '#cc453b' | The hex color code for the risk tolerance markers and dashed lines. Defaults to '#cc453b'. |
number_of_x_axis_ticks | int | None | The maximum number of tick marks to display on the x-axis. Defaults to None. |
x_axis_tick_rotation | float | None | The rotation angle in degrees for the x-axis tick labels. Defaults to None. |
title_for_plot | str | 'Probability of at Least One Event' | The main title text displayed above the plot. |
subtitle_for_plot | str | 'Shows the probability of at least one event occurring, given the probability of an event and the number of events.' | The descriptive text displayed below the main title. |
caption_for_plot | str | None | Additional summary or explanatory text displayed at the bottom of the plot. Defaults to None. |
data_source_for_plot | str | None | Text identifying the source of the data, appended to the caption. Defaults to None. |
x_indent | float | -0.127 | Horizontal offset for the plot title and labels. Defaults to -0.127. |
title_y_indent | float | 1.125 | Vertical offset for the plot title. Defaults to 1.125. |
subtitle_y_indent | float | 1.05 | Vertical offset for the plot subtitle. Defaults to 1.05. |
caption_y_indent | float | -0.3 | Vertical offset for the plot caption. Defaults to -0.3. |
figure_size | tuple | (7, 6) | The width and height of the plot in inches. Defaults to (7, 6). |
Returns
A float, or a string when format_as_percent is True — the calculated probability that the event occurs at least once.
Example
python
from analysistoolbox.probability import ProbabilityOfAtLeastOne
# Epidemiology: probability of at least one infection in a group of 50 people
# given a 2% transmission rate per contact
p_inf = ProbabilityOfAtLeastOne(
probability_of_event=0.02,
number_of_events=50,
risk_tolerance=0.5
)