<a href="https://github.com/KennethEnevoldsen/tomsup"><img src="https://github.com/KennethEnevoldsen/tomsup/raw/master/img/icon_black2.png" width="190" align="right" /></a>
# tomsup: Theory of Mind Simulation using Python
[](https://pypi.org/project/tomsup/)
[](https://pypi.org/project/tomsup/)
[](https://black.readthedocs.io/en/stable/the_black_code_style/current_style.html)
[](https://github.com/KennethEnevoldsen/tomsup)
[](https://github.com/KennethEnevoldsen/tomsup/blob/master/LICENSE)
[](https://github.com/KennethEnevoldsen/tomsup/actions)
[](https://KennethEnevoldsen.github.io/tomsup/)
[](https://www.codefactor.io/repository/github/KennethEnevoldsen/tomsup)
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)](http://dx.plos.org/10.1371/journal.pcbi.1005833). 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
- 7 March 2022
- Paper accepted at [Behavior Research Methods](https://link.springer.com/article/10.3758/s13428-022-01827-2) 2022
- v. 1.1.5
- New plotting features were added
- Speed and memory improvements as well as support for multicore simulations 🏎
- Added workflows to ensure dependencies are being updated
- Minor bugfixes
- v. 1.1.0
- A [speed comparison](missing) 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](https://KennethEnevoldsen.github.io/tomsup/) 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](https://psyarxiv.com/zcgkv/) on psyarxiv
- A series of [tutorials](https://KennethEnevoldsen.github.io/tomsup/using-tomsup) 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](https://pip.pypa.io/en/stable/installing/), otherwise, run:
```bash
pip install tomsup
```
<details>
<summary>Detailed instructions</summary>
You can also install it directly from GitHub by simply running:
```bash
pip install git+https://github.com/KennethEnevoldsen/tomsup.git
```
or more explicitly:
```bash
git clone https://github.com/KennethEnevoldsen/tomsup.git
cd tomsup
pip3 install -e .
```
</details>
## Getting Started with tomsup
To get started with tomsup we recommend the tutorials in the tutorials [folder](https://github.com/KennethEnevoldsen/tomsup/tree/master/tutorials). 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]( http://jupyter.org/install).
| Tutorial | Content | file name | Open with |
| -------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| [Documentation](https://kennethenevoldsen.github.io/tomsup/) | The documentations of tomsup | | |
| [Introduction](https://github.com/KennethEnevoldsen/tomsup/blob/master/tutorials/paper_implementation.ipynb) | a general introduction to the features of tomsup which follows the implementation in the paper | paper_implementation.ipynb | [](https://colab.research.google.com/github/KennethEnevoldsen/tomsup/blob/master/tutorials/paper_implementation.ipynb) |
| [Creating an agent](https://github.com/KennethEnevoldsen/tomsup/blob/master/tutorials/Creating_an_agent.ipynb) | an example of how you would create new agent for the package. | Creating_an_agent.ipynb | [](https://colab.research.google.com/github/KennethEnevoldsen/tomsup/blob/master/tutorials/Creating_an_agent.ipynb) |
| [Specifying internal states](https://github.com/KennethEnevoldsen/tomsup/blob/master/tutorials/specifying_internal_states.ipynb) | a short guide on how to specify internal states on a k-ToM agent | specifying_internal_states.ipynb | [](https://colab.research.google.com/github/KennethEnevoldsen/tomsup/blob/master/tutorials/specifying_internal_states.ipynb) |
| [Psychopy experiment](https://github.com/KennethEnevoldsen/tomsup/tree/master/tutorials/psychopy_experiment) | An example of how one might implement tomsup in an experiment | Not a notebook, but a folder, psychopy_experiment | [](https://github.com/KennethEnevoldsen/tomsup/tree/master/tutorials/psychopy_experiment) |
# 🤔 Issues and Usage Q&A
To ask report issues or request features, please use the [GitHub Issue Tracker](https://github.com/KennethEnevoldsen/tomsup/issues). Otherwise, please use the [discussion Forums](https://github.com/KennethEnevoldsen/tomsup/discussions).
## FAQ
<details>
<summary>How do I test the code and run the test suite?</summary>
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 requirements.txt.
```
pip install -r requirements.txt
pip install pytest
python -m pytest
```
which will run all the test in the `tomsup/tests` folder.
Specific tests can be run using:
```
python -m pytest tomsup/tests/<DesiredTest>.py
```
**Code Coverage**
If you want to check code coverage you can run the following:
```
pip install pytest-cov
python -m pytest--cov=.
```
</details>
<details>
<summary>Does tomsup run on X?</summary>
tomssup is intended to run on all major OS, this includes Windows (latest version), MacOS (Catalina) and the latest version of 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](https://www.sphinx-doc.org/en/master/index.html) to generate documentation. It uses the [Furo](https://github.com/pradyunsg/furo) theme with a custom styling.
To make the documentation you can run:
```
# install sphinx, themes and extensions
pip install sphinx furo sphinx-copybutton sphinxext-opengraph
# generate html from documentations
make -C docs html
```
</details>
# Using this Work
### License
tomsup is released under the [Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0).
### Citing
If you use this work please cite:
```bibtex
@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}
}
```
Raw data
{
"_id": null,
"home_page": "",
"name": "tomsup",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": "",
"keywords": "tom,theory-of-mind,game-theory",
"author": "Kenneth C. Enevoldsen and Peter T. Waade",
"author_email": "kennethcenevoldsen@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/1c/19/fa8ccd7268676a9ab31f927c8342074d691391c5a9fea36a032d1ee5a66a/tomsup-1.3.1.tar.gz",
"platform": null,
"description": "<a href=\"https://github.com/KennethEnevoldsen/tomsup\"><img src=\"https://github.com/KennethEnevoldsen/tomsup/raw/master/img/icon_black2.png\" width=\"190\" align=\"right\" /></a>\n\n\n# tomsup: Theory of Mind Simulation using Python \n\n[](https://pypi.org/project/tomsup/)\n[](https://pypi.org/project/tomsup/)\n[](https://black.readthedocs.io/en/stable/the_black_code_style/current_style.html)\n[](https://github.com/KennethEnevoldsen/tomsup)\n[](https://github.com/KennethEnevoldsen/tomsup/blob/master/LICENSE)\n[](https://github.com/KennethEnevoldsen/tomsup/actions)\n[](https://KennethEnevoldsen.github.io/tomsup/)\n[](https://www.codefactor.io/repository/github/KennethEnevoldsen/tomsup)\n\n\nA 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)](http://dx.plos.org/10.1371/journal.pcbi.1005833). 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.\n\n\n# \ud83d\udcf0 News\n\n- 7 March 2022\n - Paper accepted at [Behavior Research Methods](https://link.springer.com/article/10.3758/s13428-022-01827-2) 2022\n- v. 1.1.5\n - New plotting features were added\n - Speed and memory improvements as well as support for multicore simulations \ud83c\udfce\n - Added workflows to ensure dependencies are being updated\n - Minor bugfixes \n- v. 1.1.0\n - A [speed comparison](missing) between the matlab implementation was introduced, showing the the tomsup implementation to be notably faster.\n - An extensive testsuite was introduced, for how to run it see the FAQ.\n - Code coverage was upped to 86% and code quality was raised to A.\n - A [documentation](https://KennethEnevoldsen.github.io/tomsup/) site was introduced.\n - Added continiuous integration to ensure that the package always works as intended, with support for mac, windows and linux tests.\n - A new logo was introduced \ud83c\udf1f\n- v. 1.0.0\n - tomsup released its first version along with a [preprint](https://psyarxiv.com/zcgkv/) on psyarxiv\n - A series of [tutorials](https://KennethEnevoldsen.github.io/tomsup/using-tomsup) was introduced to get you started with tomsup\n\n# \ud83d\udd27 Setup and installation\n\ntomsup 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](https://pip.pypa.io/en/stable/installing/), otherwise, run:\n\n```bash\npip install tomsup \n```\n\n<details>\n <summary>Detailed instructions</summary>\n\n You can also install it directly from GitHub by simply running:\n ```bash\n pip install git+https://github.com/KennethEnevoldsen/tomsup.git\n ```\n\n or more explicitly:\n ```bash\n git clone https://github.com/KennethEnevoldsen/tomsup.git\n cd tomsup\n pip3 install -e .\n ```\n\n\n</details>\n\n\n## Getting Started with tomsup\nTo get started with tomsup we recommend the tutorials in the tutorials [folder](https://github.com/KennethEnevoldsen/tomsup/tree/master/tutorials). We recommend that you start with the introduction.\n\nThe tutorials are provided as Jupyter Notebooks. If you do not have Jupyter Notebook installed, instructions for installing and running can be found [here]( http://jupyter.org/install). \n\n\n| Tutorial | Content | file name | Open with |\n| -------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| [Documentation](https://kennethenevoldsen.github.io/tomsup/) | The documentations of tomsup | | |\n| [Introduction](https://github.com/KennethEnevoldsen/tomsup/blob/master/tutorials/paper_implementation.ipynb) | a general introduction to the features of tomsup which follows the implementation in the paper | paper_implementation.ipynb | [](https://colab.research.google.com/github/KennethEnevoldsen/tomsup/blob/master/tutorials/paper_implementation.ipynb) |\n| [Creating an agent](https://github.com/KennethEnevoldsen/tomsup/blob/master/tutorials/Creating_an_agent.ipynb) | an example of how you would create new agent for the package. | Creating_an_agent.ipynb | [](https://colab.research.google.com/github/KennethEnevoldsen/tomsup/blob/master/tutorials/Creating_an_agent.ipynb) |\n| [Specifying internal states](https://github.com/KennethEnevoldsen/tomsup/blob/master/tutorials/specifying_internal_states.ipynb) | a short guide on how to specify internal states on a k-ToM agent | specifying_internal_states.ipynb | [](https://colab.research.google.com/github/KennethEnevoldsen/tomsup/blob/master/tutorials/specifying_internal_states.ipynb) |\n| [Psychopy experiment](https://github.com/KennethEnevoldsen/tomsup/tree/master/tutorials/psychopy_experiment) | An example of how one might implement tomsup in an experiment | Not a notebook, but a folder, psychopy_experiment | [](https://github.com/KennethEnevoldsen/tomsup/tree/master/tutorials/psychopy_experiment) |\n\n\n# \ud83e\udd14 Issues and Usage Q&A\n\nTo ask report issues or request features, please use the [GitHub Issue Tracker](https://github.com/KennethEnevoldsen/tomsup/issues). Otherwise, please use the [discussion Forums](https://github.com/KennethEnevoldsen/tomsup/discussions).\n\n## FAQ\n\n<details>\n <summary>How do I test the code and run the test suite?</summary>\n\n\ntomsup 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 requirements.txt.\n\n\n```\npip install -r requirements.txt\npip install pytest\n\npython -m pytest\n```\n\nwhich will run all the test in the `tomsup/tests` folder.\n\nSpecific tests can be run using:\n\n```\npython -m pytest tomsup/tests/<DesiredTest>.py\n```\n\n**Code Coverage**\nIf you want to check code coverage you can run the following:\n```\npip install pytest-cov\n\npython -m pytest--cov=.\n```\n\n\n</details>\n\n\n\n\n<details>\n <summary>Does tomsup run on X?</summary>\n\n tomssup is intended to run on all major OS, this includes Windows (latest version), MacOS (Catalina) and the latest version of 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.\n\n \n</details>\n\n\n<details>\n <summary>How is the documentation generated?</summary>\n\n Tomsup uses [sphinx](https://www.sphinx-doc.org/en/master/index.html) to generate documentation. It uses the [Furo](https://github.com/pradyunsg/furo) theme with a custom styling.\n\n To make the documentation you can run:\n \n ```\n # install sphinx, themes and extensions\n pip install sphinx furo sphinx-copybutton sphinxext-opengraph\n\n # generate html from documentations\n\n make -C docs html\n ```\n \n</details>\n\n\n\n# Using this Work\n### License\ntomsup is released under the [Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0).\n\n### Citing\nIf you use this work please cite:\n```bibtex\n@article{waade2022introducing,\n title={Introducing tomsup: Theory of mind simulations using Python},\n author={Waade, Peter T and Enevoldsen, Kenneth C and Vermillet, Arnault-Quentin and Simonsen, Arndis and Fusaroli, Riccardo},\n journal={Behavior Research Methods},\n pages={1--35},\n year={2022},\n publisher={Springer}\n}\n```\n",
"bugtrack_url": null,
"license": "Apache License 2.0",
"summary": "An implementation of game theory of mind in a agent based framework following the implementation of Devaine, et al. (2017).",
"version": "1.3.1",
"split_keywords": [
"tom",
"theory-of-mind",
"game-theory"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "5d9da095f9b5ae3ac0fc493d3010c5a66370dfa561c28488bc81916c6116c99a",
"md5": "abf98bbb7eb0bd783af56b255c7e63ec",
"sha256": "a38b4b37ed5e7c1b4c16b9889e22ae0ed1bfb9bb218c1c9acd06a65b8357a4c6"
},
"downloads": -1,
"filename": "tomsup-1.3.1-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "abf98bbb7eb0bd783af56b255c7e63ec",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": ">=3.6",
"size": 42449,
"upload_time": "2023-01-31T11:57:21",
"upload_time_iso_8601": "2023-01-31T11:57:21.675388Z",
"url": "https://files.pythonhosted.org/packages/5d/9d/a095f9b5ae3ac0fc493d3010c5a66370dfa561c28488bc81916c6116c99a/tomsup-1.3.1-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "1c19fa8ccd7268676a9ab31f927c8342074d691391c5a9fea36a032d1ee5a66a",
"md5": "2a7a6d490a3da227beaeb20783c0ff2a",
"sha256": "dec18c81a42bf1991f5cee27998e8f93fedfe0456dc997e5ed688a67ebb64af0"
},
"downloads": -1,
"filename": "tomsup-1.3.1.tar.gz",
"has_sig": false,
"md5_digest": "2a7a6d490a3da227beaeb20783c0ff2a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 40803,
"upload_time": "2023-01-31T11:57:23",
"upload_time_iso_8601": "2023-01-31T11:57:23.029136Z",
"url": "https://files.pythonhosted.org/packages/1c/19/fa8ccd7268676a9ab31f927c8342074d691391c5a9fea36a032d1ee5a66a/tomsup-1.3.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-01-31 11:57:23",
"github": false,
"gitlab": false,
"bitbucket": false,
"lcname": "tomsup"
}
JSON