Updated tutorial, install section and models

soil_tutorial.ipynb

@@ -4,7 +4,14 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# SOIL Tutorial"
+    "<img src=\"logo_gsi.svg\" alt=\"Grupo de Sistemas Inteligentes\" width=\"100px\">"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# SOIL Tutorial "
    ]
   },
   {
@@ -31,6 +38,25 @@
     "+ __settings.py__: This file contains every variable needed in the simulation in order to be modified easily."
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Requirements"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "SOIL requires to install:\n",
+    "* **Python 3** - you can use the Conda distribution\n",
+    "* **NetworkX** - install with conda install networkx or pip install networkx\n",
+    "* **simpy** - install with pip install simpy\n",
+    "* **nxsim** - install with  pip install nxsim\n",
+    "* **Gephi** - Available at https://gephi.org"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},
@@ -54,7 +80,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 1,
+   "execution_count": 6,
    "metadata": {
     "collapsed": false
    },
@@ -90,7 +116,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 2,
+   "execution_count": 7,
    "metadata": {
     "collapsed": true
    },
@@ -121,7 +147,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 3,
+   "execution_count": 8,
    "metadata": {
     "collapsed": false
    },
@@ -164,7 +190,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 4,
+   "execution_count": 9,
    "metadata": {
     "collapsed": false
    },
@@ -207,7 +233,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 5,
+   "execution_count": 10,
    "metadata": {
     "collapsed": false
    },
@@ -282,7 +308,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 6,
+   "execution_count": 11,
    "metadata": {
     "collapsed": true
    },
@@ -325,7 +351,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 7,
+   "execution_count": 12,
    "metadata": {
     "collapsed": true
    },
@@ -388,7 +414,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 8,
+   "execution_count": 13,
    "metadata": {
     "collapsed": true
    },
@@ -529,6 +555,245 @@
    "source": [
     "This file contains all the variables that can be modified from the simulation. In case of implementing a new spread model, the new variables should be also included in this file."
    ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Model Library"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "To test this simulator in all the experiments we have used the Albert\n",
+    "Barabasi Graph [34] to automatically generate the network and the con-\n",
+    "nections among the agents due it is one of the most suitable graphs to\n",
+    "recreate social networks.\n",
+    "\n",
+    "Using different human behaviour models we will recreate the different\n",
+    "decisions of each agent.\n",
+    "\n",
+    "Moreover there are some parameters regarding the basic simulation that\n",
+    "have to be settled. In addition, more parameters will be needed depend-\n",
+    "ing on the spread model used for the experiment."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Spread Model M2"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "This model is based on the New Spread Model\n",
+    "M2 [1] which also refers to the cascade model [2]. Agents, usually Twit-\n",
+    "ter users, have three states regarding a rumour: neutral (initial state),\n",
+    "infected, vaccinated and cured.\n",
+    "\n",
+    "An agent becomes: infected when believes the rumour; vaccinated when is\n",
+    "influenced before being infected by a cured or already vaccinated agent\n",
+    "and cured when after becoming infected the agent is influenced by a\n",
+    "vaccinated/cured user.\n",
+    "\n",
+    "After a certain period of time, a random infected user develops an anti-\n",
+    "rumour and spreads it to its neighbours in order to vaccinate the neutral\n",
+    "and cure the infected ones.\n",
+    "\n",
+    "This model includes the fact that infected users who made a mistake\n",
+    "believing in the rumour will not be in favour of spreading theirs mistakes\n",
+    "through the network. Therefore, only vaccinated users will spread anti-\n",
+    "rumours. The probability of making a denier and becoming vaccinated\n",
+    "when a neutral user has an infected neighbour and the first already had\n",
+    "information about the rumour being false.\n",
+    "\n",
+    "* [1] E. Serrano and C. A. Iglesias. “Validating viral marketing\n",
+    "strategies in Twitter via agent-based social simulation”. In:\n",
+    "Expert Systems with Applications 50.1 (2016),\n",
+    "* [2] L. Weng et al. “Virality prediction and community structure\n",
+    "in social networks”. In: Scientific Reports 3 (2013)."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Control model M2,2"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "This model is based on the New Control Model\n",
+    "M2,2 [1]. It includes the use of beacons, special agents, that represent\n",
+    "an authority which can work against the rumour once it is detected. It\n",
+    "only has two states: on or off. Beacons will switch to on status when they\n",
+    "detect the misinformation in an infected neighbour agent.\n",
+    "Once the beacon is activated, they will try to cure and vaccinate other\n",
+    "agents starting a anti-rumour. Therefore this model also takes into ac-\n",
+    "count that infected users might not admit a previous mistake.\n",
+    "\n",
+    "* [1] E. Serrano and C. A. Iglesias. “Validating viral marketing\n",
+    "strategies in Twitter via agent-based social simulation”. In:\n",
+    "Expert Systems with Applications 50.1 (2016),"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### SISa Model"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "The SISa model of infection is already included in the simulator. Its the evolution of the classic disease spread Susceptible-Infective-Susceptible (SIS) model [1, 2].\n",
+    "\n",
+    "The SISa model is proposed by [3] and the main new feature is considering the spontaneous generation process of sentiment. This model has two assumptions: first, a susceptible agent who is close and more exposed to the infected has a higher probability of infection that other agent; second, the number of infected agents does not affect the probability of recovery.\n",
+    "\n",
+    "Based on some recent implementations of the SISa model [3], every agent can be in three states: neutral (initial), content and discontent.\n",
+    "\n",
+    "All the transitions between every different state are allowed depending on customizable probabilities. This model includes the fact that an agent will be more likely to change state as the number of neighbours with this state increases.\n",
+    "\n",
+    "* [1] P. Weng and X.-Q. Zhao. “Spreading speed and traveling waves for a multi-type SIS epidemic model”. In: Journal of Differential Equations 229.1 (2006)\n",
+    "\n",
+    "* [2] P. V. Mieghem. “Epidemic phase transition of the SIS type in networks”. In: A Letters Journal Exploring the Frontiers of Physics 97.4 (2012).\n",
+    "* [3] A. L. Hill et al. “Emotions as infectious diseases in a large social network: the SISa model”. In: Proceedings of the Royal Society of London B: Biological Sciences 277.1701 (2010),"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Big Market Model"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "As stated in several papers [2–4], social networks like Twitter are the perfect scenario to study the propagation of ideas, sentiments and marketing strategies. In this scenario several enterprises want to take advantage of social networks to promote their companies and connect with their clients.\n",
+    "\n",
+    "The goal of this model [1] is to recreate the behaviour of several enterprises in a social network. Following the example of HashtKat, we want to measure the effect of different marketing strategies in social networks.\n",
+    "Depending on the sentiment towards an enterprise the user will post positive or negative tweets about these enterprises. The fact that an user can increase its probabilities of posting a relevant tweet about a certain\n",
+    "company depending on its sentiment towards it is also considered.\n",
+    "In this model the number of enterprises as well as tweet rate probabilities of both companies and users can be changed.\n",
+    "\n",
+    "* [1] E. Serrano and C. A. Iglesias. “Validating viral marketing\n",
+    "strategies in Twitter via agent-based social simulation”. In:\n",
+    "Expert Systems with Applications 50.1 (2016)\n",
+    "* [2] B. A. Huberman et al. “Social Networks that Matter: Twitter\n",
+    "Under the Microscope”. In: Social Science Research Network\n",
+    "(2008).\n",
+    "* [3] M. Cha et al. “Measuring User Influence in Twitter: The\n",
+    "Million Follower Fallacy.” In: ICWSM 10.10-17 (2010),\n",
+    "* [4] M. Bulearca and S. Bulearca. “Twitter: a viable marketing\n",
+    "tool for SMEs?” In: Global business and management research\n",
+    "2.4 (2010),"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Sentiment Correlation Model"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "With this model we want to study\n",
+    "the influence of different sentiments in a social network. In order to do so, we base our model on the research made by [1]. In this paper the authors found out that in a social network (in this case Weibo) the correlation\n",
+    "of anger is significantly higher than joy and sadness meaning that the anger sentiment would occasionally spread faster than the others.\n",
+    "\n",
+    "They also confirmed some intuitive ideas such as a pair of users who have higher interactions are more likely to be influenced by each other, and that users with more friends would influence their neighbours more than other agents.\n",
+    "\n",
+    "In this simulation we have four emotions: anger, joy, sadness and disgust.\n",
+    "\n",
+    "Using the probabilities extracted from the dataset used by [1] we can visualise the graph and confirm the conclusions of the paper. Anger sentiment propagation rate is much higher than any other. Joy sentiment also spreads easily to the neighbours. However, sadness and disgust propagation rate is really small, few neighbours get affected by them.\n",
+    "\n",
+    "* [1] R. Fan et al. “Anger is More Influential Than Joy: Sentiment\n",
+    "Correlation in Weibo”. In: CoRR abs/1309.2402 (2013)."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Bass Model"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Even though Bass Model can be applied to many appli-\n",
+    "cations [57–60] it can be used to study the diffusion of information as\n",
+    "well.\n",
+    "This model is based on the implementation proposed by Rand and Wilen-\n",
+    "sky [13]. In this scenario there are only two states: unaware (initial) and\n",
+    "aware. For this simulation we assume that agents can only change status\n",
+    "from advertising (outside effects) and word of mouth (information inside\n",
+    "the network).\n",
+    "The probability of being affected by imitation (word of mouth effect)\n",
+    "increases as a function of the agent aware neighbours. In this model once\n",
+    "the user changes to aware status it remains in this state for the whole\n",
+    "simulation.\n",
+    "\n",
+    "* F. M. Bass. “A New Product Growth for Model ConsumerDurables”. In: Management Science 15.5 (1969),\n",
+    "W. Dodds. “An Application of the Bass Model in Long-TermNew Product Forecasting”. In: Journal of Marketing Research\n",
+    "10.3 (1973),\n",
+    "*  F. Douglas Tigert. “The Bass New Product Growth Model: A Sensitivity Analysis for a High Technology Product”. In: Journal of Marketing 45.4 (1981),\n",
+    "* Z. Jiang et al. “Virtual Bass Model and the left-hand data-truncation bias in diffusion of innovation studies”. In: International Journal of Research in Marketing 23.1 (2006), "
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Independent Cascade Model"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "As stated by Rand and Wilensky [1], the Independent Cascade Model [61] suits better the case we want to\n",
+    "study as it is more appropriate for social networks than the Bass Model.\n",
+    "\n",
+    "In this scenario we also have two states: unaware (initial) and aware. The new feature in this model is that one agent will only get infected once at least one neighbour became aware the previous time step. There is also\n",
+    "a probability of becoming aware by outside effects (innovation).\n",
+    "\n",
+    "This new feature can be explained intuitively, one agent will have more influence on another if the first just infected and wants to spread the new information he acquired.\n",
+    "\n",
+    "\n",
+    "* [1] W. Rand and U. Wilensky. An Introduction to Agent-Based Modeling: Modeling Natural, Social, and Engineered Complex Systems with NetLogo. MIT Press, 2015.\n",
+    "* [2] J. Goldenberg et al. “Talk of the Network: A Complex Systems Look at the Underlying Process of Word-of-Mouth”. In: Marketing Letters 12.3 (2001),\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Copyright"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "SOIL has been developed by the Intelligent Systems Group, Universidad Politécnica de Madrid, 2016-2017.\n",
+    " <img src=\"logo_gsi.svg\" alt=\"Grupo de Sistemas Inteligentes\" width=\"100px\">"
+   ]
   }
  ],
  "metadata": {
@@ -547,7 +812,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.4.0"
+   "version": "3.5.2"
   }
  },
  "nbformat": 4,