NDlib: a python library to model and analyze diffusion processes over complex networks

Abstract

Nowadays the analysis of dynamics of and on networks represents a hot topic in the social network analysis playground. To support students, teachers, developers and researchers, in this work we introduce a novel framework, namely NDlib, an environment designed to describe diffusion simulations. NDlib is designed to be a multi-level ecosystem that can be fruitfully used by different user segments. For this reason, upon NDlib, we designed a simulation server that allows remote execution of experiments as well as an online visualization tool that abstracts its programmatic interface and makes available the simulation platform to non-technicians.

Appendices

Appendix: diffusion methods implemented in NDlib

NDlib exposes several network diffusion models, covering both epidemic approaches as well as and opinion dynamics. In particular, the actual release of the library (v3.0.0) implements the following algorithms:

Static epidemic models

SI this model was introduced in 1927 by Kermack [19]. In the SI model, during the course of an epidemics, a node is allowed to change its status only from Susceptible (S) to Infected (I). SI assumes that if, during a generic iteration, a susceptible node comes into contact with an infected one, it becomes infected with probability $\beta$: once a node becomes infected, it stays infected (the only transition is $S\rightarrow I$).

SIR this model was still introduced in 1927 by Kermack [19]. In the SIR model, during the course of an epidemics, a node is allowed to change its status from Susceptible (S) to Infected (I), then to Removed (R). SIR assumes that if, during a generic iteration, a susceptible node comes into contact with an infected one, it becomes infected with probability $\beta$, then it can be switch to removed with probability $\gamma$ (the only transition allowed are $S\rightarrow I\rightarrow R$).

SIS as SIR, the SIS model is a variation of the SI model introduced in [19]. The model assumes that if, during a generic iteration, a susceptible node comes into contact with an infected one, it becomes infected with probability $\beta$, then it can switch again to susceptible with probability $\lambda$ (the only transition allowed are $S\rightarrow I\rightarrow S$).

SEIS as the previous models, the SEIS is a variation of the SI model. For many infections, there is a significant incubation period during which the individual has been infected but is not yet infectious themselves. During this period, the individual is in status exposed (E). SEIS assumes that if, during a generic iteration, a susceptible node comes into contact with an infected one, it switches to exposed with probability $\beta$, then it becomes infected with probability $\epsilon$ and then it can switch again to susceptible with probability $\lambda$ (the only transition allowed are $S\rightarrow E \rightarrow I\rightarrow S$).

SEIR as the SEIS models, the SEIR takes into consideration the incubation period, considering the status exposed (E). SEIR assumes that if, during a generic iteration, a susceptible node comes into contact with an infected one, it switches to exposed with probability $\beta$, then it becomes infected with probability $\epsilon$ and then it can switch to removed with probability $\gamma$ (the only transition allowed are $S\rightarrow E \rightarrow I\rightarrow R$).

SWIR this model has four states: Susceptible (S), Infected (I), Recovered (R) and Weakened (W). Besides the usual transaction $S\rightarrow I\rightarrow R$, we have also the transaction $S\rightarrow W \rightarrow I\rightarrow R$. At time stamp n, a node in state I is selected and the state of all its neighbors are checked one by one. If the state of a neighbor is S, then this state changes either (i) to I whit probability $\kappa$ or (ii) to W with likelihood $\mu$. If the state of a neighbor is W, with probability $\nu$ its state changes in I. Then, we repeat for all node in the state I the process and the state for all these nodes become R.

Threshold this model was introduced in 1978 by Granovetter [12]. In the Threshold model during an epidemics, a node has two distinct and mutually exclusive behavioral alternatives, e.g., it can adopt or not a given behavior, participate or not participate in a riot. Nodes individual decision depends on the percentage of its neighbors that have made the same choice, thus imposing a threshold. The model works as follows: each node starts with its own threshold $\tau$ and status (infected or susceptible). During the iteration t, every node is observed: iff the percentage of its neighbors that were infected at time $t-1$ is grater than its threshold, it becomes infected as well.

Kertesz Threshold this model was introduced in 2015 by Ruan et al. [33] and it is an extension of the Watts threshold model [43]. The authors extend the classical model introducing a density r of blocked nodes–nodes which are immune to social influence—and a probability of spontaneous adoption p to capture external influence. Thus, the model distinguishes three kinds of node: Blocked (B), Susceptible (S) and Adopting (A). A node can adopt either under its neighbors influence or due to endogenous effects.

Independent Cascades this model was introduced by Kempe et all in 2003 [18]. The Independent Cascades model starts with an initial set of active nodes $A_0$: the diffusive process unfolds in discrete steps according to the following randomized rule:

• When node v becomes active in step t, it is given a single chance to activate each currently inactive neighbor w; it succeeds with a probability $p_{v,w}$.

• If w has multiple newly activated neighbors, their attempts are sequenced in an arbitrary order.

• If v succeeds, then w will become active in step $t+1$; but whether or not v succeeds, it cannot make any further attempts to activate w in subsequent rounds.

The process runs until no more activations are possible.

Node Profile this model is a variation of the Threshold one, introduced in [25]. It assumes that the diffusion process is only apparent; each node decides to adopt or not a given behavior—once known its existence—only on the basis of its own interests. In this scenario, the peer pressure is completely ruled out from the overall model: it is not important how many of its neighbors have adopted a specific behavior, if the node does not like it, it will not change its interests. Each node has its own profile describing how many it is likely to accept a behavior similar to the one that is currently spreading. The diffusion process starts from a set of nodes that have already adopted a given behavior H: for each of the susceptible nodes in the neighborhood of a node u that has already adopted H, an unbalanced coin is flipped, the unbalance given by the personal profile of the susceptible node; if a positive result is obtained, the susceptible node will adopt the behavior.

Node Profile-Threshold this model, still extension of the Threshold one [25], assumes the existence of node profiles that act as preferential schemas for individual tastes but relax the constraints imposed by the Profile model by letting nodes influenceable via peer pressure mechanisms. The peer pressure is modeled with a threshold. The diffusion process starts from a set of nodes that have already adopted a given behavior H: for each of the susceptible nodes an unbalanced coin is flipped if the percentage of its neighbors that are already infected exceeds its threshold. As in the Profile model, the coin unbalance is given by the personal profile of the susceptible node; if a positive result is obtained, the susceptible node will adopt the behavior.

Dynamic epidemic models

NDlib (starting from v3.0.0) implements dynamic network version of classic compartmental models (SI, SIS, SIR) [26] leveraging DyNetX graph structures. Such models, here shortly described, are defined for snapshot-based as well as temporal networks.

DynSI this model adapts the classical formulation of SI model (where the transition is $S\rightarrow I$) to the snapshot-based topology evolution where the network structure is updated during each iteration. The model applied at day $t_i$ will then use as starting infected set the result of the iteration performed on the interaction graph of the previous day, and as social structure the current one. Such choice implies that not only the interactions of consecutive snapshot could vary but that the node sets can also differ.

DynSIS as the previous dynamic model, the DynSIS adapts the classical formulation of SIS model (where the transition is $S\rightarrow I\rightarrow S$) to the snapshot-based topology evolution where the network structure is updated during each iteration. The DynSIS implementation assumes that the process occurs on a directed/undirected dynamic network.

DynSIR as the previous model, the DynSIS adapts the classical formulation of SIR model (where the transition is $S\rightarrow I\rightarrow R$) to the snapshot-based topology evolution where the network structure is updated during each iteration. The DynSIR implementation assumes that the process occurs on a directed/undirected dynamic network.

Opinion dynamic models

Voter this model is one of the simplest models of opinion dynamics, originally introduced to analyze competition of species [7] and soon after applied to model elections [15]. The model assumes the opinion of an individual to be a discrete variable $\pm \,1$. The state of the population varies based on a very simple update rule: at each iteration, a random individual is selected, who then copies the opinion of one random neighbor. Starting from any initial configuration, on a complete network, the entire population converges to a consensus on one of the two options [22]. The probability that consensus is reached on opinion $+1$ is equal to the initial fraction of individuals holding that opinion.

Snajzd this model [37] is a variant of spin model employing the theory of social impact, which takes into account the fact that a group of individuals with the same opinion can influence their neighbors more than one single individual. In the original model, the social network is a 2-dimensional lattice; however, we also implemented the variant on any complex networks. Each agent has an opinion $\sigma _i=\pm 1$; at each time step, a pair of neighboring agents is selected and, if their opinion coincides, all their neighbors take that opinion. The model has been shown to converge to one of the two agreeing stationary states, depending on the initial density of up-spins (transition at 50% density).

Q-Voter this model was introduced as a generalization of discrete opinion dynamic models [5]. Here, N individuals hold an opinion $\pm \,1$. At each time step, a set of q neighbors are chosen and, if they agree, they influence one neighbor chose at random, i.e., this agent copies the opinion of the group. If the group does not agree, the agent flips its opinion with probability $\epsilon$. It is clear that the voter and Sznajd models are special cases of this more recent model ($q=1, \epsilon =0$ and $q=2, \epsilon =0$, respectively). Analytic results for $q\le 3$ validate the numerical results obtained for the special case models, with transitions from an ordered phase (small $\epsilon$) to a disordered one (large $\epsilon$). For $q>3$, a new type of transition between the two phases appears, which consist of passing through an intermediate regime where the final state depends on the initial condition. We implemented in NDlib the model with $\epsilon =0$.

Majority Rule this model is a different discrete model of opinion dynamics, proposed to describe public debates [11]. Agents take discrete opinions $\pm \,1$, just like the voter model. All agents can interact with all other agents (also in our implementation), so the social network is always a complete graph. At each time step, a group of r agents is selected randomly and they all take the majority opinion within the group. The group size can be fixed or taken at each time step from a specific distribution. If r is odd, then the majority opinion is always defined; however, if r is even, there could be tied situations. To select a prevailing opinion, in this case, a bias in favor of one opinion ($+1$) is introduced. This idea is inspired by the concept of social inertia [10].

Cognitive Opinion Dynamics this model was introduced by Vilone et all. [41], which models the state of individuals taking into account several cognitively grounded variables. The aim is to simulate a response to risk in catastrophic events in the presence of external (institutional) information. The individual opinion is modeled as a continuous variable $O_i \in [0,1]$, representing the degree of perception of the risk (how probable it is that the catastrophic event will actually happen). This opinion evolves through interactions with neighbors and external information, based on four internal variables for each individual i: risk sensitivity ($R_i \in \{-1,0,1\}$), tendency to inform others ($\beta _i \in [0,1]$), trust in institutions ($T_i \in [0,1]$) and trust in peers ($\Pi _i = 1-T_i$). These values are generated when the population is initialized and stay fixed during the simulation. In our implementation, we allow some control on the distribution of these parameters. The update rules define how $O_i$ values change in time (see original paper [41] for details). The model was shown to be able to reproduce well various real situations; in particular, it is visible that risk sensitivity is more important than trust in institutional information when it comes to evaluating risky situations.