Introduction
When events happen continuously and independently at some average rate — patient arrivals, server crashes, support tickets — the time gap between any two consecutive events isn't constant, and planning around the average gap alone underestimates how often events cluster close together. SimulateTimeBetweenEvents runs a Monte Carlo simulation of those inter-arrival times using numpy.random.exponential, the standard continuous model for wait times and equipment time-to-failure, given just the average time between events.
Teaching Note
Time-between-events simulations are essential for:
- Healthcare: Modeling the time intervals between patient arrivals at an emergency department or clinic.
- Intelligence Analysis: Simulating the time between intercepted signals or detected adversary movements.
- Cybersecurity: Estimating the duration between network intrusion attempts or system security alerts.
- Quality Engineering: Modeling the time between machine breakdowns or the discovery of defects on a line.
- Customer Service: Simulating the time between incoming support calls, emails, or live chat requests.
- DevOps & Site Reliability: Estimating the time between software deployment failures or service incidents.
- Logistics: Modeling the time between freighter, truck, or aircraft arrivals at a distribution hub.
- Environmental Science: Simulating the time between natural hazard events like earthquakes or floods.
Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
expected_time_between_eventsrequired | float | — | The average or expected time interval between events (must be greater than 0). |
number_of_trials | int | 10000 | The number of stochastic simulations (Monte Carlo trials) to run. Defaults to 10000. |
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 Between Events' | The label for the simulated time variable in the output and plot. Defaults to 'Time Between Events'. |
random_seed | int | 412 | The seed for the random number generator to ensure replicability. Defaults to 412. |
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 interval as a vertical dashed line. Defaults to True. |
show_median | bool | True | Whether to display the median interval 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 time between events' | 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 time intervals across all Monte Carlo runs — a pandas DataFrame or a NumPy array, depending on return_format.
Example
python
from analysistoolbox.simulations import SimulateTimeBetweenEvents
# Healthcare: simulating time between ER arrivals (avg 7.5 minutes)
arrival_sim = SimulateTimeBetweenEvents(
expected_time_between_events=7.5,
simulated_variable_name='Minutes Between Arrivals',
title_for_plot='ER Inter-arrival Timing'
)