README.md

In nicolemunoz99/multisensory: Predicting the conditions under which multisensory integration is favored

multisensory

The package multisensory is the model in Munoz & Blumstein that predicts the conditions that favor multisensory integration. We refer those interested in the mathematical details of the model to this manuscript. The purpose of this README is to show you how to use this package for making testable predictions as to the conditions under which an animal should integrate multisensory stimuli.

Installation

You can install multisensory from GitHub with:

# install.packages("devtools")
devtools::install_github(“nicolemunoz99/multisensory”)

Model background

| Notation in Munoz & Blumstein | Notation in R-package “multisensory” | | :---------------------------- | :----------------------------------- | | P-PRED | prior.b | | B-NONE | bb.a | | B-PRED | bb.b | | U1 | u1 | | U2 | u2 | | S1 | s1 | | K1 | k1 | | K2 | k2 |

Animal can do 1 of 2 behaviors: forage or hide. It is initially foraging.

The world that can be in 1 of 2 states: a non-threat is present (state-a) or a predator is present (state-b). The animal has some prior estimate for the probability of a predator being present, prior.b

When a non-threat is present, animal receives greatest benefit for foraging (bb.a). When a predator is present, animal receives greatest benefit for hiding behavior (bb.b).

Animal receives two, sequential stimuli. Each stimulus has the property of possibly originating from a predator or a non-threat. The probability function in each state is a normal Gaussian distribution. The proportion of overlap of the probability distributions of each state is defined as “uncertainty”. The mean magnitude of a stimulus originating from a predator is positive. The mean magnitude of a stimulus originating from a non-threat is negative.

The first stimulus has uncertainty u1. This stimulus has some value to the animal, called the value of information (Stephens DW. 1989. Variance and the value of information. American Naturalist 134:128-140), that is a function of the animal’s prior, the benefits it receives when engaging in each behavior, and the cost of attending to the stimulus, k1.

Value of information = f(prior.b, bb.a, bb.b, u1, k1)

When the value of information is positive, the animal will incorporate that information into its decision as to whether to continue foraging or to hide. The animal then updates its prior according Bayes’ theorem based on the magnitude of the first stimulus it receives, s1.

The animal receives a second stimulus in a different sensory modality having uncertainty u2. The animal calculates the value of information using its updated prior and u2. If the value of information is greater than zero, then the animal will incorporate the information into its decision as to whether it should forage or hide. When the value of information of the 1st and 2nd stimuli are both greater than zero, then the animal is said to have integrated.

Thus, multisensory integration is a function, g(prior.b, bb.a, bb.b, s1, u1, k1, u2, k2).

Function voi

The function voi takes a set of parameter values and calculates the value of information for two sequential stimuli, calculates the value of information and determines which stimuli (if any) were used. The output is a list with the following components:

| Component name | Interpretation | | :------------- | -------------------------------------------------------------------------------------------------------------- | | int1 | Answer to the question: Was the 1st stimulus used? T/F | | vi.1 | Value of information of the 1st stimulus. | | int2 | Answer to the question: Was the 2nd stimulus used? T/F | | vi.2 | Value of information of the 2nd stimulus. | | st.use | 0: neither stimulus used. 1: only 1st stimulus used. 2: only 2nd stimulus used. 3: integration. |

Function aplot

The function aplot creates grids (using the function image from package graphics) from the component st.use from the output of voi for user-specified parameter values. If we look at parameter area bb.a x bb.b, for example, for certain values of prior.b, s1, u1, k1, u2, and k2 we can use voi to see for what parameter values the animal will integrate. Munoz & Blumstein define proportion of the area bb.a x bb.a over which the animal integrates as the “favorability of integration”. By varying, for example, prior.b, we can see how this proportion changes with prior.b.

aplot requires a list having length, structure and names equal to favint.empty. favint.empty has 8 components (one for each parameter), each of which contains two components, one named “parameter” and one named “value”. The names of the 8 components must equal c(“COL”, “DIM1”, “DIM2”, “CONST1”, “CONST2”, “CONST3”, “CONST4”, “CONST5”). These names specify how each parameter is represented in the graphs.

| Plot dimension | Parameter varies | | :------------- | ---------------- | | DIM1 | …along x-axis | | DIM2 | …along y-axis | | COL | …between plots | | CONST1 | Constant | | CONST2 | Constant | | CONST3 | Constant | | CONST4 | Constant | | CONST5 | Constant |

The “parameter” components dictate what parameter you want to be represented on each plot dimension, must be of type character, and must be one of the following parameter names: “prior.b”, “bb.a”, “bb.b”, “s1”, “u1”, “k1”, “u2”, “k2”. Furthermore, each parameter must be named exactly once. The “value” component specifies the value(s) to be plotted.

The number of plots produced is equal to the vector length of COL$value. The favorability of integration (A) for a given plot is provided in the title, and the values of parameters constant within a plot are annotated to the right of the plot. The list favint.ex1 has been provided to demonstrate aplot.

# example of using aplot with the provided list favint.ex1
library(multisensory)
aplot(favint.ex1)

Function oiplot

The function oiplot produces plots for qualitatively assessing the sensitivity of the favorability of integration and for making testable predictions as to the conditions under which multisensory integration is favored. Users can input what parameters are varied along each plot dimension.

oiplot requires a list having length, structure and names equal to optint.empty. optint.empty has 8 components (one for each parameter), each of which contains two components, one named “parameter” and one named “value”. The names of the 8 components must equal c(“COL”, “ROW”, “SER”, “DIM1”, “DIM2”, “CONST1”, “CONST2”, “CONST3”). These names specify how each parameter is represented in the graphs.

| Plot dimension | Parameter varies | | :------------- | ------------------------------------------------------------------------------------- | | COL | …along x-axis | | ROW | …between plots | | SER | …between lines within a graph | | DIM1 | …along one dimension of area from which “favorability of integration” is calculated | | DIM2 | …along other dimension of area from which “favorability of integration” is calculated | | CONST1 | Constant | | CONST2 | Constant | | CONST3 | Constant |

The “parameter” components assign what parameter you want to be represented on each plot dimension, must be of type character, and must be one of the following parameter names: “prior.b”, “bb.a”, “bb.b”, “s1”, “u1”, “k1”, “u2”, “k2”. Furthermore, each parameter must be named exactly once. The “value” component specifies the value(s) to be plotted. The number of plots produced is equal to the vector length of ROW$value. The values of parameters constant within a plot are annotated to the right of the plot. The lists optint.ex1 and optint.ex2 have been provided to demonstrate oiplot.

# example of using oiplot with included list optint.ex1
oiplot(optint.ex1)

oiplot evaluates voi within a for-loop. So, depending on the length of vectors you specify, the calculations can take some time. The following table should guide your inputs in order to keep cpu time down.

| Plot dimension | Max recommended length for processing time | | :------------- | ------------------------------------------ | | COL | 15 | | ROW | \< 4 | | SER | 3 | | DIM1 | 20 | | DIM2 | 20 | | CONST1 | 1* | | CONST2 | 1* | | CONST3 | 1* |

*CONST1, CONST2, CONST3 must be of length 1

nicolemunoz99/multisensory documentation built on June 29, 2019, 2:51 p.m.