CreateCorrelatedSIPs — Analysis Tool Box

Introduction

Simulating two related quantities as if they were independent — recovery time and hospital resource use, signal strength and geolocation error — will systematically misstate your aggregate risk, understating it when the variables move together and overstating it when they offset. CreateCorrelatedSIPs generates a pair of normally distributed Stochastic Information Packets (SIPs) with a precise, specified Pearson correlation between them, so a Monte Carlo simulation built on the output preserves the real dependency instead of assuming independence away.

Teaching Note

Correlated simulations are essential for:

Epidemiology: Modeling the relationship between contact rates and transmission probability.
Healthcare: Simulating patient recovery time and hospital resource consumption.
Intelligence Analysis: Modeling the relationship between signal reliability and threat confidence.
Risk Management: Analyzing portfolio volatility where asset prices are interdependent.
Supply Chain: Modeling the correlation between lead times and demand spikes.
Environmental Science: Simulating temperature and rainfall patterns for crop yield risk.
Finance: Estimating Value at Risk (VaR) for correlated currency pairs.
Project Management: Modeling task dependencies and cumulative schedule risk.

Parameters

Parameter	Type	Default	Description
`mean_of_variable_1`required	`float`	—	The arithmetic mean for the first simulated variable.
`std_of_variable_1`required	`float`	—	The standard deviation for the first simulated variable.
`mean_of_variable_2`required	`float`	—	The arithmetic mean for the second simulated variable.
`std_of_variable_2`required	`float`	—	The standard deviation for the second simulated variable.
`correlation`required	`float`	—	The target Pearson correlation coefficient between the two variables (-1 to 1).
`number_of_samples`	`int`	`10000`	The number of stochastic trials to generate. Defaults to 10000.
`variable_1_name`	`str`	`'Variable 1'`	Label for the first variable in the output DataFrame and plot. Defaults to 'Variable 1'.
`variable_2_name`	`str`	`'Variable 2'`	Label for the second variable in the output DataFrame and plot. Defaults to 'Variable 2'.
`print_simulation_result_summary`	`bool`	`False`	Whether to print the observed correlation and summary statistics of the generated data. Defaults to False.
`show_scatterplot`	`bool`	`True`	Whether to display a scatterplot of the simulated samples. Defaults to True.
`dot_fill_color`	`str`	`'#999999'`	The hex color code for the points in the scatterplot. Defaults to '#999999'.
`title_for_plot`	`str`	`'Simulation Results'`	The main title text for the scatterplot. Defaults to 'Simulation Results'.
`subtitle_for_plot`	`str`	`'Showing the correlation between two variables'`	The descriptive subtitle for the scatterplot.
`caption_for_plot`	`str`	`None`	Additional text block displayed at the bottom of the plot. Defaults to None.
`data_source_for_plot`	`str`	`None`	Text identifying the source of the simulation parameters. Defaults to None.
`x_indent`	`float`	`-0.128`	Horizontal offset for the plot title and subtitle. Defaults to -0.128.
`title_y_indent`	`float`	`1.125`	Vertical offset for the title text. Defaults to 1.125.
`subtitle_y_indent`	`float`	`1.05`	Vertical offset for the subtitle text. Defaults to 1.05.
`caption_y_indent`	`float`	`-0.3`	Vertical offset for the caption text. Defaults to -0.3.

Returns

A pandas DataFrame containing the two columns of simulated correlated data.

Example

python

from analysistoolbox.simulations import CreateCorrelatedSIPs

# Healthcare: modeling the correlation between patient age and recovery days
recovery_data = CreateCorrelatedSIPs(
    mean_of_variable_1=65.0,
    std_of_variable_1=12.0,
    mean_of_variable_2=14.0,
    std_of_variable_2=4.0,
    correlation=0.65,
    variable_1_name='Patient Age',
    variable_2_name='Recovery Days'
)