Introduction
"Given a fixed number of independent attempts and a constant per-attempt success rate, how many successes should we actually expect — and how much could that vary?" is the Binomial question, and it shows up everywhere from clinical trial responders to defective units in a manufacturing lot. SimulateCountOfSuccesses runs a Monte Carlo simulation of exactly that using numpy.random.binomial, returning the full distribution of possible success counts across repeated trials rather than just a single expected value.
Teaching Note
Binomial count simulations are essential for:
- Epidemiology: Modeling the potential number of infections in a cohort given a transmission probability.
- Healthcare: Simulating the number of patients expected to respond positively to a clinical treatment.
- Intelligence Analysis: Estimating the number of successful signal interceptions in a batch of collection trials.
- Quality Engineering: Predicting the number of defective units likely to be found in a manufacturing lot.
- Marketing: Simulating the number of customers who convert (purchase) from a target email campaign.
- Cybersecurity: Modeling the expected number of successful intrusion attempts over a specific observation window.
- Finance: Estimating the number of profitable trades in a large-scale algorithmic trading strategy.
- Ecology: Simulating the survival count of offspring in a population given a baseline survival rate.
Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
probability_of_successrequired | float | — | The constant probability of success for each individual trial (must be between 0 and 1). |
sample_size_per_trialrequired | int | — | The total number of trials conducted in each simulation (e.g., total patients or attempts). |
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. 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 success count as a vertical dashed line. Defaults to True. |
show_median | bool | True | Whether to display the median success 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 simulated number of successes' | 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 successes across all trials — a pandas DataFrame or a NumPy array, depending on return_format.
Example
python
from analysistoolbox.simulations import SimulateCountOfSuccesses
# Healthcare: predicting patient response in a 50-person trial (20% success rate)
response_sim = SimulateCountOfSuccesses(
probability_of_success=0.20,
sample_size_per_trial=50,
simulated_variable_name='Patients Responded',
title_for_plot='Simulated Treatment Successes'
)