Add texts from paper

ModularNetworkModification.ipynb

@@ -4,7 +4,13 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "This example showcases highly modular use of defSim."
+    "## High-level modularity: Implementing a custom simulation order \n",
+    "\n",
+    "All the functions included in defSim can of course be used on their own, completely separate from the simulation framework posed here. Using lower-level defSim functions outside of the standard simulation loop may be considered defSim use with a high degree of modularity. This may be useful for those who wish to, for example, mix elements from the initialization and simulation stage, or implement exogenous shocks or idiosyncrasies into their model. In the example given in this notebook, we demonstrate one way in which lower level defSim functions can be used on their own. The simulation is initialized with a caveman graph network where *k* agents per cave create links to all other agents within one of *l* ’caves’ (Watts 1999). In this case, a network with *l*= 2 and *k* = 10 is created, as specified in the parameter dictionary (line 10 through 13 in code cell 3). \n",
+    "\n",
+    "The two caves are internally fully connected, and there are no ties connecting the two caves. The simulation runs for 40 steps (max_iterations on line 9 in code cell 3) under a bounded confidence influence function (specified on line 4). Next, the network isrestructured to create connections between the two caves using Maslov-Sneppen rewiring (Maslov & Sneppen2002). To apply the Maslov-Sneppen rewiring procedure, we can use a network modifier available in defSim which is part of the network_evolution_sim module (on line 20). The module is used by first creating an instance of the MaslovSneppenModifier with the proportion of rewired links as an initialization parameter, and then calling its rewire_network function on the simulation network. Of all ties in the simulation network, approximately 10% (rewiring_prop = 0.1) are rewired. We directly access the network on which the simulation takes place (my_simulation.network). After applying Maslov-Sneppen rewiring, new ties have been created. The in-fluence function used in this example requires knowledge of the opinion distance between connected agents.\n",
+    "\n",
+    "This opinion distance is stored as an attribute of each network tie.  The new ties we created currently lack this attribute (they are created without any attribute values).  Fortunately, the dissimilarity calculator used to calculate opinion distances in this simulation can also be accessed directly (on line 22). We call its calculate_dissimilarity_networkwide function to recalculate opinion distances between all connected agents. Finally, the simulation runs for another 40 iterations. Since the simulation is not reinitialized, agents retain their attribute values and network position. Now that network ties exist between the two caves, agents from both caves can (directly or indirectly) influence one another. Figure 5 shows that agents in each cave quickly converge to local consensus, while average opinions differ between the two caves. When the two caves are connected this leads to global consensus, which notably does not need to be located at the average of the local opinions of the two caves before rewiring."
    ]
   },
   {
@@ -669,7 +675,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.6.9"
+   "version": "3.6.5"
   }
  },
  "nbformat": 4,

README.md

@@ -3,17 +3,18 @@ defSim, examples
 
 Example scripts for defSim || Discrete Event Framework for Social Influence Models 
 
-- [defSim git repository](https://github.com/marijnkeijzer/defSim)
-- [documentation for defSim](https://marijnkeijzer.github.io/defSim)
+- [defSim git repository](https://github.com/defSim/defSim)
 
-New to defSim? [Learn how to use defSim in this quick introduction](https://marijnkeijzer.github.io/defSim/Introduction_to_defSim.html)
+New to defSim? [Learn how to use defSim in this quick introduction](https://defsim.github.io/defSim/Introduction_to_defSim.html)
 
-For a description of all of defSim's functions, see the [documentation](https://marijnkeijzer.github.io/defSim)
+For a description of all of defSim's functions, see the [documentation](https://defsim.github.io/defSim/)
 
-Included examples
+As defSim is a framework for social influence models, there are many different ways in which the package or it’s single components can be used. A way to think about the different uses of defSim is by organizing them by their degree of modularity. That is, the degree to which the users separates, reorganizes, or creates elements for their own simulation run. Low degree variations are typically well suited for teaching, illustrating, or replicating. Variations of implementations in the mid and high range of modularity may be more suited to researchers implementing novel ideas.
+
+This repository introduces examples for each level of modularity:
 -----------------
 
-- `ExperimentClass.ipynb` example of the use of the main 'Experiment' function, used to run many replications of simulation runs.
-- `SimilarityAdoption.ipynb` includes an implementation of the *SimilarityAdoption* influence function included in Axelrod's seminal 1997 JCR paper. 
-- `NewAttributeInitializer.ipynb` illustrates how you could program your own attribute initializer, following the defSim framework.
-- `ModularNetworkModification.ipynb` showcases a highly modular use of defSim splitting initialization and simulation to allow for network manipulation.
+- `ExperimentClass.ipynb` shows an 'out-of-the-box' use of defSim. This example introduces the use of the main 'Experiment' function, used to run many replications of simulation runs.
+- `SimilarityAdoption.ipynb` is another low modularity example which showcases the *SimilarityAdoption* influence function included in Axelrod's seminal 1997 JCR paper. 
+- `NewAttributeInitializer.ipynb` illustrates how you could program your own attribute initializer, following the defSim framework. This a more modular use-case of defSim.
+- `ModularNetworkModification.ipynb` showcases a highly modular use of defSim by splitting initialization and simulation to allow for network manipulation.