Package: epidemix
BriefThis package is designed to analyze the network diffusion, such as epidemic spreading and information distribution, motivated by the serious COVID19 pandemic since the end of 2019. The process of network diffusion can be simulated based on the assumption of certain predefined states for each entity and the simulation can be described mathematically under a set of ordinary differential equations (ODE). Except for the models provided by this package, the states and differential equations can also be customized by yourself. In this package, a set of ODE can be applied to the following 2 perspectives:A whole populationA Network composed of edges and nodesSince the virus is the priority task to study, the models provided by this package are all related to epidemics includingSI,SIS,SIR, andSIRV. In order to analyze the epidemic, the spreading process can be split into the following states so that mathematical model can be built up accordingly:S - SusceptableI - InfectedR - RecoveredThis is also called SIR model. Sometimes, the model can be even more easier containing only S and I states so that the mathematical mechanism can be better understood. The famous SIR model can not only be applied on the total number of a group of people, but also be able to be implemented to a network composed of nodes and edges. To represent each person by one node and define the relationship between 2 people as the edge connected to the 2 nodes, we can model the society mathematically. A certain epidemic is spreaded throughout the social network from those infected people. By calculating the probabilistic states, i.e:Si(t) probability that node i issusceptibleat time tXi(t) probability that node i isinfectedat time tRi(t) probability that node i isrecoveredat time talong with the coefficients such that:β : individual transmission / infection rateγ : recovery rateWe will be capable of tracking the state of each node along the time line. Combining with the undirected graph structure, which is also called a network, the original simple SIR model is transformed from deteministic to probabilistic description.RequirementsThis package is developed based on the following dependencies:cdlibnetworkxnumpyscipymatplotlibtqdmp.s. The programming language should bePython3.Install epidemixpipinstallepidemixAnd the required dependencies will also be installed automatically.The Reproduction RateThere is a famous factor R0, which is also called: basic reproduction nnumber. This factor indicates the average number of people being infected by an infected person. If R0 > 1, it means that the disease will keep spreading in the society. On the other hand, if R0 < 1, it implies that the infected population will converge and the disease will not spread persistently.Disease-Transmission-R0Measles麻疹Airborne空气传播12~18Pertussis百日咳Airborne droplet空气飞沫12~17Diptheria白喉Saliva唾液6~7Smallpox天花Social Contact社交接触5~7Polio小儿麻痹Fecal-oral route粪口5~7Rubelia风疹Airborne droplet空气飞沫5~7Mumps流行性腮腺炎Airborne droplet空气飞沫4~7HIV / AIDS艾滋病Sexual contact性传播2~5SARS非典型肺炎Airborne droplet空气飞沫2~5Simulation Under a PopulationThe predefined epidemic models can be imported fromepidemixaccording to the following code:fromepidemix.macroimportSI,SIS,SIR,SIRS,SEIR,SEIRDTo activate the model and visualize the results of the model, we need the following extra packages and function calledEpiModel.importnumpyasnpimportmatplotlib.pyplotaspltfromepidemix.macroimportEpiModelNext, the model can be instantiated by defining the total number of entity in a targeted population, initial infected number, initial recovered number, transmission rate, and recover rate such that:sir=SIR(1000,I0=50,R0=0,beta=0.4,gamma=0.1)To solve the equation, a period of time should be setup where the interval can be any range according to different conditions.days=np.linspace(0,80,80)Finally, the simulation can be made byEpiModel.epi=EpiModel(sir)s,i,r=epi.simulate(days)The trend of state transition can be visualized as follows.fig=plt.figure(facecolor='w')plt.plot(days,s/sis.N,'b',alpha=0.5,lw=2,label='Susceptible')plt.plot(days,i/sis.N,'r',alpha=0.5,lw=2,label='Infected')plt.plot(days,r/sis.N,'g',alpha=0.5,lw=2,label='Recovered')plt.xlabel('Time /days')plt.ylabel('Number (1000s)')plt.grid(True)plt.legend()plt.show()Model Customization - MacroTo customize an epidemic model, we need to write down a set of differential equations in advance.fromepidemix.macroimportMacroODEclassSIR(MacroODE):def__init__(self,N,I0,R0,beta,gamma):self.N=Nself.I0=I0self.R0=R0self.S0=N-I0-R0self.initial=(self.S0,I0,R0)self.beta=betaself.gamma=gammaself.reproduction_num=beta/gamma# Definition of "R_0".defderivative(self,y,t):S,I,R=ydSdt=-self.beta*S*I/self.NdIdt=self.beta*S*I/self.N-self.gamma*IdRdt=self.gamma*IreturndSdt,dIdt,dRdtMind that the parametersself.initialandself.Nshould be defined in the__init__function and the main body of the differential equations should be defined inderivativefunction accordingly.Simulation Under a NetworkThe predefined epidemic models can be imported fromepidemixaccording to the following code:fromepidemix.equationsimportSI,SIS,SIR,SIRVThese classes are the default Ordinary Differential Equations (ODE) functions that can be used to simulate in a network. Before starting the simulation, we need the other dependencies, along with the function defined inepidemixsuch that:importnumpyasnpimportnetworkxasnxfromepidemix.epidemicimportEpiModelfromutils.plotimportdraw_probswhereEpiModelis the most important API being responsible for both network simulation and disease propagation, which shares the same name as the one fromepidemix.macro. In addition, a given time period is crucial in order to solve ODEs. A timeline should also be generated here.days=np.arange(0,10,0.1)1. Network InitializationWhatever types of network can be generated so that the simulation can be activated based on the network.num_node=50# G = nx.watts_strogatz_graph(num_node, 5, 0.4)     # Small world# G = nx.powerlaw_cluster_graph(num_node, 5, 0.4)   # Power lawG=nx.gnp_random_graph(num_node,0.08)# Random2. InstantiationTake the selected ODEs and Graph (network) intoEpiModelalong with some parameters. Mind that the function will passparamsintoSIRODEs. Namely, the parameters listed here are specifically prepared for SIR function.# Note --> SIR  params: I0, R0, beta, gammaepi=EpiModel(G,SIR,num_state=3,params=[4,2,0.4,0.2])3. SimulateAs the parameters are all settled down, the simulation can begin according to the time period. If it is a SIR model, the output would be 3 states where each state is a 2D matrix. The number of row will be defined by the total number of time unit and the number of column will be decided by the total number of node in a network. Each number in the matrix represents the probability that a node staying at THAT corresponding state in a specific moment.s,i,r=epi.simulate(days)The function will help you get the probability with respect to each time interval.4. State PropagationSo far, we only get the probabilities of each state for all nodes. However, the deterministic state of each node at time t remains unknown. Although the trend of the probabilities can guide the transformation of each node, we still need to define the sequence first so that the computer can know how to propagate between nodes and between states. In SIR case, S will be turned into I and I will be turned into R.epi.set_propagate(0, 1, neighbor=1, update_state=False)
epi.set_propagate(1, 2, neighbor=None, update_state=False)
status, _ = epi.propagation()set_propagatemethod has 4 parameters (from, to, neighbor, update_state). If SIR is defined properly, 012 will represent SIR respectively and the setup should be done by the number.neighbormeans that the state transition will happen only when the neighbor of the node hasneighborkind of neighbor. S will be infected only when it has $1\rightarrow infected$ neighbors. As for the parameterupdate_state, it is used to deal with the split state transition. If one node can be transformed into 2 optional states, it should follow a sequence. The state that is transformed later should turn it intoTrue.Finally, the network simulation can be visualized by applying the following function, where status records all the information during network propagation including the actual state of each node, the color of each node, etc. The second parameter indicates what moment we want to observe. The third, forth, and fifth parameters are used to adjust the shape of the plotted result. Therefore, it is better that the number of row and column is in accordance with the number of time interval.epi.visualize(status,np.arange(16),figsize=(15,15),n_row=4,n_col=4)Self-defined Model: S → I → RExcept for the default epidemic models being defined inepidemix, people can also customize their model according to their need. Take SIR model for example here, we assume that the recovered nodes will never get the disease again. The ODE set is formulated as follows:The adjacent matrix (A) describe the network architecture so that the S nodes can only be contaminated when they have infected neighbors. If there is a connection between 2 nodes, the value would be 1. Otherwise, it would be 0 such that:A = array([[0, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
           [1, 0, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 1],
           [1, 1, 0, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
           [0, 1, 1, 0, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
           [0, 0, 1, 1, 0, 1, 1, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
           [0, 0, 0, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 1, 0],
           [0, 0, 0, 0, 1, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0],
           [0, 0, 0, 0, 0, 0, 1, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1],
           [0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0],
           [0, 0, 0, 0, 0, 0, 0, 1, 1, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0],
           [0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 0, 0, 1, 0, 1, 0, 0, 0, 0, 0],
           [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 1, 0],
           [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 0, 1, 1, 0, 0, 0, 0, 1],
           [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0, 1, 1, 0, 0, 1, 0],
           [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0, 1, 1, 0, 1, 1, 0, 0, 0],
           [0, 1, 0, 0, 0, 1, 1, 0, 0, 0, 0, 0, 0, 1, 1, 0, 1, 0, 0, 0],
           [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 0, 1, 1, 0],
           [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0, 1, 1],
           [0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 1, 0, 1, 0, 0, 1, 1, 0, 1],
           [0, 1, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 1, 0]],
          dtype=int64)Construct SIR Model with Python CodeThe ODE set should be defined in a class inherited fromNetworkODEclass.fromepidemix.equationsimportNetworkODEThere are also 2 important and identical parts comparing to the one for a pupulation:__init__method to initialize the probabilities with respect to different states.derivativemethod to formulate ODE.classSIR(NetworkODE):def__init__(self,A,I0,R0,beta,gamma):# numpy 2D Adjacent matrixself.A=Aself.N=len(A)# Randomly assign the non-repeated infected and recovered nodes.idx=np.random.choice(np.arange(self.N),I0+R0,replace=False)self.I0=np.zeros((self.N,))self.R0=np.zeros((self.N,))self.I0[idx[:I0]]=1self.R0[idx[I0:I0+R0]]=1# Init matrix should be stacked into a 1D array.self.initial=np.hstack([1-self.I0-self.R0,# s(t)self.I0,# i(t)self.R0])# r(t)self.beta=betaself.gamma=gammaself.reproduction_num=beta/gamma# Definition of "R_0".defderivative(self,z,t):# The initial "z" starts from "self.initial".b=self.beta*z[0:self.N]*np.dot(self.A,z[self.N:2*self.N])r=self.gamma*z[self.N:2*self.N]returnnp.hstack([-b,b-r,r])If we have 10 nodes in a network,self.initialattribute would be a vector with length 10 x #state​, which is 30 in SIR case. Mind that there are 2 parameters that must be defined here:self.Afor saving the adjacent matrix.self.Nfor saving the total number of node, which is equal tolen(self.A).As a class is properly defined above, it can be put intoEpiModelfor further simulation. Mind that the parameters defined in the SIR__init__class will be set up asEpiModelis instantiated withparamssettings.CitationImpact of Vaccination Strategies for Epidemic Node-level SVIR Probabilistic Model. 2020. CL Kuo, MX Chen, WK Victor Chan.LicenseCopyright (c) 2020, Kuo Chun-Lin
All rights reserved.Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:Redistributions of source code must retain the above copyright notice, this
list of conditions and the following disclaimer.Redistributions in binary form must reproduce the above copyright notice,
this list of conditions and the following disclaimer in the documentation
and/or other materials provided with the distribution.THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.