Home
Welcome to the PECSmodeler wiki!
The BehaviorSim toolkit is designed to follow a researcher's natural processes and help with each stage of creating a simulation. We have loosely divided the process of developing a model for simulation into the following five stages:
- think - Write out an explanation of your model. How does it work? What are the constructs involved? What kind of information is coming into the model?
- draw - Create an "information flow" path diagram to represent your theory. Draw the flow of information between constructs. What are the instreams to each, what are the outflows of each?
- specify - How exactly can each construct be calculated from the inflows? Use a fluid-flow analogy or linear combination to define a starting function and then adjust weights, delays, etc until the construct behaves as you think it should. Do lots of thought experiments. What should each step response look like? What should each impulse response look like?
- reconcile - Compare your simulation to real data. Compare individual data and group data. Compare the data at different time-scales. How can you adjust the constants in your model to match the data? Use semi-physical and grey-box model optimization methods. Specify which constructs are most important to match and which may be less important by adjusting the cost function.
- play - Explore all the 'what ifs' of your model. Use system identification techniques on data to inform your model. Is your model missing anything? Is there anything in the data which you cannot explain? Gain a rich understanding of what is going on even without 'p-values'.
These five steps form an iterative process that the researcher goes through repeatedly as depicted below:
The BehaviorSim toolkit breaks the process of creating a model and simulation into two parts 1) Setup of the behavioral model, environment, and simulation configuration and 2) Exploration of the simulation results. Scripts can be written for each of these two components. Thus, a researcher might create a simulation setup script to configure the experiment and he/she could perhaps use an existing exploration script to view his/her simulation results. Scripts can be easily saved and loaded so that different configurations or visualizations can be explored with minimal effort. The two script components work alongside the researcher's process as depicted below.
Setup and exploration can both be combined into one master script which can be used for running an entire experiment and analysis in one go. These scripts are stored in the behaviorSim/scripts/ directory. Example scripts are included in the behaviorSim/example_scripts/ directory.
It is recommended that you examine and run some of the sample scripts to begin. Doing this should be as easy as typing "python behaviorSimUI.py" into your console and then selecting an example script. It may take a minute or two, but hopefully you see no errors and you have just run your first behavioral simulation! (if you do have errors, please let us know on the issues page). You can open the .py files using a text editor and see exactly what they are doing to learn more about how you might use behaviorSim.
There are many ways in which you may configure the simulation. For ease of use, configuration (or setup) scripts can be at the highest level (configure the simulation and everything in it) or a script can be written to configure:
- the 'environment' to observe how an agent responds to certain stimuli
- the agent(s) themselves
- the simulation settings All tasks can be accomplished by loading a simulation configuration script, but sometimes it makes more sense to break down configuration into agent, environment, and settings setup scripts. To get started it is recommended you try modifying a copy of one of the example scripts.
The environment is an object which defines all things external to the agent. The agent interfaces with this environment by observing his/her context. If you are looking to observe how an agent behaves based on an external stimuli or you are trying to design an agent intervention, it is in the environment that you must define the stimuli or intervention.
Currently, the environment must be loaded prior to the agent(s), and is then passed to the agent constructor.
Agents can be configured in two distinct ways:
- modify agent personality
- modify agent psychology
WARNING: text below this point is not up-to-date and may not be correct.
The personality of an agent defines all constant values which may alter the agent's behavior. In order to change the personality of an agent, you must import the desired personality and then use "agent.state.setPersonality()". In order to create a new personality, it is recommended that you modify the contents of the default personality ".CSEL.agent_defaultPersonality.agent".
To modify agent psychology is to modify the theoretical basis for the agent simulation. You may want to do this if you are comparing different expressions of psychological theory or if you are looking to contribute to the current model. To do this, you need to know that the model calculates a numerical value for each 'psychological construct' in the model. The psychological constructs are organized into the categories 'context', 'state', 'motives', and 'behavior'. The way that each psychological construct's value is calculated is determined by a function associated with each construct. This means that in order to make a change in how body_temperature affects anger_level, the function of anger_level must be modified (this is an unimplemented example, by the way). Thus, if I have loaded 'agent1' using the default constructor, I can then use "agent1.state.anger_level.setFunction(,)" to set the method that anger_level is calculated for agent1. Below is a real-world example adapted from example_CSEL.py:
from src.environment.environment import environment
envmt = environment() # load default environment
from src.PECSagent.agent import agent
agent3 = agent(envmt)
#add disturbances
from src.PECSagent.state.CSEL.model_ddeint_firstOrder_withDisturbances import getEta
agent3.state.eta_PA.setFunction(getEta,agent3.inputs.xi_PA,agent3.state.agentPersonality,agent3.state.zeta_PA)in this example 'getEta' is the new function used for calculating 'eta_PA'. 'getEta' depends on the constructs 'xi_PA','agentPersonality', and 'zeta_PA', so these data objects are passed to setFunction as well.
An exploration script can do something as simple as printing out a value or as complex as creating an interactive environment. The goal is to tell a story with the data. You may be exploring the details of a particular agent, comparing populations of agents, or contrasting results in different environments. Not all simulation setup scripts will fit with all exploration scripts (for instance you cannot compare agents in a simulation with only one agent), but exploration scripts should attempt to explicitly state assumptions and print meaningful errors if they do not work with the given simulation setup.
Simulation result exploration scripts can be found in the behaviorSim/explorations/ directory.