fix ICE and ICEP Model and add docs for ICE, ICP and ICEP model

docs/reference/models/epidemics/ICE.rst

@@ -0,0 +1,107 @@
+**************************************************
+Independent Cascades with Community Embeddedness
+**************************************************
+
+The Independent Cascades with Community Embeddedness model was introduced by Milli and Rossetti in 2019 [#]_.
+
+This model is a variation of the well-known Independent Cascade (IC), and it is designed to embed community awareness into the IC model.
+The probability p(u,v) of the IC model is replaced by the edge embeddedness.
+
+The embeddedness of an edge :math:`(u,v)` with :math:`u,v \in C` is defined as:
+:math:`e_{u,v} = \frac{\phi_{u,v}}{|\Gamma(u) \cup \Gamma(v)|}`
+where :math:`\phi_{u,v}` is the number of common neighbors of u and v within :math:`C`, and :math:`\Gamma(u)` ( :math:`\Gamma(v)`) is the set of neighbors of the node u (v) in the analyzed graph G.
+
+The ICE model starts with an initial set of **active** nodes A0; 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 u. If v and u belong to the same community, it succeeds with a probability :math:`e_{u,v}`; otherwise with probability :math:`\min\{e_{z,v}|(z, v)\in E\}`.
+- If u has multiple newly activated neighbors, their attempts are sequenced in an arbitrary order.
+- If v succeeds, then u will become active in step t + 1; but whether or not v succeeds, it cannot make any further attempts to activate u in subsequent rounds.
+- The process runs until no more activations are possible.
+
+--------
+Statuses
+--------
+
+During the simulation a node can experience the following statuses:
+
+===========  ====
+Name         Code
+===========  ====
+Susceptible  0
+Infected     1
+Removed      2
+===========  ====
+
+
+----------
+Parameters
+----------
+
+The model is parameter free
+
+The initial infection status can be defined via:
+
+    - **fraction_infected**: Model Parameter, float in [0, 1]
+    - **Infected**: Status Parameter, set of nodes
+
+The two options are mutually exclusive and the latter takes precedence over the former.
+
+-------
+Methods
+-------
+
+The following class methods are made available to configure, describe and execute the simulation:
+
+^^^^^^^^^
+Configure
+^^^^^^^^^
+
+.. autoclass:: ndlib.models.epidemics.ICEModel.ICEModel
+.. automethod:: ndlib.models.epidemics.ICEModel.ICEModel.__init__(graph)
+
+.. automethod:: ndlib.models.epidemics.ICEModel.ICEModel.set_initial_status(self, configuration)
+.. automethod:: ndlib.models.epidemics.ICEModel.ICEModel.reset(self)
+
+^^^^^^^^
+Describe
+^^^^^^^^
+
+.. automethod:: ndlib.models.epidemics.ICEModel.ICEModel.get_info(self)
+.. automethod:: ndlib.models.epidemics.ICEModel.ICEModel.get_status_map(self)
+
+^^^^^^^^^^^^^^^^^^
+Execute Simulation
+^^^^^^^^^^^^^^^^^^
+.. automethod:: ndlib.models.epidemics.ICEModel.ICEModel.iteration(self)
+.. automethod:: ndlib.models.epidemics.ICEModel.ICEModel.iteration_bunch(self, bunch_size)
+
+-------
+Example
+-------
+
+In the code below is shown an example of instantiation and execution of an ICE model simulation on a random graph: we set the initial set of infected nodes as 1% of the overall population.
+
+
+.. code-block:: python
+
+    import networkx as nx
+    import ndlib.models.ModelConfig as mc
+    import ndlib.models.epidemics as ep
+
+    # Network topology
+    g = nx.erdos_renyi_graph(1000, 0.1)
+
+    # Model selection
+    model = ep.ICEModel(g)
+
+    # Model Configuration
+    config = mc.Configuration()
+    config.add_model_parameter('fraction_infected', 0.1)
+
+    model.set_initial_status(config)
+
+    # Simulation execution
+    iterations = model.iteration_bunch(200)
+
+
+.. [#] L. Milli and G. Rossetti. “Community-Aware Content Diffusion: Embeddednes and Permeability,” in Proceedings of International Conference on Complex Networks and Their Applications, 2019 pp. 362--371.

docs/reference/models/epidemics/ICEP.rst

@@ -0,0 +1,114 @@
+******************************************************************
+Independent Cascades with Community Embeddedness and Permeability
+******************************************************************
+
+The Independent Cascades with Community Embeddedness and Permeability model was introduced by Milli and Rossetti in 2020 [#]_.
+
+This model is a combination of ICE and ICP methods.
+
+The ICEP model starts with an initial set of **active** nodes A0; 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 u. If v and u belong to the same community, the method acts as the ICE model, otherwise as the ICP model.
+- If u has multiple newly activated neighbors, their attempts are sequenced in an arbitrary order.
+- If v succeeds, then u will become active in step t + 1; but whether or not v succeeds, it cannot make any further attempts to activate u in subsequent rounds.
+- The process runs until no more activations are possible.
+
+--------
+Statuses
+--------
+
+During the simulation a node can experience the following statuses:
+
+===========  ====
+Name         Code
+===========  ====
+Susceptible  0
+Infected     1
+Removed      2
+===========  ====
+
+
+----------
+Parameters
+----------
+
+======================  =====  ===============  =======  =========  ======================
+Name                    Type   Value Type       Default  Mandatory  Description
+======================  =====  ===============  =======  =========  ======================
+Edge threshold          Edge   float in [0, 1]   0.1     False      Edge threshold
+Community permeability  Model  float in [0, 1]   0.5     True       Community Permeability
+======================  =====  ===============  =======  =========  ======================
+
+The initial infection status can be defined via:
+
+    - **fraction_infected**: Model Parameter, float in [0, 1]
+    - **Infected**: Status Parameter, set of nodes
+
+The two options are mutually exclusive and the latter takes precedence over the former.
+
+-------
+Methods
+-------
+
+The following class methods are made available to configure, describe and execute the simulation:
+
+^^^^^^^^^
+Configure
+^^^^^^^^^
+
+.. autoclass:: ndlib.models.epidemics.ICEPModel.ICEPModel
+.. automethod:: ndlib.models.epidemics.ICEPModel.ICEPModel.__init__(graph)
+
+.. automethod:: ndlib.models.epidemics.ICEPModel.ICEPModel.set_initial_status(self, configuration)
+.. automethod:: ndlib.models.epidemics.ICEPModel.ICEPModel.reset(self)
+
+^^^^^^^^
+Describe
+^^^^^^^^
+
+.. automethod:: ndlib.models.epidemics.ICEPModel.ICEPModel.get_info(self)
+.. automethod:: ndlib.models.epidemics.ICEPModel.ICEPModel.get_status_map(self)
+
+^^^^^^^^^^^^^^^^^^
+Execute Simulation
+^^^^^^^^^^^^^^^^^^
+.. automethod:: ndlib.models.epidemics.ICEPModel.ICEPModel.iteration(self)
+.. automethod:: ndlib.models.epidemics.ICEPModel.ICEPModel.iteration_bunch(self, bunch_size)
+
+-------
+Example
+-------
+
+In the code below is shown an example of instantiation and execution of an ICEP model simulation on a random graph: we set the initial set of infected nodes as 1% of the overall population, assign a threshold of 0.1 to all the edges and set the community permeability equal 0.3.
+
+
+.. code-block:: python
+
+    import networkx as nx
+    import ndlib.models.ModelConfig as mc
+    import ndlib.models.epidemics as ep
+
+    # Network topology
+    g = nx.erdos_renyi_graph(1000, 0.1)
+
+    # Model selection
+    model = ep.ICEPModel(g)
+
+    # Model Configuration
+    config = mc.Configuration()
+    config.add_model_parameter('fraction_infected', 0.1)
+    config.add_model_parameter('permeability', 0.3)
+
+
+    # Setting the edge parameters
+    threshold = 0.1
+    for e in g.edges():
+        config.add_edge_configuration("threshold", e, threshold)
+
+    model.set_initial_status(config)
+
+    # Simulation execution
+    iterations = model.iteration_bunch(200)
+
+
+.. [#] L. Milli and G. Rossetti. “Barriers or Accelerators? Modeling the two-foldnature of meso-scale network topologies indiffusive phenomena,” 2020

docs/reference/models/epidemics/ICP.rst

@@ -0,0 +1,116 @@
+**************************************************
+Independent Cascades with Community Permeability
+**************************************************
+
+The Independent Cascades with Community Permeability model was introduced by Milli and Rossetti in 2019 [#]_.
+
+This model is a variation of the well-known Independent Cascade (IC), and it is designed to embed community awareness into the IC model.
+This model exploits the idea of permeability. A community is “permeable” to a given content if it permits that content to spread from it fast
+(or  vice-versa,  if  it  permits  the  content  to  be  easily  received  from  nodes  outside the  community).  Conversely,  a  community  has  a  low  degree  of  permeability  if  it dampens the diffusion probability across its border.
+
+The ICP model starts with an initial set of **active** nodes A0; 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 u. If v and u belong to the same community, the method works as a standard IC model (it succeeds with a probability p(v,u)); instead, if the nodes are part of to different communities, the likelihood p(v,u) is dampened of a factor :math:`\eta` (the community permeability parameter).
+- If u has multiple newly activated neighbors, their attempts are sequenced in an arbitrary order.
+- If v succeeds, then u will become active in step t + 1; but whether or not v succeeds, it cannot make any further attempts to activate u in subsequent rounds.
+- The process runs until no more activations are possible.
+
+--------
+Statuses
+--------
+
+During the simulation a node can experience the following statuses:
+
+===========  ====
+Name         Code
+===========  ====
+Susceptible  0
+Infected     1
+Removed      2
+===========  ====
+
+
+----------
+Parameters
+----------
+
+======================  =====  ===============  =======  =========  ======================
+Name                    Type   Value Type       Default  Mandatory  Description
+======================  =====  ===============  =======  =========  ======================
+Edge threshold          Edge   float in [0, 1]   0.1     False      Edge threshold
+Community permeability  Model  float in [0, 1]   0.5     True       Community Permeability
+======================  =====  ===============  =======  =========  ======================
+
+The initial infection status can be defined via:
+
+    - **fraction_infected**: Model Parameter, float in [0, 1]
+    - **Infected**: Status Parameter, set of nodes
+
+The two options are mutually exclusive and the latter takes precedence over the former.
+
+-------
+Methods
+-------
+
+The following class methods are made available to configure, describe and execute the simulation:
+
+^^^^^^^^^
+Configure
+^^^^^^^^^
+
+.. autoclass:: ndlib.models.epidemics.ICPModel.IndependentCascadesModel
+.. automethod:: ndlib.models.epidemics.ICPModel.ICPModel.__init__(graph)
+
+.. automethod:: ndlib.models.epidemics.ICPModel.ICPModel.set_initial_status(self, configuration)
+.. automethod:: ndlib.models.epidemics.ICPModel.ICPModel.reset(self)
+
+^^^^^^^^
+Describe
+^^^^^^^^
+
+.. automethod:: ndlib.models.epidemics.ICPModel.ICPModel.get_info(self)
+.. automethod:: ndlib.models.epidemics.ICPModel.ICPModel.get_status_map(self)
+
+^^^^^^^^^^^^^^^^^^
+Execute Simulation
+^^^^^^^^^^^^^^^^^^
+.. automethod:: ndlib.models.epidemics.ICPModel.ICPModel.iteration(self)
+.. automethod:: ndlib.models.epidemics.ICPModel.ICPModel.iteration_bunch(self, bunch_size)
+
+-------
+Example
+-------
+
+In the code below is shown an example of instantiation and execution of an ICP model simulation on a random graph: we set the initial set of infected nodes as 1% of the overall population, assign a threshold of 0.1 to all the edges and set the community permeability equal 0.3.
+
+
+.. code-block:: python
+
+    import networkx as nx
+    import ndlib.models.ModelConfig as mc
+    import ndlib.models.epidemics as ep
+
+    # Network topology
+    g = nx.erdos_renyi_graph(1000, 0.1)
+
+    # Model selection
+    model = ep.ICPModel(g)
+
+    # Model Configuration
+    config = mc.Configuration()
+    config.add_model_parameter('fraction_infected', 0.1)
+    config.add_model_parameter('permeability', 0.3)
+
+
+    # Setting the edge parameters
+    threshold = 0.1
+    for e in g.edges():
+        config.add_edge_configuration("threshold", e, threshold)
+
+    model.set_initial_status(config)
+
+    # Simulation execution
+    iterations = model.iteration_bunch(200)
+
+
+.. [#] L. Milli and G. Rossetti. “Community-Aware Content Diffusion: Embeddednes and Permeability,” in Proceedings of International Conference on Complex Networks and Their Applications, 2019 pp. 362--371.

docs/reference/reference.rst

@@ -50,6 +50,9 @@ In ``NDlib`` are implemented the following **Epidemic** models:
    models/epidemics/Profile.rst
    models/epidemics/ProfileThreshold.rst
    models/epidemics/UTLDR.rst
+   models/epidemics/ICEP.rst
+   models/epidemics/ICP.rst
+   models/epidemics/ICE.rst
 
 
 ----------------