Introduction
"How many cold calls until the first sale, how many days until the first signal detection, how many inspected units until the first defect" are all the same underlying question: given a constant per-trial success probability, how long is the wait for the first success? SimulateCountUntilFirstSuccess runs a Monte Carlo simulation of this Geometric-distribution scenario, repeatedly simulating Bernoulli trials until the first success lands for each Monte Carlo run, and returning the full distribution of wait times rather than a single expected count.
Teaching Note
Geometric wait-time simulations are essential for:
- Intelligence Analysis: Modeling the number of days or collection attempts until a high-value signal is detected.
- Healthcare: Simulating the number of treatment rounds or diagnostic tests until a patient achieves remission or a definitive result.
- Sales & Marketing: Estimating the number of cold calls or touchpoints required to secure a first-time customer.
- Quality Engineering: Predicting the number of production units inspected until the first defective item is identified.
- Cybersecurity: Modeling the number of brute-force login attempts required to breach a test account during a security audit.
- Human Resources: Estimating the number of candidates screened or interviewed until a qualified hire is made.
- Engineering: Simulating the number of cycles or operations until the first instance of component failure or fatigue.
- Scientific Research: Predicting the number of experimental trials required until a specific reaction or observation occurs.
Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
probability_of_successrequired | float | — | The constant probability of success for each individual trial (must be between 0 and 1). |
number_of_trials | int | 10000 | The number of stochastic simulations (Monte Carlo trials) to run. Defaults to 10000. |
simulated_variable_name | str | 'Count Until First Success' | The label for the simulated count variable in the output and plot. Defaults to 'Count Until First Success'. |
random_seed | int | 412 | The seed for the random number generator to ensure replicability. Defaults to 412. |
return_format | str | 'dataframe' | The format of the returned data: 'dataframe' (pd.DataFrame) or 'array' (np.ndarray). Defaults to 'dataframe'. |
plot_simulation_results | bool | True | Whether to display a histogram of the simulation outcomes. Defaults to True. |
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. |
figure_size | tuple | (8, 6) | The size of the plot figure in inches (width, height). Defaults to (8, 6). |
show_mean | bool | True | Whether to display the mean wait time as a vertical dashed line. Defaults to True. |
show_median | bool | True | Whether to display the median wait time as a vertical dotted line. Defaults to True. |
title_for_plot | str | 'Simulation Results' | The main title for the distribution plot. Defaults to 'Simulation Results'. |
subtitle_for_plot | str | 'Showing the distribution of the count until first success' | The descriptive subtitle for the plot. |
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. |
show_y_axis | bool | False | Whether to display the frequency/density scale on the y-axis. Defaults to False. |
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 simulated counts of trials until the first success across all Monte Carlo runs — a pandas DataFrame or a NumPy array, depending on return_format.
Example
python
from analysistoolbox.simulations import SimulateCountUntilFirstSuccess
# Sales: estimating calls needed for first conversion (10% success rate)
calls_sim = SimulateCountUntilFirstSuccess(
probability_of_success=0.10,
simulated_variable_name='Calls to Close',
title_for_plot='Sales Conversion Wait Time'
)