Package: epidemiological-model
Epidemiological ModelThis project provides a simulation of an epidemiological model, allowing users to study the dynamics of infectious diseases within a population.Table of ContentsIntroductionFeaturesGetting StartedPrerequisitesInstallationUsageExampleContinuous Integration and Deployment (CI/CD)DockerBuilding the Docker ImageRunning the Docker ContainerInteracting with the ContainerAdditional Docker CommandsLicenseAuthorIntroductionThe Epidemiological Model simulation is a Python-based tool designed to simulate and study the spread of infectious diseases within a population. The primary objective is to provide researchers, epidemiologists, and students with a flexible and customizable platform to explore the dynamics of epidemics.Problem to SolveIn the context of the COVID-19 pandemic and other infectious diseases, understanding the factors influencing the spread of a virus is crucial for effective public health planning. This simulation model addresses the following key questions:Infection Dynamics:How does the infection spread within a population over time, considering factors like the infection rate and recovery rate?Population Impact:What is the impact of different infection rates on the susceptible, infected, and recovered populations?FeaturesStochastic simulation of an epidemiological model with customizable parameters.Visualization of the dynamics over time, including the susceptible, infected, and recovered populations.Analysis of the impact of different infection rates, recovery rates, and intervention strategies on the simulated population.By utilizing this simulation tool, users can gain insights into the complex dynamics of infectious diseases, aiding in the development of informed public health strategies and interventions.Other FeaturesStochastic Epidemiological Simulation:Implement a stochastic epidemiological model that simulates the spread of infectious diseases within a population.Population Compartments:Structure the population into compartments (Susceptible, Infected, Recovered) to capture different states of individuals during the simulation.User-Configurable Parameters:Allow users to configure simulation parameters, including the total population (N), infection rate per interaction (beta), recovery rate (sigma), initial infected individuals, duration of simulaiton time step (dt), and the number of simulation time steps (sim_ts).Discrete Stochastic Model:Convert the deterministic model to a discrete stochastic model using the binomial distribution, providing a more realistic representation of random events in the simulation.Simulation Results:Output simulation results as a 2D NumPy array, capturing the dynamics of the model over time.Visualization:Include a function for visualizing the epidemiological dynamics over time, allowing users to plot the changes in the susceptible, infected, and recovered populations.Project Structuring:Organize the project in a modular and scalable manner, making it easy for future development and collaboration.Testing:Implement tests to ensure the correctness and reliability of the simulation and visualization functions.User-Friendly:Design the project with user-friendliness in mind, enabling researchers to run simulations with ease and flexibility.Documentation:Provide documentation, including README file, code comments, usage examples and instructions for running simulations, to assist in understanding and utilizing the project.Getting StartedTo get started with the epidemiological model simulation, follow these steps:PrerequisitesBefore running the simulation, make sure you have the following installed:Python(>=3.6)NumPyMatplotlibInstallationOption 1: Install via pipEnsure that you have Python (>=3.6) installed on your system.If Python 3 is the only Python version installed on your machine, you can use thepipcommand. For example:pipinstallepidemiological-modelIf both Python 2 and 3 are both installed, it's important to specify Python 3 using thepip3command. For example:pip3installepidemiological-modelOption 2: Clone the repositoryClone the repository:gitclonehttps://github.com/babak2/epidemiological_model.gitNavigate to the project directory:cdepidemiological-model`UsageRun the simulation with the default parameters:If Python 3 is the only Python version installed on your machine, you can use thepythoncommand. For example:python scripts/run_simulation.pyIf both Python 2 and 3 are both installed, it's important to specify Python 3 using thepython3command. For example:python3 scripts/run_simulation.pyOptional Parameters:--N: Total population size (default: 1000)--beta: Infection rate per interaction (default: 10)--sigma: Recovery rate (default: 1)--init_infect: Initial infected individuals (default: 10)--dt: Duration of simulaiton time step for simulation (default: 0.01)--sim_ts: Number of simulation time steps (default: 500)Adjust these parameters based on your research requirements.ExampleYou can customize the simulation parameters by providing command-line arguments:python3 scripts/run_simulation.py --N 40000 --beta 9 --sigma 1 --init_infect 10 --dt 0.01 --sim_ts 500Note: usepythoninstead ofpython3if Python 3 is the only Python version installed on your machine.Running TestsRun the tests using the following command:python3 -m unittest discover -s tests -p "*test_*.py"-s tests: This tells the test discovery process to start looking for tests in thetestsdirectory as the root.-p "*test_*.py": This specifies that it should discover files that match the pattern*test_*.py(files whose names include "test_" and end with ".py").To run a specific test file, use:python3 -m unittest tests.test_filenameReplace filename with the actual filename of the test module.To run a specific test function within a test file, use:python3 -m unittest tests.test_filename.TestClassName.test_function_nameReplace filename, TestClassName, and test_function_name with the actual filename, class name, and test function name, respectively.Note: usepythoninstead ofpython3if Python 3 is the only Python version installed on your machine.Tests examplesTo execute the test suite intest_simulation.py, run:python3 -m unittest tests.test_simulationTo execute thetest_simulation_with_initial_infectionsfunction insidetest_simulation.py, run the following command from the project's root directory:python3 -m unittest tests.test_simulation.TestSimulationFunctions.test_simulation_with_initial_infectionsNote: usepythoninstead ofpython3if Python 3 is the only Python version installed on your machine.Visualizing ResultsThe simulation results will be saved as a visualization plot in the output directory. You can find the generated plot with a filename similar to f_N40000_beta9.0_sigma1_initial10_dt0.01_ts500.png.File Naming Convention:f_: Prefix indicating it's a simulation file output.N40000: Total population size used in the simulation (N followed by its value).beta9.0: Infection rate per interaction used in the simulation (beta followed by rate value).sigma1: Recovery rate used in the simulation (sigma followed by rate value).initial10: Initial infected individuals used in the simulation (initial followed by its value)dt0.01: Duratio of used simulation time step (dt followed by its value).ts500: Number of time steps used in the simulatio (ts followed by its value).This naming convention provides a clear representation of the simulation parameters used to generate the corresponding plot. Adjustments to parameters will result in different filenames, making it easy to organize and identify simulations.If a filefilename.pngalready exists, the script will save the new file with a unique postfix, likefilename_1.png, and continue incrementing the number for each subsequent run.Continuous Integration and Deployment (CI/CD)This project includes a CI/CD pipeline using GitHub Actions to automate the testing and deployment processes. The pipeline is triggered whenever changes are pushed to the master branch or a pull request is opened.CI/CD WorkflowThe CI/CD workflow consists of two main jobs:Build Job:This job runs on every push to the master branch or pull request. It performs the following tasks:Checks out the repository.Sets up the Python environment.Installs project dependencies.Runs tests to ensure the correctness and reliability of the simulation and visualization functions.Deploy Job:This job runs on the completion of the Build job. It performs the following tasks:Checks out the repository.Sets up the Python environment.Installs project dependencies.Deploys the simulation with specific parameters, simulating the spread of infectious diseases with a defined configuration.Triggering the CI/CD PipelineThe CI/CD pipeline is automatically triggered in the following scenarios:On every push to the master branch.When a pull request is opened.Monitoring CI/CD StatusYou can monitor the status of the CI/CD pipeline by checking the GitHub Actions tab in the repository. Successful runs are indicated with a green checkmark, while failures are marked with a red 'X'.Modifying the CI/CD WorkflowYou can modify the CI/CD workflow by updating the.github/workflows/ci-cd.ymlfile. Adjustments can be made to the jobs, steps, and conditions based on your specific requirements.DockerPrerequisitesEnsure that Docker is installed on your system. You can download and install Docker fromhttps://www.docker.com/get-started.Building the Docker ImageBuild the Docker Imagedockerbuild-tepi-model-image.Running the Docker Containerdockerrun--nameepi-model-containerepi-model-imageIf you encounter a naming conflict, remove the existing container first:dockerrmepi-model-containerThen, run the container again.Interacting with the ContainerOpen a Shell in the Containerdockerexec-itepi-model-container/bin/bashAdditional Docker CommandsView Container Logsdockerlogsepi-model-containerRemove Containerdockerrmepi-model-containerRemove Imagedockerrmiepi-model-imageLicenseThis project is licensed under the MIT License - see theLICENSEfile for details.AuthorBabak Mahdavi Ardestanibabak.m.ardestani@gmail.com