EMUAFCEXP - Emulates alternative forced-choice (AFC) experiments

Usage

par = emuafcexp(command,par);
[out,par] = emuafcexp('run',par);
[out, par] = emuafcexp('run',par,'plot');

Input parameters

`command`	One of the following commands. `'expinit'` intializes the general experiment parameters. `'signalinit'` intializes the signal generator creating model inputs. `'modelinit'` intializes model parameters. `'decisioninit'` intializes the parameters of the decision stage in the experiment. Finally, `'run'` runs the experiment and lets the model decide.
`par`	Structure of the experimental parameters used by `emuafcexp`. Set to `[]` on the first call (when `par` is not set up yet).

Output parameters

`par`	Structure containing all parameters
`out`	Vector with the experiment output. `out(:,1)` is the average threshold of the experimental variable. `out(:,2)` is the standard deviation of the variable across all runs. `out(:,3:end)` provides the individual experimental variables used in each trial.

Description

par = emuafcexp(init_command,par) initializes the various parts of the psychoacoustic experiment to be emulated depending on init_command.

out = emuafcexp('run',par) runs the experiment defined by the structure par and outputs the experimental result in out.

[out, par] = emuafcexp('run',par) runs the experiment and outputs more details on the experiment parameters in par.

[out, par] = emuafcexp('run',par,'plot') runs the experiment and plots the experiment progress.

Initialization

Experiment

par=emuafcexp('expinit',[],exp) initilizes the experiment wiht key-value pairs provided in a cell array exp. The following pairs are required:

`'intnum',intnum`	number of intervals in a trial, e.g. 3 sets up a 3-afc experiment.
`'rule',down_up`	vector with down-up-rule e.g. [2 1] sets up a 2-down, 1-up experiment.
`'expvarstart',expvarstart`
	step size of the experimental variable at the beginning of the experiment
`'expvarsteprule',factor_turns`
	vector with a factor and number of turn arounds. The factor affects the step size of the experimental variable after the number of turn arounds, e.g. [0.5 2] multiplies the stepsize by 0.5 after two turn arounds.
`'stepmin',min_threshturn`
	vector with minimal step size and number of turn arounds after reaching that minimal step size for the threshold calculation. E.g. [1 8] means that after reaching the step size 1, the experiment will continue for another 8 reversals before terminating.

Signal generator

par=emuafcexp('signalinit',par,sig) intializes the signal generator creating signals for the model with key-value pairs provided in the cell array sig. The signal generator is called with those parameters in each trial of the experiment. Up to 15 input parameters are supported. One of inputs must be 'inttyp': In each experimental interval, this input will be replaced by 'target' or 'reference' depending on the interval type. One of the inputs must be 'expvar': In each trial, this input will be replaced by the value of the experimental variable. The following pairs are required:

`'name',name`	string which defines the name of the signal generation
`'inputX',inputX`	input parameter X needed for the signal generator

Model called in each interval

par=emuafcexp('modelinit',par,mod) initializes the model called in each interval with the key-value pairs provided in mod. Up to 10 input parameters are supported. One of the inputs must contain the keyword 'expsignal'. This keyword is replaced in the 'run' routine with the output of the signal generation function:

`'name',name`	string which defines the name of the model function
`'inputX',intputX`	input parameter X needed by the model
`'outputs',outputs`	indicies of used model outputs for the decision e.g. [1 2 6]: output 1,2 and 6 used

Decision stage called in each trial

par=emuafcexp('decisioninit',par,dec) initializes the decision stage of the experiment with key-value pairs provided in dec. Up to 10 input parameters are supported. All inputs containing the keyword 'modelout' are replaced with the outputs of the model function during an experimental run. Therefore the number of inputs with the keyword 'modelout' must be equal to number of 'outputs' defined in 'modelinit'. An output of the modelfunction contains a cell with an entry for each interval. E.g. param1{1} contains the first output of the model function of the first interval and param3{2} contains the third output of the modelfunction of the second interval. Therefore the decision function must be implemented so that the inputs of the decision function are cells with entries for each interval. Following parameters are required:

`'name',name`	name of the decision fuction
`'inputX',intputX`	input parameter X needed by the decision function

Running the experiment

After the initialization, the experiment can be started by out = emuafcexp('run',par);. The threshold will be in out.

The Auditory Modeling Toolbox