cholera-risk 0.2.0

A Monte Carlo simulation for Cholera risk assessment — evaluating transboundary infection risk from Bangladesh to India

🦠 Cholera Risk Assessment — Monte Carlo Simulation

A Python package for quantitative risk analysis of transboundary cholera infection from Bangladesh to India, using stochastic Monte Carlo simulation.

---

📐 Model Overview

The model computes the compound probability of cholera-related mortality through a chain of six risk factors:

P_final = P1 × P2 × P3 × P4 × P5 × P6

Step	Parameter	Description	Distribution
P1	Outbreak Probability	Cholera outbreak in Bangladesh	Poisson: 1 − e^(−λt), λ = 2779/(22×12)
P2	Infection Rate	Human cholera infection probability	Beta(1605, 24618)
P3	False Negative (BD)	Missed cases in Bangladesh	1 − Uniform(0.549, 0.906)
P4	False Negative (IN)	Missed cases in India	1 − Uniform(0.884, 0.999)
P5	Exposure Risk	Unsafe water × unsafe sanitation	0.11 × 0.01 = 0.0011
P6	Mortality	Case fatality rate	0.03

The simulation generates 10,000 (configurable) random samples and computes:

• Expected Probability (mean)
• 90% Confidence Interval (5th–95th percentile)
• Min/Max range
• Sensitivity analysis via Spearman's rank correlation

---

📦 Installation

# Clone the repository
git clone https://github.com/example/cholera-risk.git
cd cholera-risk

# Install the package
pip install .

# Or install in development mode
pip install -e .

# Or install dependencies only
pip install -r requirements.txt

---

🚀 Quick Start

Using the Class API

from cholera_risk import CholeraSimulator

# Create simulator with 10,000 samples
sim = CholeraSimulator(n_samples=10000, seed=42)

# Run the Monte Carlo simulation
results = sim.run_simulation()

# Access results
print(f"Expected Risk: {results['summary']['expected_prob']:.6e}")
print(f"90% CI: [{results['summary']['ci_5']:.2e}, {results['summary']['ci_95']:.2e}]")

Using the Convenience Function

from cholera_risk.model import quick_risk_assessment

results = quick_risk_assessment(n_samples=50000, seed=123)
print(f"Risk: {results['summary']['expected_prob']:.6e}")

Generating Visualizations

from cholera_risk import CholeraSimulator
from cholera_risk.visualization import plot_all, print_summary

sim = CholeraSimulator(n_samples=10000, seed=42)
results = sim.run_simulation()

# Print formatted summary
print_summary(results)

# Generate all plots (histogram, sensitivity, scatter)
plot_all(results, save_dir="./output_plots/")

Custom Parameters

from cholera_risk.model import CholeraSimulator, SimulationConfig

# Customize epidemiological parameters
config = SimulationConfig(
    total_outbreaks=3000,
    observation_years=25,
    beta_alpha=2000,
    beta_beta=30000,
    case_fatality_rate=0.05,
)

sim = CholeraSimulator(n_samples=20000, seed=99, config=config)
results = sim.run_simulation()

---

🧪 Running Tests

# Run all tests
python -m pytest tests/ -v

# Run with coverage
python -m pytest tests/ -v --cov=cholera_risk --cov-report=term-missing

---

📁 Directory Structure

colera/
├── cholera_risk/              # The actual Python package
│   ├── __init__.py            # Package init, exports CholeraSimulator
│   ├── model.py               # Core simulation logic (math & stats)
│   └── visualization.py       # Plotting functions (matplotlib/seaborn)
├── tests/                     # Unit tests
│   ├── __init__.py
│   └── test_model.py          # 25+ tests for correctness
├── app.py                     # Original monolithic script (reference)
├── index.php                  # PHP web application version
├── README.md                  # This file
├── requirements.txt           # Python dependencies
└── setup.py                   # Package installation script

---

📊 Output Example

=================================================================
   CHOLERA RISK ASSESSMENT — Monte Carlo Simulation Results
=================================================================
  Samples:              10,000
  Random Seed:          42
  λ (Poisson rate):     10.5265
-----------------------------------------------------------------
  Expected Probability: 3.207426e-08
  Median:               2.450000e-08
  90% CI:               [3.16e-09, 7.74e-08]
  Minimum:              2.67e-10
  Maximum:              1.05e-07
-----------------------------------------------------------------
  Sensitivity Analysis (Spearman ρ):
    P2 (Infection Rate): ρ = 0.1234
    P3 (FN Bangladesh):  ρ = 0.3456
    P4 (FN India):       ρ = 0.5678
=================================================================

---

🔬 Methodology

• Monte Carlo Simulation: Generates thousands of random scenarios by sampling each stochastic input from its probability distribution
• Beta Distribution (P2): Models the uncertainty in human infection rates using Bayesian parameters derived from epidemiological data
• Uniform Distributions (P3, P4): Represent the range of CholKit RDT diagnostic sensitivity
• Spearman Rank Correlation: Non-parametric measure of how strongly each input drives variations in the output

---

📝 License

MIT License — see LICENSE for details.

---

👥 Authors

• Navnath Kamble — [e-mail]
• Yamini Madugu — [e-mail]