Introduction
Knowing the average time between individual events doesn't directly tell you how long a whole batch of them will take — five surgeries, ten software modules, N support tickets — because the cumulative wait has its own, wider distribution. SimulateTimeUntilNEvents runs a Monte Carlo simulation of that cumulative wait using numpy.random.gamma, generalizing the Exponential distribution's "time until the first event" to "time until the Nth event," which makes it a direct tool for capacity planning and project duration estimation.
Teaching Note
Time-until-N-events simulations are essential for:
- Healthcare: Modeling the expected time until a specialized clinic completes 'N' complex surgeries or procedures.
- Customer Support: Simulating the total time required for a technical team to resolve 'N' high-priority tickets.
- Intelligence Analysis: Estimating the time window needed to collect 'N' distinct intelligence artifacts for an assessment.
- Quality Engineering: Modeling the time until a manufacturing process produces 'N' defective units for reliability testing.
- Logistics & Warehouse: Simulating the total time until a distribution hub processes and clears 'N' scheduled shipments.
- Project Management: Estimating the total duration of a project phase that requires the completion of 'N' sequential milestones.
- Finance: Modeling the time required for an algorithmic system to execute 'N' blocks of automated trades under market conditions.
- Meteorology: Predicting the likely time period until a geographic region experiences 'N' instances of an extreme weather event.
Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
number_of_events | int | 1 | The total count of events that must occur for the simulation to conclude (Shape). Defaults to 1. |
expected_time_between_events | float | 1 | The average or expected time interval between individual events (Scale). Defaults to 1. |
number_of_trials | int | 10000 | The number of stochastic simulations (Monte Carlo trials) to run. Defaults to 10000. |
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'. |
simulated_variable_name | str | 'Time Until N Events' | The label for the simulated time variable in the output and plot. Defaults to 'Time Until N Events'. |
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 completion time as a vertical dashed line. Defaults to True. |
show_median | bool | True | Whether to display the median completion 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 time until n events occur' | 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 total times across all Monte Carlo runs — a pandas DataFrame or a NumPy array, depending on return_format.
Example
python
from analysistoolbox.simulations import SimulateTimeUntilNEvents
# Healthcare: time until 5 surgeries are completed (avg 4 hours each)
surgery_sim = SimulateTimeUntilNEvents(
number_of_events=5,
expected_time_between_events=4.0,
simulated_variable_name='Hours to Complete Batch',
title_for_plot='Surgical Suite Throughput Simulation'
)