docs update

docs/developer/ndlib/DiffusionModel.rst

@@ -84,31 +84,48 @@ To do so, the ``iteration()`` method of the base class has to be overridden in `
 
 .. code-block:: python
 
-	def iteration(self):
+	def iteration(self, node_status=True):
 
-		# Set initial node statuses
-		actual_status = {node: nstatus for node, nstatus in self.status.items()}
+		self.clean_initial_status(self.available_statuses.values())
 
-		# first iteration
+		# if first iteration return the initial node status
 		if self.actual_iteration == 0:
 			self.actual_iteration += 1
-			return 0, actual_status
+			delta, node_count, status_delta = self.status_delta(actual_status)
+			if node_status:
+				return {"iteration": 0, "status": actual_status.copy(),
+						"node_count": node_count.copy(), "status_delta": status_delta.copy()}
+			else:
+				return {"iteration": 0, "status": {},
+						"node_count": node_count.copy(), "status_delta": status_delta.copy()}
+
+		actual_status = {node: nstatus for node, nstatus in self.status.iteritems()}
 
 		# iteration inner loop
 		for u in self.graph.nodes():
-			# Iteration updates
+			# evluate possible status changes using the model parameters (accessible via self.params)
+			# e.g. self.params['beta'], self.param['nodes']['threshold'][u], self.params['edges'][(id_node0, idnode1)]
+
+		# identify the changes w.r.t. previous iteration
+		delta, node_count, status_delta = self.status_delta(actual_status)
 
-		# Incremental result
-		delta = self.status_delta(actual_status)
+		# update the actual status and iterative step
 		self.status = actual_status
 		self.actual_iteration += 1
 
-		return self.actual_iteration - 1, delta
+		# return the actual configuration (only nodes with status updates)
+		if node_status:
+			return {"iteration": self.actual_iteration - 1, "status": delta.copy(),
+					"node_count": node_count.copy(), "status_delta": status_delta.copy()}
+		else:
+			return {"iteration": self.actual_iteration - 1, "status": {},
+			"node_count": node_count.copy(), "status_delta": status_delta.copy()}
+
 
 The provided template is composed by 4 steps:
 
-1. making a copy of the actual diffusion status;
-2. first iteration handling: if present the model returns as result of the first iteration is initial status;
+1. first iteration handling: if present the model returns as result of the first iteration is initial status;
+2. making a copy of the actual diffusion status;
 3. iteration loop: definition, and application, of the rules that regulates individual node status transitions;
 4. construction of the incremental result.
 

docs/developer/ndlib/DiffusionViz.rst

@@ -2,12 +2,20 @@
 Describe a Visuzlization
 ************************
 
-All the bokeh visualizations implemented so far in ``NDlib`` extends the abstract class ``nndlib.viz.bokeh.DiffusionViz.DiffusionPlot``.
+All the ``matplotlib`` visualizations implemented so far in ``NDlib`` extends the abstract class ``nndlib.viz.mpl.DiffusionViz.DiffusionPlot``.
+
+.. autoclass:: ndlib.viz.mpl.DiffusionViz.DiffusionPlot
+
+Conversely, visualizations that use the ``bokeh`` library, should extend the abstract class ``nndlib.viz.bokeh.DiffusionViz.DiffusionPlot``.
 
 .. autoclass:: ndlib.viz.bokeh.DiffusionViz.DiffusionPlot
 
+Here is introduced the pattern for describing novel ``matplotlib`` based visualization, ``bokeh`` ones following the same rationale.
+
+
 So far ``DiffusionPlot`` implements the visualization logic *only* for generic **trend line plot** built upon simulation iterations and model metadata.
 
+
 --------------------
 Line Plot Definition
 --------------------
@@ -21,15 +29,14 @@ In oder to effectively describe the visualization the ``__init__`` function of `
 
 .. code-block:: python
 
-	from ndlib.viz.bokeh.DiffusionViz import DiffusionPlot
+	from ndlib.viz.mpl.DiffusionViz import DiffusionPlot
 
 	class MyViz(DiffusionPlot):
 
-		def __init__(self, model, iterations):
-			super(self.__class__, self).__init__(model, iterations)
-			self.ylabel = "Y label"
-			self.xlabel = "X label"
-			self.title = "Plot Title"
+		def __init__(self, model, trends):
+			super(self.__class__, self).__init__(model, trends)
+			self.ylabel = "#Nodes"
+			self.title = "Diffusion Trend"
 
 
 ----------------
@@ -38,9 +45,9 @@ Data Preparation
 
 Once described the plot metadata it is necessary to prepare the data to be visualized through the ``plot()`` method.
 
-To do so, the ``iteration_series()`` method of the base class has to be overridden in ``MyViz``.
+To do so, the ``iteration_series(percentile)`` method of the base class has to be overridden in ``MyViz``.
 
-.. automethod:: ndlib.viz.bokeh.DiffusionViz.DiffusionPlot.iteration_series(self)
+.. automethod:: ndlib.viz.bokeh.DiffusionViz.DiffusionPlot.iteration_series(self, percentile)
 
-Such method can access the iterations data, as returned by ``ndlib.models.DiffusionModel.DiffusionModel.iteration_bunch(self, bunch_size)`` in ``self.iterations``.
+Such method can access the trend data, as returned by ``ndlib.models.DiffusionModel.DiffusionModel.build_trends(self, iterations)`` in ``self.iterations``.
 

docs/reference/models/epidemics/IndependentCascades.rst

@@ -76,7 +76,7 @@ Execute Simulation
 Example
 -------
 
-In the code below is shown an example of istantiation and execution of an Independent Cascades model simultion on a random graph: we set the initial set of infected nodes as 1% of the overall population, and assign a threshold of 0.1 to all the edges.
+In the code below is shown an example of instantiation and execution of an Independent Cascades model simulation on a random graph: we set the initial set of infected nodes as 1% of the overall population, and assign a threshold of 0.1 to all the edges.
 
 
 .. code-block:: python

docs/reference/models/epidemics/KThreshold.rst

@@ -80,7 +80,7 @@ Execute Simulation
 Example
 -------
 
-In the code below is shown an example of istantiation and execution of a Kertesz Threshold model simultion on a random graph: we set the initial infected as well blocked node sets equals to the 10% of the overall population, assign a threshold of 0.25 to all the nodes and impose an probability of spontaneous adoptions of 40%.
+In the code below is shown an example of instantiation and execution of a Kertesz Threshold model simulation on a random graph: we set the initial infected as well blocked node sets equals to the 10% of the overall population, assign a threshold of 0.25 to all the nodes and impose an probability of spontaneous adoptions of 40%.
 
 
 .. code-block:: python
@@ -112,5 +112,5 @@ In the code below is shown an example of istantiation and execution of a Kertesz
     iterations = model.iteration_bunch(200)
 
 
-.. [#] Z. Ruan, G. In ̃iguez, M. Karsai, and J. Kerte ́sz, “Kinetics of social contagion,” Phys. Rev. Lett., vol. 115, p. 218702, Nov 2015.
+.. [#] Z. Ruan, G. In ̃iguez, M. Karsai, and J. Kertész, “Kinetics of social contagion,” Phys. Rev. Lett., vol. 115, p. 218702, Nov 2015.
 .. [#] D. J. Watts, “A simple model of global cascades on random networks,” Proceedings of the National Academy of Sciences, vol. 99, no. 9, pp. 5766–5771, 2002.

docs/reference/models/epidemics/Profile.rst

@@ -10,8 +10,10 @@ Each node has its own profile describing how many it is likely to accept a behav
 
 The diffusion process starts from a set of nodes that have already adopted a given behaviour S:
 
--  for each of the susceptible nodes' in the neighborhood of a node u in S an unbalanced coin is flipped, the unbalance given by the personal profile of the susceptible node;
+- for each of the susceptible nodes' in the neighborhood of a node u in S 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 behaviour, thus becoming infected.
+- if the **blocked** status is enabled, after having rejected the adoption with probability ``blocked`` a node becomes immune to the infection.
+- every iteration ``adopter_rate`` percentage of nodes spontaneous became infected to endogenous effects.
 
 
 
@@ -26,17 +28,20 @@ Name         Code
 ===========  ====
 Susceptible  0
 Infected     1
+Blocked      -1
 ===========  ====
 
 ----------
 Parameters
 ----------
 
-=========  =====  ===============  =======  =========  ============
-Name       Type   Value Type       Default  Mandatory  Description
-=========  =====  ===============  =======  =========  ============
-profile    Node   float in [0, 1]   0.1     False      Node profile
-=========  =====  ===============  =======  =========  ============
+============  =====  ===============  =======  =========  ===================
+Name          Type   Value Type       Default  Mandatory  Description
+============  =====  ===============  =======  =========  ===================
+profile       Node   float in [0, 1]   0.1     False      Node profile
+blocked       Model  float in [0, 1]   0       False      Blocked nodes
+adopter_rate  Model  float in [0, 1]   0       False      Autonomous adoption
+============  =====  ===============  =======  =========  ===================
 
 The initial infection status can be defined via:
 
@@ -78,7 +83,7 @@ Execute Simulation
 Example
 -------
 
-In the code below is shown an example of istantiation and execution of a Profile model simultion on a random graph: we set the initial infected node set to the 10% of the overall population and assign a profile of 0.25 to all the nodes.
+In the code below is shown an example of instantiation and execution of a Profile model simulation on a random graph: we set the initial infected node set to the 10% of the overall population and assign a profile of 0.25 to all the nodes.
 
 .. code-block:: python
 
@@ -92,6 +97,8 @@ In the code below is shown an example of istantiation and execution of a Profile
     # Model selection
     model = pr.ProfileModel(g)
     config = mc.Configuration()
+    config.add_model_parameter('blocked', 0)
+    config.add_model_parameter('adopter_rate', 0)
     config.add_model_parameter('percentage_infected', 0.1)
 
     # Setting nodes parameters

docs/reference/models/epidemics/ProfileThreshold.rst

@@ -8,9 +8,10 @@ The peer pressure is modeled with a threshold.
 
 The diffusion process starts from a set of nodes that have already adopted a given behaviour S:
 
--  for each of the susceptible node an unbalanced coin is flipped if the percentage of its neighbors that are already infected excedes its threhosld. 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 behaviour, thus becoming infected. 
-
+- for each of the susceptible node an unbalanced coin is flipped if the percentage of its neighbors that are already infected excedes its threhosld. 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 behaviour, thus becoming infected.
+- if the **blocked** status is enabled, after having rejected the adoption with probability ``blocked`` a node becomes immune to the infection.
+- every iteration ``adopter_rate`` percentage of nodes spontaneous became infected to endogenous effects.
 
 --------
 Statuses
@@ -23,18 +24,21 @@ Name         Code
 ===========  ====
 Susceptible  0
 Infected     1
+Blocked      -1
 ===========  ====
 
 ----------
 Parameters
 ----------
 
-=========  =====  ===============  =======  =========  =====================
-Name       Type   Value Type       Default  Mandatory  Description
-=========  =====  ===============  =======  =========  =====================
-threshold  Node   float in [0, 1]   0.1     False      Individual threshold
-profile    Node   float in [0, 1]   0.1     False      Node profile
-=========  =====  ===============  =======  =========  =====================
+============  =====  ===============  =======  =========  =====================
+Name          Type   Value Type       Default  Mandatory  Description
+============  =====  ===============  =======  =========  =====================
+threshold     Node   float in [0, 1]   0.1     False      Individual threshold
+profile       Node   float in [0, 1]   0.1     False      Node profile
+blocked       Model  float in [0, 1]   0       False      Blocked nodes
+adopter_rate  Model  float in [0, 1]   0       False      Autonomous adoption
+============  =====  ===============  =======  =========  =====================
 
 The initial infection status can be defined via:
 
@@ -76,7 +80,7 @@ Execute Simulation
 Example
 -------
 
-In the code below is shown an example of istantiation and execution of a Profile Threshold model simultion on a random graph: we set the initial infected node set to the 10% of the overall population, assign a profile of 0.25 and a threshold of 0.15 to all the nodes.
+In the code below is shown an example of instantiation and execution of a Profile Threshold model simulation on a random graph: we set the initial infected node set to the 10% of the overall population, assign a profile of 0.25 and a threshold of 0.15 to all the nodes.
 
 .. code-block:: python
 
@@ -90,6 +94,8 @@ In the code below is shown an example of istantiation and execution of a Profile
     # Model selection
     model = pt.ProfileThresholdModel(g)
     config = mc.Configuration()
+    config.add_model_parameter('blocked', 0)
+    config.add_model_parameter('adopter_rate', 0)
     config.add_model_parameter('percentage_infected', 0.1)
 
     # Setting nodes parameters

docs/reference/models/epidemics/SEIR.rst

@@ -77,8 +77,7 @@ Execute Simulation
 Example
 -------
 
-In the code below is shown an example of istantiation and execution of an SEIR simultion on a random graph:
-we set the initial set of infected nodes as % of the overall population, a probability of infection of 1%, a removal probability of 0.5% and an incubation period of 5% (e.g. 20 iterations).
+In the code below is shown an example of instantiation and execution of an SEIR simulation on a random graph: we set the initial set of infected nodes as % of the overall population, a probability of infection of 1%, a removal probability of 0.5% and an incubation period of 5% (e.g. 20 iterations).
 
 .. code-block:: python
 

docs/reference/models/epidemics/SEIS.rst

@@ -76,7 +76,7 @@ Execute Simulation
 Example
 -------
 
-In the code below is shown an example of istantiation and execution of an SEIS simultion on a random graph:
+In the code below is shown an example of instantiation and execution of an SEIS simulation on a random graph:
 we set the initial set of infected nodes as 5% of the overall population, a probability of infection of 1%, a removal probability of 0.5% and an incubation period of 5% (e.g. 20 iterations).
 
 .. code-block:: python

docs/reference/models/epidemics/SIR.rst

@@ -76,7 +76,7 @@ Execute Simulation
 Example
 -------
 
-In the code below is shown an example of istantiation and execution of an SIR simultion on a random graph: we set the initial set of infected nodes as 5% of the overall population, a probability of infection of 1%, and a removal probability of 0.5%.
+In the code below is shown an example of instantiation and execution of an SIR simulation on a random graph: we set the initial set of infected nodes as 5% of the overall population, a probability of infection of 1%, and a removal probability of 0.5%.
 
 .. code-block:: python
 
@@ -101,4 +101,4 @@ In the code below is shown an example of istantiation and execution of an SIR si
     iterations = model.iteration_bunch(200)
 
 
-.. [#] W. O. Kermack and A. McKendrick, “A Contribution to the Mathemat- ical Theory of Epidemics,” Proceedings of the Royal Society of London. Series A, Containing Papers of a Mathematical and Physical Character, vol. 115, no. 772, pp. 700–721, Aug. 1927
+.. [#] W. O. Kermack and A. McKendrick, “A Contribution to the Mathematical Theory of Epidemics,” Proceedings of the Royal Society of London. Series A, Containing Papers of a Mathematical and Physical Character, vol. 115, no. 772, pp. 700–721, Aug. 1927

docs/reference/models/epidemics/SIS.rst

@@ -75,7 +75,7 @@ Execute Simulation
 Example
 -------
 
-In the code below is shown an example of istantiation and execution of an SIS simultion on a random graph: we set the initial set of infected nodes as 5% of the overall population, a probability of infection of 1%, and a probability of recovery of 0.5%.
+In the code below is shown an example of instantiation and execution of an SIS simulation on a random graph: we set the initial set of infected nodes as 5% of the overall population, a probability of infection of 1%, and a probability of recovery of 0.5%.
 
 .. code-block:: python
 
@@ -100,4 +100,4 @@ In the code below is shown an example of istantiation and execution of an SIS si
     iterations = model.iteration_bunch(200)
 
 
-.. [#] W. O. Kermack and A. McKendrick, “A Contribution to the Mathemat- ical Theory of Epidemics,” Proceedings of the Royal Society of London. Series A, Containing Papers of a Mathematical and Physical Character, vol. 115, no. 772, pp. 700–721, Aug. 1927
+.. [#] W. O. Kermack and A. McKendrick, “A Contribution to the Mathematical Theory of Epidemics,” Proceedings of the Royal Society of London. Series A, Containing Papers of a Mathematical and Physical Character, vol. 115, no. 772, pp. 700–721, Aug. 1927

docs/reference/models/epidemics/SIm.rst

@@ -73,7 +73,7 @@ Execute Simulation
 Example
 -------
 
-In the code below is shown an example of istantiation and execution of an SI simultion on a random graph: we set the initial set of infected nodes as 5% of the overall population and a probability of infection of 1%.
+In the code below is shown an example of instantiation and execution of an SI simulation on a random graph: we set the initial set of infected nodes as 5% of the overall population and a probability of infection of 1%.
 
 .. code-block:: python
 
@@ -97,4 +97,4 @@ In the code below is shown an example of istantiation and execution of an SI sim
     iterations = model.iteration_bunch(200)
 
 
-.. [#] W. O. Kermack and A. McKendrick, “A Contribution to the Mathemat- ical Theory of Epidemics,” Proceedings of the Royal Society of London. Series A, Containing Papers of a Mathematical and Physical Character, vol. 115, no. 772, pp. 700–721, Aug. 1927.
+.. [#] W. O. Kermack and A. McKendrick, “A Contribution to the Mathematical Theory of Epidemics,” Proceedings of the Royal Society of London. Series A, Containing Papers of a Mathematical and Physical Character, vol. 115, no. 772, pp. 700–721, Aug. 1927.

docs/reference/models/epidemics/Threshold.rst

@@ -75,7 +75,7 @@ Execute Simulation
 Example
 -------
 
-In the code below is shown an example of istantiation and execution of a Threshold model simultion on a random graph: we set the initial set of infected nodes as 1% of the overall population, and assign a threshold of 0.25 to all the nodes.
+In the code below is shown an example of instantiation and execution of a Threshold model simulation on a random graph: we set the initial set of infected nodes as 1% of the overall population, and assign a threshold of 0.25 to all the nodes.
 
 
 .. code-block:: python

docs/reference/models/opinion/COD.rst

@@ -90,7 +90,7 @@ Execute Simulation
 Example
 -------
 
-In the code below is shown an example of istantiation and execution of a Cognitive Opinion Dynamics model simultion on a random graph: we set the initial infected node set to the 10% of the overall population, the external information value to 015, the B and T intervals equal to [0,1] and the fraction of positive/neutral/infected equal to 1/3.
+In the code below is shown an example of instantiation and execution of a Cognitive Opinion Dynamics model simulation on a random graph: we set the initial infected node set to the 10% of the overall population, the external information value to 015, the B and T intervals equal to [0,1] and the fraction of positive/neutral/infected equal to 1/3.
 
 .. code-block:: python
 

docs/reference/models/opinion/MajorityRule.rst

@@ -75,7 +75,7 @@ Execute Simulation
 Example
 -------
 
-In the code below is shown an example of istantiation and execution of a Majority Rule model simultion on a random graph: we set the initial infected node set to the 10% of the overall population.
+In the code below is shown an example of instantiation and execution of a Majority Rule model simulation on a random graph: we set the initial infected node set to the 10% of the overall population.
 
 .. code-block:: python