quoter-model 1.3.2
A package for simulating the quoter model of information flow on networks
Requires Python: >=3.7

# Quoter Model
This repository is a packaged version of code using 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
```
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`. 

See the examples for ideas on experiments to run, parameters to vary in simulations, etc.

## 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) or [ICON](https://icon.colorado.edu/#!/).

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). Example simulations for different parameters of ER, BA, WS, SBM networks are also found in the [examples directory](src/quoter/examples/), which is initialised as a module and can therefore be called in scripts.

Note also that the simulation currently only works with uniformly weighted networks. An extension would be to use edge weights either as non-uniform quoting probabilites, or once an ego has "decided" to quote, to choose from its predecessors preferentially based on the connecting weights.

## 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. The docs are also now available at [readthedocs](https://quoter-model.readthedocs.io/en/latest/), and this is configured to re-build every time the github repo is pushed to, however it does not seem to be hosting the same html as I get locally! If anyone knows how to solve this please let me know:)

### 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. Note that for some advanced use of the `networkx` package, which may be included within `quoter`, it may be helpful to run `pip install networkx[default]`

## TODO
+ Make sure all docstrings are in reST/sphinx format
+ Add more helpful comments
+ Make documentation better and available online [crude version available online at quoter-model.readthedocs.io]
+ Add more typing to function args
+ Add verbose output to quoter_model_sim() [done, needs testing/improving]
+ Better syncing between simulation and processing scripts in the examples [done]
+ get_modularity is currently defined in multiple different files, giving redundancies

## 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.