Author: Manuel Capel
This is the implementation in Python of a propagation model that we propose to call CAST as Cell Agent State Transitions. Its purpose is modeling the propagation of epidemics and the impact of actions to counter it. See medium article.
🇫🇷 For French, see this blog article
pip install propagsim
See this notebook for a (toy) example of an implementation of this model
Basically, this model considers three types of object:
- Cell. A cell can contain 0, 1 or many agents at any time. It has also a position (Euclidean coordinates on a plan)
- Agent. An agent has one (and only one) state at a given moment, and is also in one (and only one) cell. The cell where an agent is initially is considered to be its home_cell.
- State. A state has a predefined severity, contagiousity and sensitivity, all in (0, 1)
A contagion happens within a cell, when it contains several agents at the same time and one of them is contagious. When an agent has a state with contagiousity > 0, then the other agents in the same cell can get infected. The probability of Agent_A to contaminate Agent_B in cell is given by:
NB:
- The highest contagiousity in the cell is taken to compute p.
- The unsafety of a cell measures how a cell is unsafe for contagion (social distancing respected or not inside etc.)
If Agent_B gets infected, it gets to its own state having the least strictly positive severity (it can't jump directly to a more severe state).
A state transition matrix and state durations are attached to each agent. The state transition matrix is a Markovian matrix describing the transition probabilities between the states an agent can take. The state durations are the duration of each state. If a agent is in a given state, it will switch to another one sampled according to its state transition matrix
NB: Different agents can share the same states and the same state transition matrix but have different state durations, or have have the same state, the same state durations but a different state transition matrix, or etc.
A move consists in moving agents to other cells. When a move is done, all agents are concerned. It happens it two steps:
- Selecting agents that will move
- moving the selected agents to their new cells
The probability of an agent to be selected for a move is:
The first factor represents the mobility of the agent so to say. The second factor represents the fact that the more severe the state of an agent, the less the probability that it will move.
The cell where to move a selected agent is sampled according to a probability
NB:
- a limitation of this model is that the attractivity of each cell is the same for all agent. An extension / refinement of this model would be to have cell attractivities personalized by agent.
- The distance is always computed from the home_cell of an agent, not from its current_cell. An agent is considered wandering around its home_cell
- The agents not selected for a move will be moved to their home_cell afterward
Each time period contains move rounds (they don't have to have all the same number of move rounds). During each move round, agents are selected and moved as described above. Id they are infected, they can infect other agents in the same cell than themselves. A time period finishes when all agents are simultanously forwarded. Each agent is actually in a given state, that has a given duration. By a forward, the time in this state is incremented by 1. If this time then exceeds the duration of the current state of the agent, the agent moves to the next state according to its transition described above.
Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.
Please make sure to update tests as appropriate.