trecs 0.1.0

Framework for simulating sociotechnical systems

A simulator for sociotechnical systems. More details coming soon.

Install

This simulator supports Python 3.7+ and it has not been tested with older versions of Python 3. If you have not configured a Python environment locally, please follow Scipy’s instructions for installing a scientific Python distribution.

If you do not have Python 3.7+ installed, you can create a new environment with Python 3.7 by running the following command in terminal:

conda create --name py37 python=3.7

To ensure the example Jupyter notebooks run in your Python 3.7 environment, follow the instructions from this blog post. Note: you will also need pandas to run the example notebooks. As of December 2020, we recommend installing pandas v1.0.5 using the command: pip install 'pandas==1.0.5'. This will help avoid package conflicts between pandas and pylint if you also plan on contributing to trecs and running tests.

Currently, the simulator has only been tested extensively on MacOS 10.15 and Ubuntu 20.04.

To install the simulator, you will need the Python package manager, pip. After activating your virtual environment, run the following commands in a terminal:

git clone https://github.com/elucherini/t-recs.git
cd t-recs
pip install -e .

The command should automatically install all dependencies.

Tutorials

Examples of how to use the simulator can be found in the notebooks below:

• Quick start: start here for a brief introduction.

• Complete guide: an overview of the main concepts of the system.

• Advanced guide - building a model: an introduction to adding your own models on top of the system.

• Advanced guide - adding metrics: an example of how to add new metrics to a model.

Please check the examples directory for more notebooks.

Example usage

import trecs

recsys = trecs.models.ContentFiltering()
recsys.run(timesteps=10)
measurements = recsys.get_measurements()

Documentation

A first draft of the documentation is available here. In its current version, the documentation can be used as a supplement to exploring details in the code. Currently, the tutorials in examples might be a more useful and centralized resource to learn how to use the system.

Contributing

Thanks for your interest in contributing! Check out the guidelines for contributors in CONTRIBUTING.md.