An interactive web-based epidemic simulation tool that visualizes how infectious diseases spread through populations using network-based compartmental models.
- Multiple Compartmental Models: SIR, SEIR, and SEIRD (Susceptible-Exposed-Infectious-Recovered-Deceased)
- Network-Based Transmission: Models disease spread through realistic contact networks
- Real-time Visualization: Interactive network graphs with color-coded disease states
- Epidemic Curves: Dynamic plots showing disease progression over time
- Disease Presets: Pre-configured parameters for COVID-19, Influenza, Measles, Ebola, and Common Cold
- Network Structures:
- Random Graph (ErdΕsβRΓ©nyi)
- Small-World Network (WattsβStrogatz)
- Scale-Free Network (BarabΓ‘siβAlbert)
- Community Structure (Clustered households)
- Immunity Waning: Recovered individuals can lose immunity and become susceptible again
- Variant Emergence: Models emergence of higher-transmission variants during simulation
- Super-Spreader Visualization: Node size reflects connectivity (potential super-spreaders)
- Vaccination: Immunize susceptible individuals
- Quarantine: Isolate infected individuals
- Contact Tracing: Automatically identify and quarantine contacts of infected people
- Rβ Calculation: Estimates basic reproduction number
- Epidemic Statistics: Attack rate, peak infections, mortality rate, etc.
- Data Export: Download simulation results as CSV for further analysis
- Playback Controls: Step through simulation timesteps to observe disease progression
- Python 3.10 or higher
- pip package manager
- Clone the repository:
git clone https://github.com/DevalPrime/epidemic-simulator.git
cd epidemic-simulator- Install dependencies:
pip install -r requirements.txt- Run the application:
streamlit run app.py- Open your browser: The app will automatically open at
http://localhost:8501
- Select a Disease Preset: Choose from COVID-19, Influenza, Measles, etc., or use custom parameters
- Configure Network: Select population size and network structure
- Adjust Parameters (if using Custom preset):
- Exposure probability
- Infection probability (EβI)
- Recovery probability
- Death probability
- Set Simulation Length: Choose number of timesteps
- Click "Run Simulation": Watch the disease spread through the network
During simulation playback:
- Vaccination: Enter number of individuals to vaccinate and click "Vaccinate"
- Quarantine: Specify how many infected to quarantine and click "Quarantine"
- Contact Tracing: Click "Contact Tracing" to auto-quarantine exposed contacts
- Immunity Waning: Set the period (timesteps) after which recovered individuals lose immunity
- Variant Emergence: Enable variants and specify when they emerge and their transmission advantage
- Super-Spreader Visualization: Toggle to show node sizes based on connection degree
- View Statistics: Attack rate, peak infections, mortality rate displayed automatically
- Epidemic Curves: Visualize S-E-I-R-D compartments over time
- Network Animation: Use playback controls to step through the epidemic
- Export Data: Download CSV file with full time-series data
The simulator implements the SEIRD compartmental model:
- S (Susceptible): Can become infected through contact with infectious individuals
- E (Exposed): Infected but not yet infectious (incubation period)
- I (Infectious): Can transmit disease to susceptible neighbors
- R (Recovered): Immune to reinfection (unless waning immunity is enabled)
- D (Deceased): Died from disease
Individuals are represented as nodes in a graph, with edges representing potential contact for disease transmission. Different network types model different social structures:
- Random: Equal probability of connection between any two individuals
- Small-World: High clustering with some long-range connections (realistic social networks)
- Scale-Free: Few highly connected "hubs" (airports, schools, workplaces)
- Community: Tightly connected households with inter-household connections
The basic reproduction number is estimated as:
Rβ β (average_degree) Γ (transmission_probability) / (recovery_probability)
| Disease | Transmission | Recovery | Mortality | Rβ (typical) |
|---|---|---|---|---|
| COVID-19 | Moderate | Slow | Low (2%) | ~2.5 |
| Influenza | High | Fast | Very Low (0.1%) | ~1.3 |
| Measles | Very High | Moderate | Low (0.2%) | ~15 |
| Ebola | Moderate | Slow | Very High (50%) | ~2 |
| Common Cold | High | Very Fast | None | ~2 |
Note: These presets are illustrative approximations for educational purposes, not precise epidemiological data.
- Python 3.10+: Core programming language
- Streamlit: Interactive web UI framework
- NetworkX: Graph/network modeling
- Matplotlib: Data visualization and plotting
- Pandas: Data export and manipulation
- NumPy: Numerical computations
epidemic-simulator/
βββ app.py # Main Streamlit application
βββ requirements.txt # Python dependencies
βββ README.md # This file
βββ LICENSE # MIT License
βββ .gitignore # Git ignore rules
Contributions are welcome! Here are some ways you can contribute:
- Report bugs or suggest features via Issues
- Submit pull requests with improvements
- Improve documentation
- Add new disease presets with real epidemiological data
- Fork the repository
- Create a feature branch:
git checkout -b feature-name - Make your changes and test thoroughly
- Commit with clear messages:
git commit -m "Add feature X" - Push to your fork:
git push origin feature-name - Submit a pull request
Planned features for future releases:
- Transmission tree logging (who infected whom)
- Multi-run batch simulation with confidence intervals
- Auto-play animation mode
- Scaling to 1000+ nodes
- Real epidemiological data calibration
- Age-structured populations
- Spatial/geographic spread models
- Hospital capacity modeling
This project is licensed under the MIT License - see the LICENSE file for details.
- Compartmental epidemic models: Kermack-McKendrick (1927)
- Network science: Newman, BarabΓ‘si, Watts & Strogatz
- Streamlit community for excellent documentation
For questions or feedback, please open an issue on GitHub or contact the maintainer.
Built with β€οΈ using Python, Streamlit, NetworkX, and Matplotlib