Package: simcat
simcat: a Python package to Simulate Multi-agent Cognitive Association TasksThis 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 averbal fluency taskseither individually of following different interaction structures.
At present, the package includes two hard-coded rules: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);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:Strictturn-taking: agents alternate in naming the next item;Flexible(orcollaborative) turn-taking: agents are allowed to step in if the partner has no available associations from the current prompt;Shortest(orcompetitive) 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.:cherry_blossom:  ApplicationsApplications of this framework include simulation of verbal fluency data, as well as computational studies investigating emergent properties of parameters such ascognitive diversitybetween agents andturn-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 underpaper.:gear:  InstallationWe strongly recommend that you installsimcatfrom pip:pip install simcatYou can also installsimcatfrom source by running:pip install git+https://github.com/rbroc/simcat.gitorgit clone https://github.com/rbroc/simcat.git
cd simcat
pip3 install -e .:robot: :speech_balloon:  Running a simulationOnce you have installedsimcatcan easily run a simulation with the following command:fromsimcatimportInteraction,Agentagent_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):floppy_disk:  Simulation outputsA csv file containing a log of the interaction will be saved, whose first rows will look like this:agentturniterseedresponseprob_a0prob_a1thresholdnr_simmax_exchangesinit_seedlog_idnr_agentsresp_knnd_5_a0resp_knnd_5_a0_currentavg_dist_remain_a0avg_knnd_5_a0var_knnd_5_a0resp_neighbors_a0resp_neighbors_a0_currentresp_knnd_5_a1resp_knnd_5_a1_currentavg_dist_remain_a1avg_knnd_5_a1var_knnd_5_a1resp_neighbors_a1resp_neighbors_a1_currentagent_100catdog0.007820.01130.011792240cattest_2_agents20.009820.00990.012740.0110.0007183820.010530.010530.012730.010990.000727069agent_210doglion0.011360.008910.011792240cattest_2_agents20.010660.010660.012740.0110.0007150480.009890.010230.012740.0110.000729896agent_120lionelephant0.009380.012640.011792240cattest_2_agents20.009870.010070.012740.011010.0007181780.011480.011480.012740.0110.000721010agent_230elephantcoral_snake0.013170.010260.011792240cattest_2_agents20.010190.010190.012740.011010.0007146460.010540.010760.012740.0110.000724442agent_140coral_snakesea_snake0.008360.013680.011792240cattest_2_agents20.010450.010530.012740.011020.0007166650.010560.010560.012740.0110.000722726agent_250sea_snakecoyote0.01350.009190.011792240cattest_2_agents20.010710.010710.012740.011020.0007169670.010270.010360.012740.011010.000724038agent_160coyoterabbit0.009820.012010.011792240cattest_2_agents20.009870.010080.012750.011030.0007191860.011750.011750.012740.011010.0007277agent_270rabbitsquid0.012570.010780.011792240cattest_2_agents20.009550.009550.012750.011030.000754530.010830.010880.012740.011010.000735450agent_180squidcuttlefish0.008450.012530.011792240cattest_2_agents20.010110.010280.012750.011040.000753500.01080.01080.012740.011010.000735452agent_290cuttlefishgull0.013110.010270.011792240cattest_2_agents20.011640.011660.012750.011040.00071090.009820.009820.012740.011020.000728378The columns in the output refer to the following:namedescriptionagentname of agent speakingturnturn number within the simulationitersimulation numberseedseed at current turnresponseresponse to seedprob_a{n}Euclidean distance between seed and response in the n-th agent's space (Python indexing, therefore the index for the first agent is 0)thresholdstopping threshold for the simulationnr_simtotal number of simulations to runmax_exchangesmaximum number of turns within a simulationinit_seedfirst seed in the simulationlog_idid of the simulation, used in the logfilenr_agentsnumber of agentsresp_knnd_{k}_a{n}distance between the response and its k-th nearest neighbor (relative to the original semantic memory of the n-th agent) --kis passed as a parameter to theInteractioncall. This is an index of neighborhood density.resp_knnd_{k}_a{n}_currentsame as above, but computed on the updated space (i.e., accounting only for items that havenotbeen named)avg_dist_remain_a{n}average Euclidean distance between each pair of items that have notyetbeen named (relative to the semantic memory of the n-th agent).avg_knnd_{k}_a{n}Mean distance from k-th neighbor, for each item in the n-th agent's semantic space. Only items that havenotbeen named are considered.var_knnd_{k}_a{n}Std of the distance from k-th neighbor, for each item in the n-th agent's semantic space. Only items that havenotbeen named are considered.resp_neighbors_a{n}number of sub-threshold neighbors of the response item (relative to the semantic memory of the n-th agent)resp_neighbors_a{n}_currentnumber ofremainingsub-threshold neighbors of the response item (relative to the semantic memory of the n-th agent). Items are dropped from agents' semantic space as they are named.:hammer_and_wrench:  Maintenance and developmentPlease feel free to contribute to this project. You can contribute to bug fixes :bug: or implement new functionality :seedling: byopening a PRoropening an issue.
You are also very welcome to contributedocs, which are not yet available.:file_folder:  Project structuresimcat
├── LICENSE
├── pyproject.toml
├── README.md
├── img
├── paper      
│   ├── README.md            
│   ├── figures
│   ├── logs
│   ├── metrics
│   ├── models 
│   ├── notebooks 
│   └── scripts
├── sample                  
│   ├── agent_1
│   ├── agent_2
│   └── outs
├── src
│   └── simcat
└── tests:book:  CitationIf 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},
}