# 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](https://github.com/tobinsouth/ProcessEntropy/tree/master) 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](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](https://networkrepository.com/index.php).

An example usage of the real networks is calculating their so-called *edge clustering coefficient* in [examples/edge_clustering.py](src/quoter/examples/edge_clustering.py).

## Documentation
There are autogenerated html docs in [docs/_build/html/index.html](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.
