InformationTheoryTools

MABE provides a collection of tools built from Shannon Entropy. At its core, Shannon Entropy defines the amount of uncertainty present in a collection of states of a variable. If the order of the states of the variable is also known then multiple variables can be considered to determine if there are relationships between their states. The primary reason for these tools is to analyze brains, and while some of the functions (particularly in the Brain Infomation Tools section), the majority of these tools can be applied to data sets collected from other sources.

Information Theory Tools are divided into the following categories:

  TimeSeries - defines containers to hold variable states, and manipulate and display these states

  Entropy Functions - provides functions to calculate Entropy, Mutual (i.e. Shared) Entropy, Conditional Entropy, and Condition Mutual Entropy given Time Series.

  Smearing - provides functions to calculate Smearing, which is a measure of how much information individual nodes (in brains) know about some features, and how distributed or localized this information is

  Fragmentation - provides functions to determine how much how information is fragmented within networks (i.e. brains)

  State to State - converts TimeSeries into state to state visualizations

  Brain Infomation Tools - provides brain aware wrapper functions

World Builders Guide to using these tools

In order to use the information theory tools on brains, world builders must add the following:

You will need to include brainTools.h from Analyze at the top of your [world].h file. Note that because brainTools.h includes the other entropy function files, you do not need to include them as well, but can directly access their functions if needed.

#include "../../Analyze/brainTools.h"

Before agent evaluation begins every brain that will be analyzed must be told to start recording its activity:

[brain]->setRecordActivity(true);

If you wish to be able to calculate R or Smearing you will need to collect World State. A World State just a list of values that you decide are representative of the state of the world and which you want to compare to the states of brains. For every world update, you will need to collect the world state and add these to a list of states. World State information needs to be collected in a TS:intTimeSeires (a vector<vector> typedef).

TS::intTimeSeries worldStates;

Finally, you will need to add function calls to functions in brainTools.h or other information theory tools as needed.

BRAINTOOLS::saveStateToState(brain,"StateToState.txt");
BRAINTOOLS::getR(brain,WorldStates);

A note on time series discretization. The tools in BrainTools defaults to binary discretization. Unless a binary discretization works for you, you will need to learn about discretization methods. Information on TimeSeries discretization can be found in TimeSeries;

If you need to access brain states directly you can use the functions...

[brain]->getInputStates()
[brain]->getOutputtates()
[brain]->getHiddenStates()

Note that these functions return continuous value time series and must be discretized with a function like TS::remapToIntTimeSeries. Information on TimeSeries discretization can be found in TimeSeries;

If you need to reset a brains state recording use:

[brain]->resetStatesAndLifetimes()

Brain Builders Guide to using these tools

Brain developers are responsible for recoding brain states. For more information, check out Brain States and Life Times.