quoter-model 1.2

A package for simulating the quoter model of information flow on networks

Quoter Model

This repository is a packaged version of code using to simulate the quoter model as a model for social information flow [1]. The model was further explored and this code was further developed by Tyson Pond [2,3].

The quoter model offers an idealistic mechanism for how people communicate written information in online social contexts (i.e. tweets on Twitter or posts on Facebook). The model runs on a social network, where each node (user) takes turns generating a sequence of words by one of two mechanisms:

• (i) copying a segment of a random neighbor's past text with probability $q$
• (ii) randomly generating new text according to a vocabulary distribution.

We can then apply the cross-entropy (an information-theoretic measure which satisfies temporal precedence, referred to as hx in the code) to quantify information flow between each pair of users text.

Installation and usage

pip install quoter-model

Alternatively: clone the repository, and in the project root run

pip install .

This will appear in your list of installed packages as quoter-model, but included in a python script by import quoter.

The most relevant usage of this package, as shown in the examples, would be to run something like

from quoter.quoter_model import quoter_model_sim

and then run that function with relevant arguments.

Currently the simulation is dependent on the ProcessEntropy package which can have C-related install issues; a workaround for this (as detailed at that repo) is to first run

pip install --no-dependencies ProcessEntropy
pip install numba numpy nltk

Alternatively you can modify the source code inside quoter/quoter_model to use the local version of CrossEntropy.

Once you have run a reasonable number of simulations (in modules with a -sims suffix), you can run the corresponding -process scripts to generate some summary csv output (these and other helper modules are found in examples/processing/). Currently, all simulation and processing output will go into a folder output/ relative to your running directory (which you may need to create - I had some exceptions raised during testing), this is likely to change in future versions.

Example networks

Inside src/quoter/real_networks are many examples of real networks, along with a module for parsing them into an appropriate format, that can be used to run simulations on.

These have been compiled from different sources and are intended only as a starting point; other networks could be found, for example, at the online network repository.

An example usage of the real networks is calculating their so-called edge clustering coefficient in examples/edge_clustering.py.

Documentation

There are autogenerated html docs in docs/_build/html/index.html, produced by running make html inside docs/ (the makefile itself being auto-generate by after sphinx-quickstart).

Many of the docstrings are produced using docify so may need double checking. We intend to make these docs available online too.

Common abbreviations

• ER = Erdős–Rényi random graph
• BA = Barabási–Albert random graph
• WS = Watts–Strogatz (small-world) graph
• SBM = Stochastic Block Model

Requirements

Works with

• Python 3.6+
• [Networkx 1.11] Initially ran on this; now on 3.1 but in case you have any issues this would be why

See the requirements.txt file for further dependencies.

TODO

• Make sure all docstrings are in reST/sphinx format
• Add more helpful comments
• Make documentation better and available online
• Add more typing to function args
• Add verbose output to quoter_model_sim()
• Better syncing between simulation and processing scripts in the examples
• get_modularity is currently defined in two different files [redundant]

Repository structure

dist/ contains the distribution archives generated using python3 -m build, and are an alternative way of installing the package for local use

docs/ contains the auto-generated docs, as previously mentioned

src/ contains the actual package. I'm not too sure why it needs to be two levels down, but seems to work in any case

tests/ contains future tests for the package. As you can see, it is currently empty

All the files in the base directory (this one) are fairly self explanatory (except maybe pyproject.toml - at least it wasn't to me before I compiled this package - it is where pip gets its package metadata from).

References

[1] Bagrow, J. P., & Mitchell, L. (2018). The quoter model: A paradigmatic model of the social flow of written information. Chaos: An Interdisciplinary Journal of Nonlinear Science, 28(7), 075304.

[2] Pond, T. C. (2020). Measuring and Modeling Information Flow on Social Networks (Doctoral dissertation, The University of Vermont and State Agricultural College).

[3] Pond, T., Magsarjav, S., South, T., Mitchell, L., & Bagrow, J. P. (2020). Complex contagion features without social reinforcement in a model of social information flow. Entropy, 22(3), 265.