Introduction
"On average we see 8 patients an hour" tells you the center of a distribution, not its spread — and staffing to the average is a common way to be under-resourced on a busy hour. SimulateCountOutcome runs a Monte Carlo simulation of independent "arrival" events over a fixed interval using numpy.random.poisson, given only the average expected count, so you can see the full range of plausible counts rather than just the mean.
Teaching Note
Poisson count simulations are essential for:
- Epidemiology: Modeling the daily number of new disease cases in a specific region.
- Healthcare: Simulating patient arrivals at an emergency department per hour.
- Intelligence Analysis: Modeling the frequency of specific signal detections per day.
- Cybersecurity: Estimating the number of malicious port scans or log-in attempts per minute.
- Supply Chain: Projecting the daily volume of customer orders at a warehouse.
- Infrastructure: Simulating vehicle throughput at a highway intersection per hour.
- Finance: Estimating the frequency of high-value transactions or system alerts.
- Quality Control: Modeling the number of surface defects per square meter of manufactured material.
Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
expected_countrequired | float | — | The average number of events expected to occur in the interval (Lambda). |
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 | 'Count' | The label for the simulated count variable in the output and plot. Defaults to 'Count'. |
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 event count as a vertical dashed line. Defaults to True. |
show_median | bool | True | Whether to display the median event count 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 simulated count outcome' | 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 events across all trials — a pandas DataFrame or a NumPy array, depending on return_format.
Example
python
from analysistoolbox.simulations import SimulateCountOutcome
# Healthcare: simulating hourly ER arrivals (average of 8 per hour)
er_arrivals = SimulateCountOutcome(
expected_count=8.0,
simulated_variable_name='Patient Arrivals',
title_for_plot='Simulated ER Throughput'
)