simcat: a Python package to Simulate Multi-agent Cognitive Association Tasks

This is a Python package to perform simulations of multi-agent cognitive association tasks (e.g., the verbal fluency test).

The package makes it eary to instantiate one or more agents, endow them with a semantic memory, defined as a vector space that can be different across agents, and have agents perform association tasks in the form of a verbal fluency tasks either individually of following different interaction structures. At present, the package includes two hard-coded rules:

1. Agents always name the item in their semantic space which has the lowest distance from the prompt (or has the strongest association, depending on options);
2. The simulation stops when all items in the semantic space have been named during a simulation, or when no items in the semantic space can be found, whose distance from the current prompt is lower than (or higher than, depending on options) a set threshold, passed as a parameter to the simulation. These constraints could potentially be relaxed in future releases.

When multiple agents perform the association task together, they can interact following three possible turn-taking rules:

1. Strict turn-taking: agents alternate in naming the next item;
2. Flexible (or collaborative) turn-taking: agents are allowed to step in if the partner has no available associations from the current prompt;
3. Shortest (or competitive) turn-taking: the turn-holder is the agent with the shortest distance between the current prompt and the closest item in their semantic memory. The package is tested for single-agent and two-agent interactions, but it supports interactions with more than two agents. Furthermore, the package makes it possible to endow individual agents with basic forms of working memory, which make it possible to revert to previous prompts if no association from the current prompt is available.

For each simulation, a log of the entire association chain, including a range of metadata (e.g., the distance in semantic space between the prompt and the response item, or the density of the neighborhood in which named words are located), is produced and stored.

🌸 Applications

Applications of this framework include simulation of verbal fluency data, as well as computational studies investigating emergent properties of parameters such as cognitive diversity between agents and turn-taking structures.

A first study using this framework to investigate the effect of cognitive diversity on search behavior and performance in the association task was published in the proceedings of the 2022 Annual Meeting of the Cognitive Science Society (available at: https://escholarship.org/uc/item/58v5d82w):

@inproceedings{rocca2022cognitive,
  title={Cognitive diversity promotes collective creativity: an agent-based simulation},
  author={Rocca, Roberta and Tylén, Kristian},
  booktitle={Proceedings of the Annual Meeting of the Cognitive Science Society},
  volume={44},
  number={44},
  year={2022}
}

A follow-up involving comprehensive investigation of the effect of turn-taking structures and working memory flexibility is available as a preprint at: https://osf.io/preprints/psyarxiv/n3t6j, and currently under review.

@misc{rocca2024diversity,
  title={The effect of diversity and social interaction on cognitive search: An agent-based simulation},
  url={osf.io/preprints/psyarxiv/n3t6j},
  author={Rocca, Roberta and Tylén, Kristian},
  publishr={PsyArXiv},
  year={2024},
}

Materials and documentation concerning this study are available under paper.

⚙️ Installation

We strongly recommend that you install simcat from pip:

pip install simcat

You can also install simcat from source by running:

pip install git+https://github.com/rbroc/simcat.git

or

git clone https://github.com/rbroc/simcat.git
cd simcat
pip3 install -e .

🤖 💬 Running a simulation

Once you have installed simcat can easily run a simulation with the following command:

from simcat import Interaction, Agent

agent_1 = Agent(agent_name="agent_1", matrix_filename="sample/agent_1/matrix.tsv")
agent_2 = Agent(agent_name="agent_2", matrix_filename="sample/agent_2/matrix.tsv")

i = Interaction(
    agents=[agent_1, agent_2],
    save_folder="./sample/outs",
    log_id="my_interaction",
    nr_sim=2,
    map_locations=False,
)

i.run_interaction(seeds=["cat", "dog"], interaction_type="strict", n_back=0)

The columns in the output refer to the following:

🛠️ Maintenance and development

Please feel free to contribute to this project. You can contribute to bug fixes 🐛 or implement new functionality 🌱 by opening a PR or opening an issue. You are also very welcome to contribute docs, which are not yet available.

📁 Project structure

simcat
├── LICENSE
├── pyproject.toml
├── README.md
├── img
├── paper      
│   ├── README.md            
│   ├── figures
│   ├── logs
│   ├── metrics
│   ├── models 
│   ├── notebooks 
│   └── scripts
├── sample                  
│   ├── agent_1
│   ├── agent_2
│   └── outs
├── src
│   └── simcat
└── tests

📖 Citation

If you use this work, please cite:

@misc{rocca2024diversity,
  title={The effect of diversity and social interaction on cognitive search: An agent-based simulation},
  url={osf.io/preprints/psyarxiv/n3t6j},
  author={Rocca, Roberta and Tylén, Kristian},
  publishr={PsyArXiv},
  year={2024},
}