Disease Modeling

Instructions

For this project you will be designing and implementing a system, in C++, to simulate an outbreak across a geographic area. Specifically, you will be using a cellular automata, with a Moore neighborhood configuration, to model a geographic region, and a SIR model to model the health states of the populace. Your model should visually output how the regions population changes over time, the final S, I, R, V counts, the day of the outbreaks peak, and the day the outbreak ended.

Additionally, sample input files will be uploaded

Requirements

This project has two parts: a design portion and an implementation portion.

Design Document

For the design portion, you must generate documentation, in PDF format, describing your system and design process. The purpose of this is for you to explain not just what your system is doing, and how it is doing it, but why. You will need to justify your design decisions in a concise, informative manner. Justifications such as I did this because it was easy are not sufficient, as you should actually explain why a particular data structure or algorithm was more efficient, effective, or optimal. Additionally, commented code, while sometimes helpful in small examples, is not a sufficient explanation in and of itself. Your explanations and justifications are expected to be presented in prose and in paragraph format, i.e. not bulleted lists. Further, part of the evaluation of your design document is the apparent amount of thought and effort that went into its creation.

This document should be divided into four main parts, each with an appropriate header.

In the first part, you should describe your design process. Did you work out the algorithm on paper or a whiteboard before hand? Did you draw UML diagrams of the system? Did you create a small prototype? Did you simply start coding away and then recode once or twice with newfound understanding? In a few paragraphs, describe in detail how you went about designing the system, and be sure to provide sufficient justification of your methodology.

For the second part, you should describe the data structures you used in your system. What, if any, objects or structs did you create to store data? How did you organize and manage them? What types of formal data structures did you make use of (trees, graphs, arrays, hashes, etc)? In a few paragraphs, describe in detail how you stored the various data elements in your system, and be sure to provide sufficient justification of your methodology.

For the third part, you should describe functionality of your system. How is data moved and transformed? How is it read in? How is it output? What are the various major functions you constructed and how do they work? In a few paragraphs, describe in detail how your system works, and be sure to provide sufficient justification of your methodology. You might also consider including diagrams to more easily visualize how all of the pieces fit together.

Implementation

Your program must provide the following functionality and adhere to the following constraints:

• Allow the user to choose the file describing the initial setup of the simulation
  • The first line indicates the required number of infectious agents in a susceptible agents neighborhood for the susceptible agent to become infectious on the next day
  • The second line indicates how many days an agent remains infectious before it becomes recovered on the following day, i.e. if the infectious period is 2, then the agent becomes recovered after being infectious for 2 days
  • The third line indicates the display frequently for how frequently the region should be displayed in days
  • All subsequent lines will indicate the starting health states of the different agents in the region

s: susceptible
i: infectious
r: recovered
v: vaccinated

• Agents that are one square away from some other agent are considered to be in that agents neighborhood
• Agents on the left and right boundaries of the region should be considered adjacent, i.e. the region is not a flat map but more like a cylinder
• An agent can have one of four health states: susceptible, infectious, recovered, vaccinated
  • oAn agent can only move through the states as follows: S -> I -> R
  • oA susceptible agent becomes infectious if they have threshold or greater number of infectious agents in their neighborhood on any given day
  • oAn infectious agent becomes recovered after infectious period number of days
  • oVaccinated agents are permanently vaccinated and cannot change states
• The simulation should run until the number of infectious agents is 0, indicating the outbreak has ended. There should only be S, R, and/or V agents left over
• The initial setup of the region represents the simulation at day 0
• Your program should output the following:
  • The initial status of the region, i.e. day 0
  • The status of the region every X days, where X is the display frequency from the input file
  • The final state of the region once the outbreak has ended, i.e. the first day that there are 0 infectious agents
  • The final counts of the number of susceptible, infectious, recovered, and vaccinated agents once the outbreak has ended, i.e. the first day that there are 0 infectious agents
  • The day the outbreak ended
  • The first day of the outbreaks peak in terms of number of infectious agents, i.e. the first day with the highest count of infectious agents
• Your code must be well commented.
• You must provide a short README file which includes your name and explains how to compile and run your program.
• Additionally, you may write a makefile if you want your code to compile with additional flags.

Suggestions

This project requires the use of a few different data structures to store and represent the agents within the model. First, you will need a way to store the grid of the cellular automata. This is a good opportunity to use either vectors or dynamic arrays, as you do not know how big the region is until you have read the entire input file. Then within that grid, you will need to represent each agent. Because each agent maintains both their health state (S,I,R,V) and how long they have been infectious, you should consider using a struct or object. As for the health states themselves, perhaps consider an enumerated type to make checking for states a bit more readable in your code.

Additionally, updating the grid from one day to the next could be done with two grids, one for the current day and one for the next day. Trying to update in place may cause problems, as an agent should not be considered infectious until the day after they have enough infectious agents in their neighborhood. Thus, consider using a temporary grid to determine what the state of the region will be the next day given the state of the region on the current day, and then once it is filled in, overwrite the current day with the next day.

Example Output

Threshold:1
Infectious Period:2
Display:1

Day 0 to Day 4: see image.