tomsup: Theory of Mind Simulation using Python

A Python Package for Agent-Based simulations. The package provides a computational eco-system for investigating and comparing computational models of hypothesized Theory of mind (ToM) mechanisms and for using them as experimental stimuli. The package notably includes an easy-to-use implementation of the variational Bayesian k-ToM model developed by Devaine, et al. (2017). This model has been shown able to capture individual and group-level differences in social skills, including between clinical populations and across primate species. It has also been deemed among the best computational models of ToM in terms of interaction with others and recursive representation of mental states. We provide a series of tutorials on how to implement the k-ToM model and a score of simpler types of ToM mechanisms in game-theory based simulations and experimental stimuli, including how to specify custom ToM models, and show examples of how resulting data can be analyzed.

📰 News

• v. 1.1.3
  • New plotting features were added
  • Speed and memory improvements as well as support for multicore simulations 🏎
  • Added workflows to ensure dependencies are being kept up to date
• v. 1.1.0
  • A speed comparison between the matlab implementation was introduced, showing the the tomsup implementation to be notably faster.
  • An extensive testsuite was introduced, for how to run it see the FAQ.
  • Code coverage was upped to 86% and code quality was raised to A.
  • A documentation site was introduced.
  • Added continiuous integration to ensure that the package always works as intended, with support for mac, windows and linux tests.
  • A new logo was introduced 🌟
• v. 1.0.0
  • tomsup released its first version along with a preprint on psyarxiv
  • A series of tutorials was introduced to get you started with tomsup

🔧 Setup and installation

tomsup supports Python 3.6 or later. We strongly recommend that you install tomsup from pip. If you haven't installed pip you can install it from the official pip website, otherwise, run:

pip install tomsup 

pip install git+https://github.com/KennethEnevoldsen/tomsup.git

git clone https://github.com/KennethEnevoldsen/tomsup.git
cd tomsup
pip3 install -e .

Getting Started with tomsup

To get started with tomsup we recommend the tutorials in the tutorials folder. We recommend that you start with the introduction.

The tutorials are provided as Jupyter Notebooks. If you do not have Jupyter Notebook installed, instructions for installing and running can be found here.

Tutorial	Content	file name	Open with
Documentation	The documentations of tomsup
Introduction	a general introduction to the features of tomsup which follows the implementation in the paper	paper_implementation.ipynb
Creating an agent	an example of how you would create new agent for the package.	Creating_an_agent.ipynb
Specifying internal states	a short guide on how to specify internal states on a k-ToM agent	specifying_internal_states.ipynb
Psychopy experiment	An example of how one might implement tomsup in an experiment	Not a notebook, but a folder, psychopy_experiment

🤔 Issues and Usage Q&A

To ask report issues or request features, please use the GitHub Issue Tracker. Otherwise, please use the discussion Forums.

FAQ

pip install -r requirements.txt
pip install pytest

python -m pytest

python -m pytest tomsup/tests/<DesiredTest>.py

pip install pytest-cov

python -m pytest--cov=.

# install sphinx, themes and extensions
pip install sphinx furo sphinx-copybutton sphinxext-opengraph

# generate html from documentations

make -C docs html

Using this Work

License

tomsup is released under the Apache License, Version 2.0.

Citing

If you use this work please cite:

@article{enevoldsen2020tomsup,
  title={tomsup: An implementation of computational Theory of Mind in Python},
  author={Enevoldsen, Kenneth C and Waade, Peter Thestrup},
  year={2020},
  publisher={PsyArXiv}
}