<a href="https://github.com/KennethEnevoldsen/tomsup"><img src="https://github.com/KennethEnevoldsen/tomsup/raw/main/img/icon_black2.png" width="190" align="right" /></a>

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.

🔧 Setup and installation

You can install tomsup using pip If you haven't installed pip you can install it from the official pip website, otherwise, run:

pip install tomsup 

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

<details> <summary>How do I test the code and run the test suite?</summary>

We recommend using uv to run the test as it also installs the required depencencies. tomsup comes with an extensive test suite. In order to run the tests, you'll usually want to clone the repository and build tomsup from the source. This will also install the required development dependencies and test utilities defined in the dev dependency group in the pyproject.toml.

# assuming you have downloaded the repository
uv run pytest

which will run all the test in the tomsup/tests folder.

Specific tests can be run using:

uv run pytest tomsup/tests/<DesiredTest>.py

Code Coverage If you want to check code coverage you can run the following:

uv run pytest--cov=.

</details> <details> <summary>Does tomsup run on X?</summary>

tomsup is intended to run on all major OS, this includes Windows, MacOS and Linux (Ubuntu). Please note these are only the systems tomsup is being actively tested on, if you run on a similar system (e.g. an earlier version of Linux) the package will likely run there as well.

</details> <details> <summary>How is the documentation generated?</summary>

Tomsup uses sphinx to generate documentation. It uses the Furo theme with a custom styling.

To make the documentation you can run:

# install required dependencies and builds the documentation
make build-docs

# view docs
make view-docs

</details>

Using this Work

License

tomsup is released under the Apache License, Version 2.0.

Citing

If you use this work please cite:

@article{waade2022introducing,
  title={Introducing tomsup: Theory of mind simulations using Python},
  author={Waade, Peter T and Enevoldsen, Kenneth C and Vermillet, Arnault-Quentin and Simonsen, Arndis and Fusaroli, Riccardo},
  journal={Behavior Research Methods},
  pages={1--35},
  year={2022},
  publisher={Springer}
}